Proposal: Standardize validation error and introduce new keyword messages

[TeCHiScy]

Standardize validation error

When using jsonschema in validating user's input (e.g. in a html form), usually we want to give users friendly/multilingual/custom error messages. Futhermore, the error message may include some validation params.
Take the minLength keyword as example, two validation params are available for sure:

1. the length of the input string ($a)
2. the minLength defined in the schema ($b)

With those two params, we can form various error messages like:

1. Need at least $b characters
2. Need at least $b characters, $a given
3. ... etc.

Considering the usage described above, I proposal to standarlize params that a validation error must give, including the type and the meaning. e.g.,

As for minLength,

1. the length of the input string (should be number)
2. the minLength defined in the schema (should be number)

As for minimum,

1. the actual input number (should be number)
2. the minimum defined in the schema (should be number)

and so on.

In a word, the proposal can be regarded as "Standardize and structuring the validation error".

A new keyword messages

Based on the structuralized error, I propose to add a new keyword, let me call it messages. This keyword is used to define templates for formating errors. It looks like:

{
  "type": "string",
  "minLength": 2,
  "messages": {
    "default": "the string is wrong",
    "minLength": "the string is too short, must have $a charaters"
  }
}

There are two keys in the messages keyword, default and minLength. When a validation error occurs, the validator should use corresponding error message template defined in the messages keyword to format the error.

e.g., if the error is caused by minLength keyword, then,

• template minLength in the messages should be used.
• If no corresponding template is defined, then the default template should be used.
• If the default template isn't present, then validators can format the error as they want.

Without the proposed messages keyword, it will be very hard for developers to format error messages as they want, especially in the circumstance that developers won't be able to get the validation params as mentioned above. By the way, error message are ususually tied closely to a specific schema, that's why I propose to embed messages in the schema itself.

Finally, if there's a duplicate issue, please let me know, thanks.

[TeCHiScy]

maybe related: https://github.com/orgs/json-schema-org/discussions/63

[awwright]

The tag for this is localization, and another related issue might be #743. Although "localization" normally implies "translating for one language & culture from another", in the case of JSON Schema, there might not be any localization (the only output format is for machines), and we're trying to create one from scratch.

In addition to multiple locales, you have to accommodate multiple interfaces. For example, a response from an API isn't going to be the same as an error in a form.

[TeCHiScy]

In addition to multiple locales, you have to accommodate multiple interfaces. For example, a response from an API isn't going to be the same as an error in a form.

Yes, when multiple APIs share a same schema, to accommodate these APIs, it's better not to put messages in the schema itself. But I think it still important to standardize validation error, and output the keyword that causes the error as well as the params used in validation. With these information, we can format error messages on our own.

[gregsdennis]

The current output formats already specify the keyword. Moreso, they specify the location of the keyword.

We've gone back and forth on inclusion of specific wording. I do appreciate the thought you've put into the messages keyword, though.

For my implementation, json-everything, I have added support for defining custom error messages, including support for language packs (though I only have Spanish defined for now).

This is currently an implementation-defined thing, though, so your mileage may vary with other libraries.

[TeCHiScy]

The current output formats already specify the keyword. Moreso, they specify the location of the keyword.

Yes, I see. I'd appreciate if there's also a seperate keyword, otherwise I will need to split the location and get the last item of the location to know the specific keyword (if I want to match error message using the keyword).

For my implementation, json-everything, I have added support for defining custom error messages, including support for language packs (though I only have Spanish defined for now).

Great feature, that's what I really want, buy sadly I'm using some other lib in golang (https://github.com/santhosh-tekuri/jsonschema). So, this proposal is to make this feature a specification, so that all the implementations behave the same, including the keyword of error messages, the placeholder in an error message (i.e., [[received]], [[limit]]).

We've gone back and forth on inclusion of specific wording. I do appreciate the thought you've put into the messages keyword, though.

In my usage, I won't share a schema between multiple APIs, so embedding messages into the schema looks charming to me. However, if consider that:

• the schema is shared between APIs, and each APIs should return different message,
• not to include specific wording in the schema,
• formatting is also implemention-specific, and can leave to users to use the appropriate tools

I propose to standardize and structuring the validation error (the first part of the proposal), and output them, like:

{
  "valid": false,
  "keyword": "minLength",
  "keywordLocaation": "#/description",
  "xxx": {
    "received": 1,
    "limit": 3
  },
  "schemaLocation": "https://example.com/mySchema#/description",
  "instanceLocation": "",
  "annotation": "description"
}

so users can format their own messages. Here xxx should be a better name.

[gregsdennis]

Please start a new thread in my output format proposed changes discussion linked above. I think that's the appropriate place to catalog features like this.

[TeCHiScy]

Please start a new thread in my output format proposed changes discussion linked above. I think that's the appropriate place to catalog features like this.

OK, I've started a new thread in the discussion, and the issue can be closed if needed.