xref: /aosp_15_r20/external/json-schema-validator/doc/compatibility.md (revision 78c4dd6aa35290980cdcd1623a7e337e8d021c7c)

## Compatibility with JSON Schema versions

[![Supported spec](https://img.shields.io/endpoint?url=https%3A%2F%2Fbowtie.report%2Fbadges%2Fjava-json-schema-validator%2Fsupported_versions.json)](https://bowtie.report/#/implementations/java-json-schema-validator)
[![Compliance](https://img.shields.io/endpoint?url=https%3A%2F%2Fbowtie.report%2Fbadges%2Fjava-json-schema-validator%2Fcompliance%2Fdraft2020-12.json)](https://bowtie.report/#/dialects/draft2020-12)
[![Compliance](https://img.shields.io/endpoint?url=https%3A%2F%2Fbowtie.report%2Fbadges%2Fjava-json-schema-validator%2Fcompliance%2Fdraft2019-09.json)](https://bowtie.report/#/dialects/draft2019-09)
[![Compliance](https://img.shields.io/endpoint?url=https%3A%2F%2Fbowtie.report%2Fbadges%2Fjava-json-schema-validator%2Fcompliance%2Fdraft7.json)](https://bowtie.report/#/dialects/draft7)
[![Compliance](https://img.shields.io/endpoint?url=https%3A%2F%2Fbowtie.report%2Fbadges%2Fjava-json-schema-validator%2Fcompliance%2Fdraft6.json)](https://bowtie.report/#/dialects/draft6)
[![Compliance](https://img.shields.io/endpoint?url=https%3A%2F%2Fbowtie.report%2Fbadges%2Fjava-json-schema-validator%2Fcompliance%2Fdraft4.json)](https://bowtie.report/#/dialects/draft4)

The `pattern` validator by default uses the JDK regular expression implementation which is not ECMA-262 compliant and is thus not compliant with the JSON Schema specification. The library can however be configured to use a ECMA-262 compliant regular expression implementation.

Annotation processing and reporting are implemented. Note that the collection of annotations will have an adverse performance impact.

This implements the Flag, List and Hierarchical output formats defined in the [Specification for Machine-Readable Output for JSON Schema Validation and Annotation](https://github.com/json-schema-org/json-schema-spec/blob/8270653a9f59fadd2df0d789f22d486254505bbe/jsonschema-validation-output-machines.md).

The implementation supports the use of custom keywords, formats, vocabularies and meta-schemas.

### Known Issues

There are currently no known issues with the required functionality from the specification.

The following are the tests results after running the [JSON Schema Test Suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite) as at 29 Jan 2024 using version 1.3.1. As the test suite is continously updated, this can result in changes in the results subsequently.

| Implementations | Overall                                                                 | DRAFT_03                                                          | DRAFT_04                                                            | DRAFT_06                                                           | DRAFT_07                                                               | DRAFT_2019_09                                                        | DRAFT_2020_12                                                          |
|-----------------|-------------------------------------------------------------------------|-------------------------------------------------------------------|---------------------------------------------------------------------|--------------------------------------------------------------------|------------------------------------------------------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------|
| NetworkNt       | pass: r:4703 (100.0%) o:2369 (100.0%)<br>fail: r:0 (0.0%) o:1 (0.0%)    |                                                                   | pass: r:600 (100.0%) o:251 (100.0%)<br>fail: r:0 (0.0%) o:0 (0.0%)  | pass: r:796 (100.0%) o:318 (100.0%)<br>fail: r:0 (0.0%) o:0 (0.0%) | pass: r:880 (100.0%) o:541 (100.0%)<br>fail: r:0 (0.0%) o:0 (0.0%)     | pass: r:1201 (100.0%) o:625 (100.0%)<br>fail: r:0 (0.0%) o:0 (0.0%)  | pass: r:1226 (100.0%) o:634 (99.8%)<br>fail: r:0 (0.0%) o:1 (0.2%)     |

### Legend

| Symbol | Meaning               |
|:------:|:----------------------|
|   ��   | Fully implemented     |
|   ��   | Partially implemented |
|   ��   | Not implemented       |
|   ��   | Not defined           |

### Keywords Support

| Keyword                    | Draft 4 | Draft 6 | Draft 7 | Draft 2019-09 | Draft 2020-12 |
|:---------------------------|:-------:|:-------:|:-------:|:-------------:|:-------------:|
| $anchor                    | �� | �� | �� | �� | �� |
| $dynamicAnchor             | �� | �� | �� | �� | �� |
| $dynamicRef                | �� | �� | �� | �� | �� |
| $id                        | �� | �� | �� | �� | �� |
| $recursiveAnchor           | �� | �� | �� | �� | �� |
| $recursiveRef              | �� | �� | �� | �� | �� |
| $ref                       | �� | �� | �� | �� | �� |
| $vocabulary                | �� | �� | �� | �� | �� |
| additionalItems            | �� | �� | �� | �� | �� |
| additionalProperties       | �� | �� | �� | �� | �� |
| allOf                      | �� | �� | �� | �� | �� |
| anyOf                      | �� | �� | �� | �� | �� |
| const                      | �� | �� | �� | �� | �� |
| contains                   | �� | �� | �� | �� | �� |
| contentEncoding            | �� | �� | �� | �� | �� |
| contentMediaType           | �� | �� | �� | �� | �� |
| contentSchema              | �� | �� | �� | �� | �� |
| definitions                | �� | �� | �� | �� | �� |
| defs                       | �� | �� | �� | �� | �� |
| dependencies               | �� | �� | �� | �� | �� |
| dependentRequired          | �� | �� | �� | �� | �� |
| dependentSchemas           | �� | �� | �� | �� | �� |
| enum                       | �� | �� | �� | �� | �� |
| exclusiveMaximum (boolean) | �� | �� | �� | �� | �� |
| exclusiveMaximum (numeric) | �� | �� | �� | �� | �� |
| exclusiveMinimum (boolean) | �� | �� | �� | �� | �� |
| exclusiveMinimum (numeric) | �� | �� | �� | �� | �� |
| if-then-else               | �� | �� | �� | �� | �� |
| items                      | �� | �� | �� | �� | �� |
| maxContains                | �� | �� | �� | �� | �� |
| minContains                | �� | �� | �� | �� | �� |
| maximum                    | �� | �� | �� | �� | �� |
| maxItems                   | �� | �� | �� | �� | �� |
| maxLength                  | �� | �� | �� | �� | �� |
| maxProperties              | �� | �� | �� | �� | �� |
| minimum                    | �� | �� | �� | �� | �� |
| minItems                   | �� | �� | �� | �� | �� |
| minLength                  | �� | �� | �� | �� | �� |
| minProperties              | �� | �� | �� | �� | �� |
| multipleOf                 | �� | �� | �� | �� | �� |
| not                        | �� | �� | �� | �� | �� |
| oneOf                      | �� | �� | �� | �� | �� |
| pattern                    | �� | �� | �� | �� | �� |
| patternProperties          | �� | �� | �� | �� | �� |
| prefixItems                | �� | �� | �� | �� | �� |
| properties                 | �� | �� | �� | �� | �� |
| propertyNames              | �� | �� | �� | �� | �� |
| readOnly                   | �� | �� | �� | �� | �� |
| required                   | �� | �� | �� | �� | �� |
| type                       | �� | �� | �� | �� | �� |
| unevaluatedItems           | �� | �� | �� | �� | �� |
| unevaluatedProperties      | �� | �� | �� | �� | �� |
| uniqueItems                | �� | �� | �� | �� | �� |
| writeOnly                  | �� | �� | �� | �� | �� |

In accordance with the specification, unknown keywords are treated as annotations. This is customizable by configuring a unknown keyword factory on the respective meta-schema.

#### Content Encoding

Since Draft 2019-09, the `contentEncoding` keyword does not generate assertions.

#### Content Media Type

Since Draft 2019-09, the `contentMediaType` keyword does not generate assertions.

#### Content Schema

The `contentSchema` keyword does not generate assertions.

#### Pattern

By default the `pattern` keyword uses the JDK regular expression implementation validating regular expressions.

This is not ECMA-262 compliant and is thus not compliant with the JSON Schema specification. This is however the more likely desired behavior as other logic will most likely be using the default JDK regular expression implementation to perform downstream processing.

The library can be configured to use a ECMA-262 compliant regular expression validator which is implemented using [joni](https://github.com/jruby/joni). This can be configured by setting `setEcma262Validator` to `true`.

This also requires adding the `joni` dependency.

```xml
<dependency>
    <!-- Used to validate ECMA 262 regular expressions -->
    <groupId>org.jruby.joni</groupId>
    <artifactId>joni</artifactId>
    <version>${version.joni}</version>
</dependency>
```

#### Format

Since Draft 2019-09 the `format` keyword only generates annotations by default and does not generate assertions.

This can be configured on a schema basis by using a meta schema with the appropriate vocabulary.

| Version               | Vocabulary                                                    | Value             |
|:----------------------|---------------------------------------------------------------|-------------------|
| Draft 2019-09         | `https://json-schema.org/draft/2019-09/vocab/format`          | `true`            |
| Draft 2020-12         | `https://json-schema.org/draft/2020-12/vocab/format-assertion`| `true`/`false`    |

This behavior can be overridden to generate assertions by setting the `setFormatAssertionsEnabled` option to `true`.

| Format                | Draft 4 | Draft 6 | Draft 7 | Draft 2019-09 | Draft 2020-12 |
|:----------------------|:-------:|:-------:|:-------:|:-------------:|:-------------:|
| date                  | �� | �� | �� | �� | �� |
| date-time             | �� | �� | �� | �� | �� |
| duration              | �� | �� | �� | �� | �� |
| email                 | �� | �� | �� | �� | �� |
| hostname              | �� | �� | �� | �� | �� |
| idn-email             | �� | �� | �� | �� | �� |
| idn-hostname          | �� | �� | �� | �� | �� |
| ipv4                  | �� | �� | �� | �� | �� |
| ipv6                  | �� | �� | �� | �� | �� |
| iri                   | �� | �� | �� | �� | �� |
| iri-reference         | �� | �� | �� | �� | �� |
| json-pointer          | �� | �� | �� | �� | �� |
| relative-json-pointer | �� | �� | �� | �� | �� |
| regex                 | �� | �� | �� | �� | �� |
| time                  | �� | �� | �� | �� | �� |
| uri                   | �� | �� | �� | �� | �� |
| uri-reference         | �� | �� | �� | �� | �� |
| uri-template          | �� | �� | �� | �� | �� |
| uuid                  | �� | �� | �� | �� | �� |

##### Unknown Formats

When the format assertion vocabularies are used in a meta schema, in accordance to the specification, unknown formats will result in assertions. If the format assertion vocabularies are not used, unknown formats will only result in assertions if the assertions are enabled and if `setStrict("format", true)`.

##### Footnotes
1. Note that the validation are only optional for some of the keywords/formats.
2. Refer to the corresponding JSON schema for more information on whether the keyword/format is optional or not.