Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/erosb/json-skema
JSON Schema Validator for the JVM, implements draft2020-12
https://github.com/erosb/json-skema
json-schema json-schema-validator
Last synced: 6 days ago
JSON representation
JSON Schema Validator for the JVM, implements draft2020-12
- Host: GitHub
- URL: https://github.com/erosb/json-skema
- Owner: erosb
- License: mit
- Created: 2020-11-20T20:51:00.000Z (almost 4 years ago)
- Default Branch: master
- Last Pushed: 2024-10-21T04:37:26.000Z (15 days ago)
- Last Synced: 2024-10-23T02:27:41.805Z (13 days ago)
- Topics: json-schema, json-schema-validator
- Language: Kotlin
- Homepage:
- Size: 749 KB
- Stars: 49
- Watchers: 6
- Forks: 8
- Open Issues: 19
-
Metadata Files:
- Readme: README.md
- License: LICENSE.md
Awesome Lists containing this project
README
# json-sKema
_json-sKema is a [Json Schema](https://json-schema.org/) validator library for the Java Virtual Machine. It implements the [draft 2020-12](https://json-schema.org/draft/2020-12/json-schema-validation.html) specification._
Are you new to JSON Schema? Get started with [Understanding JSON Schema](https://json-schema.org/understanding-json-schema/)!
* [json-sKema](#json-skema)
* [Installation](#installation)
* [Maven](#maven)
* [Gradle](#gradle)
* [Usage](#usage)
* [Hello-world](#hello-world)
* [Loading a schema file from URL](#loading-a-schema-file-from-url)
* [Pre-registering schemas by URI before schema loading](#pre-registering-schemas-by-uri-before-schema-loading)
* [Validating in Read or Write context](#validating-in-read-or-write-context)
* [SchemaBuilder for dynamic (programmatic) schema construction](#schemabuilder-for-dynamic-programmatic-schema-construction)
* [Compatibility notes](#compatibility-notes)
* [`"format"` support](#format-support)
* [Support for older JSON Schema drafts](#support-for-older-json-schema-drafts)
* [Contribution guideline](#contribution-guideline)
* [Building the project:](#building-the-project)
* [Building the project and running the official test suite:](#building-the-project-and-running-the-official-test-suite)
* [Building the project without running the official test suite:](#building-the-project-without-running-the-official-test-suite)
## Installation
### Maven
Add the following dependency to the `` section of your project:
```xml
com.github.erosb
json-sKema
0.18.0
```
### Gradle
```groovy
dependencies {
implementation("com.github.erosb:json-sKema:0.18.0")
}
```
## Usage
### Hello-world
[Complete source](https://github.com/erosb/json-sKema-examples/blob/master/src/main/java/com/github/erosb/jsonsKema/examples/HelloWorld.java)
```java
// parse the schema JSON as string
JsonValue schemaJson = new JsonParser("""
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"age": {
"type": "number",
"minimum": 0
},
"name": {
"type": "string"
},
"email": {
"type": "string",
"format": "email"
}
}
}
""").parse();
// map the raw json to a reusable Schema instance
Schema schema = new SchemaLoader(schemaJson).load();
// create a validator instance for each validation (one-time use object)
Validator validator = Validator.create(schema, new ValidatorConfig(FormatValidationPolicy.ALWAYS));
// parse the input instance to validate against the schema
JsonValue instance = new JsonParser("""
{
"age": -5,
"name": null,
"email": "invalid"
}
""").parse();
// run the validation
ValidationFailure failure = validator.validate(instance);
// print the validation failures (if any)
System.out.println(failure);
```
### Loading a schema file from URL
```java
// HTTP(s) protocol is also supported
Schema schema = SchemaLoader.forURL("classpath:///path/to/your/schema.json").load();
// create a validator instance for each validation (one-time use object)
Validator validator = Validator.forSchema(schema);
// ...
```
### Pre-registering schemas by URI before schema loading
[Complete source](https://github.com/erosb/json-sKema-examples/blob/master/src/main/java/com/github/erosb/jsonsKema/examples/PreRegisteredSchemas.java)
```java
// Creating a SchemaLoader config with a pre-registered schema by URI
SchemaLoaderConfig config = createDefaultConfig(Map.of(
// When the loader sees this URI,
new URI("urn:uuid:d652a438-9897-4160-959c-bbdb690c3e0d"),
// then it will resolve it to this schema json
"""
{
"$defs": {
"ItemType": {
"type": "integer",
"minimum": 0
}
}
}
"""
));
// parsing the schema json, with a $ref to the above pre-configured URI
JsonValue schemaJson = new JsonParser("""
{
"type": "array",
"items": {
"$ref": "urn:uuid:d652a438-9897-4160-959c-bbdb690c3e0d#/$defs/ItemType"
}
}
""").parse();
// loading the schema json into a Schema object
Schema schema = new SchemaLoader(schemaJson, config).load();
// running the validation
ValidationFailure result = Validator.forSchema(schema).validate(new JsonParser("[null]").parse());
System.out.println(result.toJSON());
```
### Validating in Read or Write context
[Complete source](https://github.com/erosb/json-sKema-examples/blob/master/src/main/java/com/github/erosb/jsonsKema/examples/ReadWriteContextValidation.java)
If you want to take advantage of the [`"readOnly"` and `"writeOnly"`](https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-validation-00#rfc.section.9.4)
keywords of json schema, you can tell the `Validator` instance if the validation happens in read or write context:
```java
JsonValue schemaJson = new JsonParser("""
{
"type": "object",
"properties": {
"id": {
"readOnly": true,
"type": "number"
},
"name": {
"type": "string"
},
"password": {
"type": "string",
"writeOnly": true
}
}
}
""").parse();
// map the raw json to a reusable Schema instance
Schema schema = new SchemaLoader(schemaJson).load();
// creating write-context validator, it will report validation failures
// for read-only properties that are included in the instance
var writeContextValidator = Validator.create(schema, ValidatorConfig.builder()
.readWriteContext(ReadWriteContext.WRITE)
.build()
);
// creating the json document which will be validated (first in write context, then in read context)
JsonValue instance = new JsonParser("""
{
"id": 1,
"name": "John Doe",
"password": "v3ry_s3cur3"
}
""").parse();
var writeContextFailure = writeContextValidator.validate(instance);
// prints failure because the read-only property "id" is present in write context
System.out.println(writeContextFailure);
// creating read-context validator, it will report validation failures
// for write-only properties that are included in the instance
var readContextValidator = Validator.create(schema, ValidatorConfig.builder()
.readWriteContext(ReadWriteContext.READ)
.build()
);
var readContextFailure = readContextValidator.validate(instance);
// prints failure because the write-only property "password" is present in read context
System.out.println(readContextFailure);
```
### SchemaBuilder for dynamic (programmatic) schema construction
The library allows dynamic schema construction via its `SchemaBuilder` class. This is useful in cases when, instead of working with
static schemas or externally fed JSON Schemas, the application needs to create a schema instance at run-time, dynamically. This can
be done with a fluent API, demonstrated below:
[Complete source](https://github.com/erosb/json-sKema-examples/blob/master/src/main/java/com/github/erosb/jsonsKema/examples/SchemaBuilderDemo.java)
```java
import static com.github.erosb.jsonsKema.SchemaBuilder.*;
//...
typeObject()
.property("myString", typeString()
.minLength(2)
.maxLength(50)
.pattern("^[a-zA-Z ]*$")
).property("myInteger", typeInteger()
.minimum(10)
.maximum(20)
.multipleOf(4)
).property("myObject", typeObject()
.additionalProperties(falseSchema())
.patternProperties(Map.of(
"^[A-Z]{2}$", allOf(
typeArray().items(typeNumber())
.prefixItems(List.of(typeBoolean(), typeBoolean())),
typeArray().minContains(3, constSchema(new JsonNumber(1.5)))
)
))
)
```
## Compatibility notes
The library implements the JSON Schema draft 2020-12 core and validation specifications, with the following notes:
* `$dynamicAnchor` and `$dynamicRef` support is partially implemented
### `"format"` support
The library currently has built-in support for the following `"format"` values defined in the specification:
"format"
Supported?
Notes
date
Yes
date-time
Yes
Non-UTC values with leap seconds not supported
time
Yes
duration
Partially
email
Yes
IPV6 domain parts not supported
uri
Yes
ipv4
Yes
ipv6
Yes
uuid
Yes
The following formats are NOT supported: hostname, idn-email, idn-hostname, iri, iri-reference, json-pointer, regex, relative-json-pointer, uri-reference, uri-template .
### Support for older JSON Schema drafts
This project is the successor of [everit-org/json-schema](https://github.com/everit-org/json-schema). If you want to use draft-04, draft-06 or draft-07 versions of JSON Schema, then you can use the everit library.
## Contribution guideline
Local environment setup:
_Prerequisite: JDK and Maven installed_
```
git clone https://github.com/erosb/json-sKema.git
cd json-sKema
git submodule init
git submodule update
```
### Building the project:
`mvn clean package`
### Building the project and running the official test suite:
Test annotated with `@Tag("acceptance")` require the test suite to be pulled using:
`git submodule update --init --recursive`
Then run the tests:
`mvn clean verify`
### Building the project without running the official test suite:
`mvn clean package -Dgroups='!acceptance'`