dev.harrel:json-schema Help

Dialect details

Dialect registry

Each validator object contains an internal dialect registry which is used to recognize dialect based on $schema keyword value. By default, all official currently supported JSON Schema specification dialects are present in the registry. The registry can be updated:

new ValidatorFactory().withDialect(new CustomDialect);

Please note that overriding existing dialects in the registry is also possible. To do so, create a dialect implementation which returns the same value from getMetaSchema() as the one you want to override.

Default dialect

If schema does not contain a $schema keyword, a default dialect will be used. By default, the default dialect is Draft 2020-12. You can change it by calling:

new ValidatorFactory().withDefaultDialect(new CustomDialect);

Moreover, if you set disabledSchemaValidation to true, then the default dialect will be picked for any unknown (by dialect registry) $schema keyword values.

Dialect types

Depending on your needs, you might want to define only specific parts of a dialect.

Meta-schema only

This is the only official way to extend/create dialects, and it's implementation-agnostic.

You will need:

  1. The actual meta-schema:

    • It can be provided either by SchemaResolver or registered directly in Validator instance.

    • It has to finally resolve to an actual concrete dialect (from dialect registry). It cannot be recursive, either directly or indirectly - it may reference (by $schema) another "meta-schema only" dialect, but eventually the chain of references must point to a dialect from the dialect registry.

It allows you:

  1. Changing active vocabularies (by $vocabulary keyword). You can, for example, disable all validation keywords.

  2. Defining custom validation for your schemas.

You will not be able to:

  1. Define custom keywords, as the logic cannot be expressed directly in JSON.

  2. Make the dialect independent of another one. As mentioned before: it eventually needs to point to a registered dialect.

  3. Change the supported, required and default vocabularies.

    Dialect without meta-schema

    This is not really recommended approach as such a dialect can only be used as a default dialect.

    You will need:

    1. The actual implementation of Dialect.

    It allows you (only for schemas lacking $schema keyword):

    1. Defining custom keywords via EvaluatorFactory.

    2. Defining custom validation for your schemas.

    3. Changing active vocabularies (by $vocabulary keyword). You can, for example, disable all validation keywords.

    4. Changing the supported, required and default vocabularies.

    You will not be able to:

    1. Define custom validation for your schemas.

    2. Apply to schemas with resolvable $schema values.

      Full dialect

      The combination of two previous approaches.

      You will need:

      1. The actual meta-schema:

        • It can be provided either by SchemaResolver or registered directly in Validator instance.

        • It can be recursive.

      2. The actual implementation of Dialect.

      It allows you:

      1. Defining custom keywords via EvaluatorFactory.

      2. Changing the supported, required and default vocabularies.

        Dialect resolution process

        No

        Yes

        No

        Yes

        No

        No

        Yes

        No

        Does schema contain $schema keyword?

        ✔ Use default dialect

        Is it present in dialect registry?

        Is disableSchemaValidation set?

        ✔ Use dialect from the registry

        ✔ Use default dialect

        Is meta-schema present in schema registry?

        ✔ Get meta-schema from registry and use its dialect

        Follow schema resolution flow up the tree until:

        ✔ Root meta-schema is resolved. Use its dialect

        ❌ Resolution of meta-schema fails

        ❌ Cycle found

        04 August 2025
        lenientTypeFormat assertions