Skip to content

Commit a7a0f2d

Browse files
justin-tayjustin-tay
committed
migration docs
1 parent 75e4323 commit a7a0f2d

File tree

1 file changed

+107
-0
lines changed

1 file changed

+107
-0
lines changed

‎doc/migration-2.0.0.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
## Migration to 2.0.0 from 1.5.x
2+
3+
### Compatibility
4+
5+
| Version | Java Compatibility | Jackson Version | Comments |
6+
| ----------------- | ------------------ | --------------- | -------------------------------------------------------------------------------------------------- |
7+
| `2.0.0` | Java 8 | Jackson 2 | This allows clients that still require to use Java 8 to have an incremental upgrade path to 3.0.0. |
8+
| `3.0.0` (Planned) | Java 17 | Jackson 3 | The change to Java compatibility is because Jackson 3 requires Java 17. |
9+
10+
### Major Changes
11+
12+
- Removal of deprecated methods and functionality from 1.x.
13+
- Major renaming of many of the public APIs and moving of classes into sub-packages.
14+
- Errors are returned as a `List` instead of a `Set`.
15+
- External resources will not be automatically fetched by default. This now requires opt-in via configuration.
16+
- This is to conform to the specification that requires such functionality to be disabled by default to prefer offline operation. Note however that classpath resources will still be automatically loaded.
17+
18+
#### Renaming and Refactoring
19+
20+
| Old | New | Comments |
21+
| ----------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
22+
| `com.networknt.schema.JsonMetaSchema` | `com.networknt.schema.dialect.Dialect` | Renamed to convey that this represents the dialect which has a set of keywords and vocabularies with precise semantics. The dialect id is used to identify the meta-schema which can be used to validate that a schema conforms to this dialect. |
23+
| `com.networknt.schema.JsonMetaSchemaFactory` | `com.networknt.schema.dialect.DialectRegistry` | Renamed to convey that this stores a set of registered dialects that will be used when `$schema` is found in a schema. For instance it is possible to override a standard dialect specified by a specification by registering a dialect using that dialect id. |
24+
| `com.networknt.schema.JsonSchema` | `com.networknt.schema.Schema` | Simplify naming. It is no longer possible to associate a configuration with a specific schema. |
25+
| `com.networknt.schema.JsonSchemaFactory` | `com.networknt.schema.SchemaRegistry` | Renamed to convey that this stores a set of registered schema resources. All schemas created will use the same configuration used for the registry. Therefore all the keywords of the schemas in the registry will be consistent configured. If there is a need for different configuration, a separate schema registry should be used. |
26+
| `com.networknt.schema.ValidationMessage` | `com.networknt.schema.Error` | Renamed to convey the intent better as a validation error raised by assertion keywords when processing instance data, or as a parse error when processing the schema data. The instance location has also been removed from the message. Therefore calling `error.getMessage()` no longer has the instance location pre-pended to the message. Calling `error.toString()` will return the message with the instance location prepended if the instance location exists. |
27+
| `com.networknt.schema.SchemaValidatorsConfig` | `com.networknt.schema.SchemaRegistryConfig` | Renamed to convey that this configuration is shared by all schemas from the same schema registry. The walk configuration has been moved out. |
28+
| `com.networknt.schema.SchemaValidatorsConfig` | `com.networknt.schema.walk.WalkConfig` | The walk configuration has been moved to a separate class. |
29+
| `com.networknt.schema.ErrorMessageType` | No replacement | The concept of error codes have been removed, instead the message keys used for generating the localised messages can be used instead to distinguish the error messages. |
30+
| `com.networknt.schema.ValidationContext` | `com.networknt.schema.SchemaContext` | Renamed to convey that this is the schema context shared for all the schemas and validators for the same overall schema with the same dialect. |
31+
| `com.networknt.schema.ValidatorTypeCode` | `com.networknt.schema.keyword.KeywordType` | Renamed to convey that these are keywords as the error codes have been removed. |
32+
| `com.networknt.schema.JsonSchemaValidator` | `com.networknt.schema.Validator` | Simplify naming. |
33+
| `com.networknt.schema.JsonValidator` | `com.networknt.schema.keyword.KeywordValidator` | Renamed to convey the intent that this is the validator created for keywords. |
34+
| `com.networknt.schema.walk.JsonSchemaWalker` | `com.networknt.schema.walk.Walker` | Simplify naming. |
35+
| `com.networknt.schema.SpecVersion.VersionFlag` | `com.networknt.schema.SpecificationVersion` | Renamed and flatten the hierarchy. |
36+
| `com.networknt.schema.SchemaId` | `com.networknt.schema.dialect.DialectId` | Renamed to convey that this is the dialect id used for the `$schema` keyword in schemas and `$id` keyword in meta-schemas. |
37+
| `com.networknt.schema.VocabularyFactory` | `com.networknt.schema.vocabulary.VocabularyRegistry` | Renamed to convey that this stores a set of registered vocabularies that contain keywords. |
38+
| `com.networknt.schema.JsonSchemaIdValidator` | `com.networknt.schema.SchemaIdValidator` | Simplify naming. |
39+
| `com.networknt.schema.JsonSchemaRef` | `com.networknt.schema.SchemaRef` | Simplify naming. |
40+
| `com.networknt.schema.JsonSchemaException` | `com.networknt.schema.SchemaException` | Simplify naming. |
41+
| `com.networknt.schema.JsonNodePath` | `com.networknt.schema.NodePath` | Simplify naming. |
42+
| `com.networknt.schema.serialization.JsonNodeReader` | `com.networknt.schema.serialization.NodeReader` | Simplify naming. |
43+
| `com.networknt.schema.annotation.JsonNodeAnnotation` | `com.networknt.schema.annotation.Annotation` | Simplify naming. |
44+
| `com.networknt.schema.annotation.JsonNodeAnnotations` | `com.networknt.schema.annotation.Annotations` | Simplify naming. |
45+
| `com.networknt.schema.ValidationResult` | `com.networknt.schema.Result` | Renamed to convey that this stores not just validation results but the output from walking. |
46+
| `com.networknt.schema.result.JsonNodeResult` | `com.networknt.schema.result.InstanceResult` | Simplify naming. |
47+
| `com.networknt.schema.result.JsonNodeResults` | `com.networknt.schema.result.InstanceResults` | Simplify naming. |
48+
| `com.networknt.schema.VersionCode` | `com.networknt.schema.SpecificationVersionRange` | Renamed to convey that this contains specification version ranges. |
49+
50+
#### API
51+
52+
```java
53+
package com.example.demo;
54+
55+
import java.util.List;
56+
import java.util.Map;
57+
58+
import com.networknt.schema.Error;
59+
import com.networknt.schema.InputFormat;
60+
import com.networknt.schema.Schema;
61+
import com.networknt.schema.SchemaLocation;
62+
import com.networknt.schema.SchemaRegistry;
63+
import com.networknt.schema.dialect.Dialects;
64+
65+
public class Demo {
66+
public static void main(String[] args) {
67+
String schemaData = """
68+
{
69+
"$id": "https://example.com/address.schema.json",
70+
"$schema": "https://json-schema.org/draft/2020-12/schema",
71+
"type": "object",
72+
"properties": {
73+
"streetAddress": {
74+
"type": "string"
75+
},
76+
"locality": {
77+
"type": "string"
78+
},
79+
"region": {
80+
"type": "string"
81+
},
82+
"postalCode": {
83+
"type": "string"
84+
},
85+
"countryName": {
86+
"type": "string"
87+
}
88+
},
89+
"required": [ "locality", "region", "countryName" ]
90+
}
91+
""";
92+
String instanceData = """
93+
{
94+
"streetAddress": "456 Main St",
95+
"region": "State",
96+
"postalCode": "12345",
97+
"countryName": "Country"
98+
}
99+
""";
100+
SchemaRegistry schemaRegistry = SchemaRegistry.withDialect(Dialects.getDraft202012(),
101+
builder -> builder.schemas(Map.of("https://example.com/address.schema.json", schemaData)));
102+
Schema schema = schemaRegistry.getSchema(SchemaLocation.of("https://example.com/address.schema.json"));
103+
List<Error> errors = schema.validate(instanceData, InputFormat.JSON);
104+
System.out.println(errors);
105+
}
106+
}
107+
```

0 commit comments

Comments
 (0)