JSON Data Errors Response (JDER)

The JSON Data Errors Response (JDER) specification defines a standardized structure for JSON responses that can be used for both success and failure scenarios.

Structure

The following is the structure of the response.

Root Structure

The root structure is a JSON object with the following fields:

Field	Type	Description
success	Boolean	Indicates whether the response is successful or not
data	Any	Contains the requested information
errors	Array	Contains a list of errors

success Field

The success field indicates whether the response is successful. However, it can be omitted if the HTTP status code is already used to convey this information, as shown in the examples below:

Success response (HTTP Status: 200):

{
    "data": {
        "message": "Hello, World!"
    }
}

Failure response (HTTP Status: 404):

{
    "errors": [
        {
            "code": "not_found"
        }
    ]
}

data Field

The data field contains the requested information when success is true.

errors Field

The errors field contains a list of errors when success is false.

Field	Type	Description
code	String	Code representing the error
path	Array	Indicates where the error occurred
message	String	Detail of the error

Each API should define a set of error codes for consistent error handling across clients. For example, a parsing error may use the code parse, a timeout error may use the code timeout, and so on.

The path array indicates the exact location in the data structure where the error occurred. Each element represents a property name or array index.

Examples

Below are examples of both success and failure responses:

Success Response

A basic success response:

{
    "success": true
}

A success response that returns a single object in the data field:

{
    "success": true,
    "data": {
        "message": "Hello, World!"
    }
}

A success response that returns a list of items in the data field:

{
    "success": true,
    "data": [
        {
            "id": 1,
            "name": "John"
        }, 
        {
            "id": 2,
            "name": "Jane"
        }
    ]
}

Failure Response

A failure response with only the code field:

{
    "success": false,
    "errors": [
        {
            "code": "not_found"
        }
    ]
}

A failure response representing an internal server error:

{
    "success": false,
    "errors": [
        {
            "code": "server",
            "message": "Internal server error"
        }
    ]
}

A failure response representing a parsing error:

{
    "success": false,
    "errors": [
        {
            "code": "parse",
            "path": [
                "json",
                "name"
            ],
            "message": "Invalid input: expected string, received number"
        }
    ]
}

A failure response representing multiple parsing errors:

{
    "success": false,
    "errors": [
        {
            "code": "parse",
            "path": [
                "json",
                "name"
            ],
            "message": "Invalid input: expected string, received number"
        },
        {
            "code": "parse",
            "path": [
                "json",
                "age"
            ],
            "message": "Invalid input: expected number, received string"
        }
    ]
}

License

This project is licensed under the terms of the MIT license.