1## Upgrading to new versions 2 3This library can contain breaking changes in `minor` version releases. 4 5This contains information on the notable or breaking changes in each version. 6 7### 1.4.0 8 9This contains breaking changes 10- to those using the walk functionality 11- in how custom meta-schemas are created 12 13When using the walker with defaults the `default` across a `$ref` are properly resolved and used. 14 15The behavior for the property listener is now more consistent whether or not validation is enabled. Previously if validation is enabled but the property is `null` the property listener is not called while if validation is not enabled it will be called. Now the property listener will be called in both scenarios. 16 17The following are the breaking changes to those using the walk functionality. 18 19`WalkEvent` 20| Field | Change | Notes 21|--------------------------|--------------|---------- 22| `schemaLocation` | Removed | For keywords: `getValidator().getSchemaLocation()`. For items and properties: `getSchema().getSchemaLocation()` 23| `evaluationPath` | Removed | For keywords: `getValidator().getEvaluationPath()`. For items and properties: `getSchema().getEvaluationPath()` 24| `schemaNode` | Removed | `getSchema().getSchemaNode()` 25| `parentSchema` | Removed | `getSchema().getParentSchema()` 26| `schema` | New | For keywords this is the parent schema of the validator. For items and properties this is the item or property schema being evaluated. 27| `node` | Renamed | `instanceNode` 28| `currentJsonSchemaFactory`| Removed | `getSchema().getValidationContext().getJsonSchemaFactory()` 29| `validator` | New | The validator indicated by the keyword. 30 31 32The following are the breaking changes in how custom meta-schemas are created. 33 34`JsonSchemaFactory` 35* The following were renamed on `JsonSchemaFactory` builder 36 * `defaultMetaSchemaURI` -> `defaultMetaSchemaIri` 37 * `enableUriSchemaCache` -> `enableSchemaCache` 38* The builder now accepts a `JsonMetaSchemaFactory` which can be used to restrict the loading of meta-schemas that aren't explicitly defined in the `JsonSchemaFactory`. The `DisallowUnknownJsonMetaSchemaFactory` can be used to only allow explicitly configured meta-schemas. 39 40`JsonMetaSchema` 41* In particular `Version201909` and `Version202012` had most of the keywords moved to their respective vocabularies. 42* The following were renamed 43 * `getUri` -> `getIri` 44* The builder now accepts a `vocabularyFactory` to allow for custom vocabularies. 45* The builder now accepts a `unknownKeywordFactory`. By default this uses the `UnknownKeywordFactory` implementation that logs a warning and returns a `AnnotationKeyword`. The `DisallowUnknownKeywordFactory` can be used to disallow the use of unknown keywords. 46* The implementation of the builder now correctly throws an exception for `$vocabulary` with value of `true` that are not known to the implementation. 47 48`ValidatorTypeCode` 49* `getNonFormatKeywords` has been removed and replaced with `getKeywords`. This now includes the `format` keyword as the `JsonMetaSchema.Builder` now needs to know if the `format` keyword was configured, as it might not be in meta-schemas that don't define the format vocabulary. 50* The applicable `VersionCode` for each of the `ValidatorTypeCode` were modified to remove the keywords that are defined in vocabularies for `Version201909` and `Version202012`. 51 52`Vocabulary` 53* This now contains `Keyword` instances instead of the string keyword value as it needs to know the explicit implementation. For instance the implementation for the `items` keyword in Draft 2019-09 and Draft 2020-12 are different. 54* The following were renamed 55 * `getId` -> `getIri` 56 57### 1.3.1 58 59This contains a breaking change in that the results from `failFast` are no longer thrown as an exception. The single result is instead returned normally in the output. This was partially done to distinguish the fail fast result from true exceptions such as when references could not be resolved. 60 61* Annotation collection and reporting has been implemented 62* Keywords have been refactored to use annotations for evaluation to improve performance and meet functional requirements 63* The list and hierarchical output formats have been implemented as per the [Specification for Machine-Readable Output for JSON Schema Validation and Annotation](https://github.com/json-schema-org/json-schema-spec/blob/main/jsonschema-validation-output-machines.md). 64* The fail fast evaluation processing has been redesigned and fixed. This currently passes the [JSON Schema Test Suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite) with fail fast enabled. Previously contains and union type may cause incorrect results. 65* This also contains fixes for regressions introduced in 1.3.0 66 67The following keywords were refactored to improve performance and meet the functional requirements. 68 69In particular this converts the `unevaluatedItems` and `unevaluatedProperties` validators to use annotations to perform the evaluation instead of the current mechanism which affects performance. This also refactors `$recursiveRef` to not rely on that same mechanism. 70 71* `unevaluatedProperties` 72* `unevaluatedItems` 73* `properties` 74* `patternProperties` 75* `items` / `additionalItems` 76* `prefixItems` / `items` 77* `contains` 78* `$recursiveRef` 79 80This also fixes the issue where the `unevaluatedItems` keyword does not take into account the `contains` keyword when performing the evaluation. 81 82This also fixes cases where `anyOf` short-circuits to not short-circuit the evaluation if a adjacent `unevaluatedProperties` or `unevaluatedItems` keyword exists. 83 84This should fix most of the remaining functional and performance issues. 85 86#### Functional 87 88| Implementations | Overall | DRAFT_03 | DRAFT_04 | DRAFT_06 | DRAFT_07 | DRAFT_2019_09 | DRAFT_2020_12 | 89|-----------------|-------------------------------------------------------------------------|-------------------------------------------------------------------|---------------------------------------------------------------------|--------------------------------------------------------------------|------------------------------------------------------------------------|----------------------------------------------------------------------|------------------------------------------------------------------------| 90| 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%) | 91 92#### Performance 93 94##### NetworkNT 1.3.1 95 96``` 97Benchmark Mode Cnt Score Error Units 98NetworkntBenchmark.testValidate thrpt 10 6776.693 ± 115.309 ops/s 99NetworkntBenchmark.testValidate:·gc.alloc.rate thrpt 10 971.191 ± 16.420 MB/sec 100NetworkntBenchmark.testValidate:·gc.alloc.rate.norm thrpt 10 165318.816 ± 0.459 B/op 101NetworkntBenchmark.testValidate:·gc.churn.G1_Eden_Space thrpt 10 968.894 ± 51.234 MB/sec 102NetworkntBenchmark.testValidate:·gc.churn.G1_Eden_Space.norm thrpt 10 164933.962 ± 8636.203 B/op 103NetworkntBenchmark.testValidate:·gc.churn.G1_Survivor_Space thrpt 10 0.002 ± 0.001 MB/sec 104NetworkntBenchmark.testValidate:·gc.churn.G1_Survivor_Space.norm thrpt 10 0.274 ± 0.218 B/op 105NetworkntBenchmark.testValidate:·gc.count thrpt 10 89.000 counts 106NetworkntBenchmark.testValidate:·gc.time thrpt 10 99.000 ms 107``` 108 109###### Everit 1.14.1 110 111``` 112Benchmark Mode Cnt Score Error Units 113EveritBenchmark.testValidate thrpt 10 3719.192 ± 125.592 ops/s 114EveritBenchmark.testValidate:·gc.alloc.rate thrpt 10 1448.208 ± 74.746 MB/sec 115EveritBenchmark.testValidate:·gc.alloc.rate.norm thrpt 10 449621.927 ± 7400.825 B/op 116EveritBenchmark.testValidate:·gc.churn.G1_Eden_Space thrpt 10 1446.397 ± 79.919 MB/sec 117EveritBenchmark.testValidate:·gc.churn.G1_Eden_Space.norm thrpt 10 449159.799 ± 18614.931 B/op 118EveritBenchmark.testValidate:·gc.churn.G1_Survivor_Space thrpt 10 0.001 ± 0.001 MB/sec 119EveritBenchmark.testValidate:·gc.churn.G1_Survivor_Space.norm thrpt 10 0.364 ± 0.391 B/op 120EveritBenchmark.testValidate:·gc.count thrpt 10 133.000 counts 121EveritBenchmark.testValidate:·gc.time thrpt 10 148.000 ms 122``` 123 124### 1.3.0 125 126This adds support for Draft 2020-12 127 128This adds support for the following keywords 129* `$dynamicRef` 130* `$dynamicAnchor` 131* `$vocabulary` 132 133This refactors the schema retrieval codes as the ID is based on IRI and not URI. 134 135Note that Java does not support IRIs. See https://cr.openjdk.org/%7Edfuchs/writeups/updating-uri/ for details. 136 137The following are removed and replaced by `SchemaLoader` and `SchemaMapper`. 138* `URIFactory` - No replacement. The resolve logic is in `AbsoluteIRI`. 139* `URISchemeFactory` - No replacement as `URIFactory` isn't required anymore. 140* `URISchemeFetcher` - No replacement. The `SchemaLoaders` are iterated and called. 141* `URITranslator` - Replaced by `SchemaMapper`. 142* `URLFactory` - No replacement as `URIFactory` isn't required anymore. 143* `URLFetcher` - Replaced by `UriSchemaLoader`. 144* `URNURIFactory` - No replacement as `URIFactory` isn't required anymore. 145 146The `SchemaLoader` and `SchemaMapper` are configured in the `JsonSchemaFactory.Builder`. See [Customizing Schema Retrieval](schema-retrieval.md). 147 148As per the specification. The `format` keyword since Draft 2019-09 no longer generates assertions by default. 149 150This can be changed by using a custom meta schema with the relevant `$vocabulary` or by setting the execution configuration to enable format assertions. 151 152### 1.2.0 153 154The following are a summary of the changes 155* Paths are now specified using the `JsonNodePath`. The paths are `instanceLocation`, `schemaLocation` and `evaluationPath`. The meaning of these paths are as defined in the [specification](https://github.com/json-schema-org/json-schema-spec/blob/main/jsonschema-validation-output-machines.md). 156* Schema Location comprises an absolute IRI component and a fragment that is a `JsonNodePath` that is typically a JSON pointer 157* Rename `at` to `instanceLocation`. Note that for the `required` validator the error message `instanceLocation` does not point to the missing property to be consistent with the [specification](https://json-schema.org/draft/2020-12/json-schema-core#section-12.4.2). The `ValidationMessage` now contains a `property` attribute if this is required. 158* Rename `schemaPath` to `schemaLocation`. This should generally be an absolute IRI with a fragment particularly in later drafts. 159* Add `evaluationPath` 160 161`JsonValidator` 162* Now contains `getSchemaLocation` and `getEvaluationPath` in the interface 163* Implementations now need a constructor that takes in `schemaLocation` and `evaluationPath` 164* The `validate` method uses `JsonNodePath` for the `instanceLocation` 165* The `validate` method with just the `rootNode` has been removed 166 167`JsonSchemaWalker` 168* The `walk` method uses `JsonNodePath` for the `instanceLocation` 169 170`WalkEvent` 171* Rename `at` to `instanceLocation` 172* Rename `schemaPath` to `schemaLocation` 173* Add `evaluationPath` 174* Rename `keyWordName` to `keyword` 175 176`WalkListenerRunner` 177* Rename `at` to `instanceLocation` 178* Rename `schemaPath` to `schemaLocation` 179* Add `evaluationPath` 180 181`BaseJsonValidator` 182* The `atPath` methods are removed. Use `JsonNodePath.append` to get the path of the child 183* The `buildValidationMessage` methods are removed. Use the `message` builder method instead. 184 185`CollectorContext` 186* The `evaluatedProperties` and `evaluatedItems` are now `Collection<JsonNodePath>` 187 188`JsonSchema` 189* The validator keys are now using `evaluationPath` instead of `schemaPath` 190* The `@deprecated` constructor methods have been removed 191 192`ValidatorTypeCode` 193* The `customMessage` has been removed. This made the `ValidatorTypeCode` mutable if the feature was used as the enum is a shared instance. The logic for determining the `customMessage` has been moved to the validator. 194* The creation of `newValidator` instances now uses a functional interface instead of reflection. 195 196`ValidatorState` 197* The `ValidatorState` is now a property of the `ExecutionContext`. This change is largely to improve performance. The `CollectorContext.get` method is particularly slow for this use case. 198 199### 1.1.0 200 201Removes use of `ThreadLocal` to store context and explicitly passes the context as a parameter where needed. 202 203The following are the main API changes, typically to accept an `ExecutionContext` as a parameter 204 205* `com.networknt.schema.JsonSchema` 206* `com.networknt.schema.JsonValidator` 207* `com.networknt.schema.Format` 208* `com.networknt.schema.walk.JsonSchemaWalker` 209* `com.networknt.schema.walk.WalkEvent` 210 211`JsonSchema` was modified to optionally accept an `ExecutionContext` for the `validate`, `validateAndCollect` and `walk` methods. For methods where no `ExecutionContext` is supplied, one is created for each run in the `createExecutionContext` method in `JsonSchema`. 212 213`ValidationResult` was modified to store the `ExecutionContext` of the run which is also a means of reusing the context, by passing this context information from the `ValidationResult` to following runs. 214 215### 1.0.82 216 217Up to version [1.0.81](https://github.com/networknt/json-schema-validator/blob/1.0.81/pom.xml#L99), the dependency `org.apache.commons:commons-lang3` was included as a runtime dependency. Starting with [1.0.82](https://github.com/networknt/json-schema-validator/releases/tag/1.0.82) it is not required anymore.