Support Error Code

[jugaadi]

Since error messages are not standardised across implementations, it is difficult to share the exact error. Moreover, these error messages can change over time(depending on the library), thus, introducing breakages in implementations. Such breakages can break translations, formatting, etc for the end user.

Example: Server validation output format being passed to client validator.

Suggestions:

1. Current error node in output format can point to error code instead of the message.
2. title and description annotations can be used to add more details of the error.
3. Standardise error code format(similar to SQLSTATE).
4. Introduce error code classes(similar to SQLSTATE) for each constraint type.

Prior art:

1. HTTP Error Codes
2. Typescript Error Codes
3. Postgres Error Codes

[gregsdennis]

Can you give an example that knowing the keyword that produced the error doesn't solve that an error code would?

(I realize that "keyword" isn't a property in the output unit, but check out #1249, which restructures the output unit so that the keyword is actually the key in an errors property.)

[jugaadi]

The motivation here is to depend on a pre-defined(provided in spec) set of error codes rather than implementation specific error language(English) dependent details. In the new format too, the usage of detailed string instead of code(numeric/short string) is prone to the above issue.

Doubts wrt new format:

1. If a keyword constraint can result in only one type of error, then isn't an array of keywords enough since the keyword location is already available?
2. Can you share an example of error object in the new format which fails patternProperties constraint?

[gregsdennis]

The motivation here is to depend on a pre-defined(provided in spec) set of error codes rather than implementation specific error language(English) dependent details.

Again, what's the difference between an "error code" and just using the keyword. (Asked another way, what if the error code was the keyword?)

If a keyword constraint can result in only one type of error,

Yes, keywords only result in a single type of reportable error (at least so far as we've seen). Theoretically, a vocabulary could be created which defines a keyword that could fail in multiple ways, but such a thing is generally advised against.

then isn't an array of keywords enough since the keyword location is already available?

If you want to only look at the keys, then that's fine, but having human-readable messages from implementations (and especially being able to customize them) is frequently requested. We won't standardize error message wording, but we definitely can require (or strongly suggest) that an implementation provide one or provide means for clients to define their own. (My implementation allows customization and even internationalization.)

Can you share an example of error object in the new format which fails patternProperties constraint?

patternProperties itself doesn't produce any errors, but its subschemas do. It's output would be just like properties, which you can see in this sample

Effectively, for the hierarchical (proposed to replace detailed and verbose), output units have nested units for subschemas.

[jugaadi]

Theoretically, a vocabulary could be created which defines a keyword that could fail in multiple ways, but such a thing is generally advised against.
...
...
but we definitely can require (or strongly suggest) that an implementation provide one or provide means for clients to define their own.

This should work out for our use case.

Thanks @gregsdennis . Shall I close this issue?

[handrews]

Since the original filer suggested closing this almost a month ago with no further commentary, I'm going to go ahead and close it. It looks like the discussion is resolved to me.