JSONSchemer

You can override default JSON Schema error messages by adding the x-error keyword to your schema. x-error takes precedence over I18n translations.

It supports several modes:

• String: A single string used for the schema and all its keywords.
• Hash: Allows keyword-specific overrides.
  • Use the specific keyword name (e.g., 'type') for targeted messages.
  • Use '^' to define a fallback error for the schema itself.
  • Use '*' to define a fallback error for the schema and all its keywords.

Variable Interpolation Inside an x-error string or template, you can use the following variables to inject context into the error message:

• %{instance}: The data being validated.
• %{instanceLocation}: The JSON pointer to the data.
• %{formattedInstanceLocation}: The JSON pointer formatted as a code literal.
• %{keywordValue}: The value of the keyword that failed.
• %{keywordLocation}: The JSON pointer to the keyword in the schema.
• %{absoluteKeywordLocation}: The absolute URI to the keyword in the schema.
• %{details}: A hash of additional error details.
• %{details__<key>}: Accesses a specific key within the details hash (e.g., %{details__missing_keys}).

# keyword-specific errors
schemer = JSONSchemer.schema({
  'type' => 'string',
  'minLength' => 10,
  'x-error' => {
    'type' => 'custom error for `type` keyword',
    '^' => 'custom error for schema',
    '*' => 'fallback error for schema and all keywords'
  }
})

# variable interpolation example
schemer = JSONSchemer.schema({
  'properties' => {
    'abc' => {
      'type' => 'object',
      'required' => ['xyz'],
      'x-error' => "instance: %{instance}, location: %{instanceLocation}"
    }
  }
})

If the i18n gem is loaded, json_schemer looks up error messages under the json_schemer key. This is useful for multi-language support.

Lookup Order Translations are looked up in the following order (the first match wins):

1. $LOCALE.json_schemer.errors.$ABSOLUTE_KEYWORD_LOCATION
2. $LOCALE.json_schemer.errors.$SCHEMA_ID.$KEYWORD_LOCATION
3. $LOCALE.json_schemer.errors.$KEYWORD_LOCATION
4. $LOCALE.json_schemer.errors.$SCHEMA_ID.$KEYWORD
5. $LOCALE.json_schemer.errors.$SCHEMA_ID.*
6. $LOCALE.json_schemer.errors.$META_SCHEMA_ID.$KEYWORD
7. $LOCALE.json_schemer.errors.$META_SCHEMA_ID.*
8. $LOCALE.json_schemer.errors.$KEYWORD
9. $LOCALE.json_schemer.errors.*

Note: You may need to restart your application after adding the root key because the existence check is cached for performance.

en:
  json_schemer:
    errors:
      '#/properties/abc/required': custom error for keyword location
      'required': custom error for `required` keyword
      '^': custom error for schema
      '*': fallback error for schema and all keywords

The 2019-09 and 2020-12 specifications have ambiguity regarding the basic output structure when only a single output node exists. There are two possible interpretations:

1. Nested structure: The root schema appears in a list with a containing node that only has a valid property.

   {
       "valid": false,
       "errors": [
           {
               "valid": false,
               "keywordLocation": "",
               "absoluteKeywordLocation": "...",
               "instanceLocation": ""
           }
       ]
   }

2. Collapsed structure: The entire structure collapses to just the root output node (similar to detailed).

   {
       "valid": false,
       "keywordLocation": "",
       "absoluteKeywordLocation": "...",
       "instanceLocation": ""
   }

Workaround for test authors: To avoid testing for a specific interpretation, you can force a second output unit by adding an "anyOf": [ true ] to the schema. This adds enough structure to avoid the ambiguity without changing the validation result. Ensure your test schema targets the specific requirement and ignores the extra output units generated by this keyword.