Repository navigation
Question: defining strict error schemas #392
Description
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[].dataattribute of an OpenRPC schema - add a custom global-scoped flag, i.e.
x-error-data-schema: boolwhich indicates should thedataproperty 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'dataattribute 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:
- Is our approach with adding
x-error-data-schemaa legit and intended/idiomatic way of expanding the spec? - Should we propose a spec update?
Reacted by smagafurov and Zane Starr
Activity
github-actions commentedon Nov 20, 2024
Welcome to OpenRPC! Thank you for taking the time to create an issue. Please review the guidelines
zcstarr commentedon Jul 27, 2025
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 commentedon Dec 17, 2025
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