Question: defining strict error schemas

[qweeze]

We use errors[].data field to pass detailed errors to client, like so:

{
    "jsonrpc": "2.0",
    "error": {
        "code": 6000,
        "message": "Invalid parameters",
        "data": {
            "errors": [
                {
                    "code":"wrong_code",
                    "path": "sms_code",
                    "message": "Verification code mismatch"
                },
                {
                    "code":"wrong_payee_id",
                    "path": "payments[2].payee",
                    "message": "Invalid payee ID"
                }
            ]
        }
    },
    "id": 42
}

We'd like to be able to specify JSON schemas for these (inner) errors, without violating the OpenRPC spec or breaking backwards compatibility. We've come up with the following approach:

• put the JSON schemas of inner errors in the errors[].data attribute of an OpenRPC schema
• add a custom global-scoped flag, i.e. x-error-data-schema: bool which indicates should the data property of errors be treated as a schema or not. If the flag is set, all the related tools (validators, code generators, documentation viewers) should assume that error responses' data attribute is constrained with these schemas and act accordingly.

Alternatively, the spec itself could probably be updated to support defining specific schemas for errors. I might be wrong but it feels like a nice-to-have feature that could come in handy not only for our use case. As for implementation, adding a separate dedicated attribute like errors[].data-schema should suffice.

To sum up, my questions are:

1. Is our approach with adding x-error-data-schema a legit and intended/idiomatic way of expanding the spec?
2. Should we propose a spec update?

[github-actions]

Welcome to OpenRPC! Thank you for taking the time to create an issue. Please review the guidelines

[zcstarr]

Sorry for the late response here :) .

Actually that would be a good approach to spec things out with x-error-data-schema @shanejonas and I have been talking about error codes including an data-schema, so you can pattern match data field against it. We've been actually working on an extension to the spec x-error-groups, which expands the ability to group errors as classes, and not having a schema for the data coming back is definitely a valid concern.

We started moving our tooling into a mono repo, and have been working on a roadmap of upcoming concerns, I think this might help you directionally by looking at error group implementation

https://github.com/open-rpc/tools/tree/main/packages/extensions

Recently we added support for extensions to be defined to be valid everywhere. The best way to check the schema extension validity is to use schema-utils.

I'll give it some more thought as well as to where the x-error-data-schema would live, but I think that would be the right place to start, the goal eventually would be if the extension is found useful enough we'd support it into the spec. That process still hasn't been formalized but soon :D

[jeremyfiel]

I would recommend looking at RFC9457 Problem JSON
https://www.rfc-editor.org/rfc/rfc9457.html

Quite a few OpenAPI definitions have used this with much success