Skip to content

Latest commit

 

History

History
196 lines (137 loc) · 6.54 KB

index.adoc

File metadata and controls

196 lines (137 loc) · 6.54 KB
Raw

Vert.x Json Schema

Table of Contents

Vert.x Json Schema provides an extendable and asynchronous implementation for Json Schema specification. You can use Json Schemas to validate every json structure. This module provides:

  • Implementation of draft 2020-12

  • Implementation of draft 2019-09

  • Implementation of draft 7

  • Implementation of draft 4

  • Dereferencing of $ref resolution and caching

  • DSL to build schemas programmatically

Using Vert.x Json Schema

To use Vert.x Json Schema, add the following dependency to the dependencies section of your build descriptor:

  • Maven (in your pom.xml):

<dependency>
  <groupId>io.vertx</groupId>
  <artifactId>vertx-json-schema</artifactId>
  <version>${maven.version}</version>
</dependency>

  • Gradle (in your build.gradle file):

dependencies {
  compile 'io.vertx:vertx-json-schema:${maven.version}'
}

Concepts

JsonSchema

Schemas can exist in 2 flavours:

  • JSON as in JSON notation

  • Boolean as in true/false

The {@link io.vertx.json.schema.JsonSchema} interface allows both types to be handled without the constant check of the underlying type.

SchemaRepository

The {@link io.vertx.json.schema.SchemaRepository} holds {@link io.vertx.json.schema.JsonSchema} instances. It performs dereferencing of schemas to speed up validation. The repository is a simple key store, this means that it does not allow duplicate ids.

The repository can then create {@link io.vertx.json.schema.Validator} instances aware of all sub schemas in the repository.

Validator

As the name implies the {@link io.vertx.json.schema.Validator} validates an object using a start schema. The output format is dependent of the configuration.

Parse a schema

When working with multiple schemas or sub-schemas, it is recommended to use a Repository.

To parse a schema you first need a JsonSchema and some initial configuration. Since schemas can contain references it is required for the validator and repository to be aware of your application baseUri. This allows you to reference your own schemas in other sub-schemas. For the purpose of dereferencing, you don’t need to configure a draft.

{@link examples.JsonSchemaExamples#instantiate}

You can use JsonSchema instances for different Validator and you can parse different JsonSchema with JsonParser directly.

Now you can parse the schema:

{@link examples.JsonSchemaExamples#parse}
Important

Remember that for security reasons, this module will not attempt to download any referenced sub-schema. All required sub-schemas should be provided to a repository object.

Validate

Given the dynamic nature of json-schema and the conditional if-then-else it is not possible to validate in a streaming scenario. Validation is for this reason a blocking operation. If you are aware that validation will be a very expensive process, then it is advisable to run the validation on a dedicated thread pool or using executeBlocking. A schema could have two states:

To validate a schema:

{@link examples.JsonSchemaExamples#validate}

If a validation fails, you can retrieve the OutputErrorType to help determine the cause of the failure. Currently there are 3 OutputErrorType:

  • NONE, This is used when there are no errors found.

  • INVALID_VALUE, This is used when a value is provided, but the value does not match the given schema.

  • MISSING_VALUE, This is used when a value is not present, or not enough of the value is present but the schema requires it.

Defining a custom JSON format

By default, the schema validator will perform an NOOP on unknown formats, so they will be treated as valid inputs. It may be the case that additional format checking is required depending on the JSON specification you decide to use. If you need to define additional format checking, you can supply your own implementation of {@link io.vertx.json.schema.JsonFormatValidator} when creating a {@link io.vertx.json.schema.SchemaRepository} or {@link io.vertx.json.schema.Validator}:

{@link examples.JsonSchemaExamples#instantiateWithCustomJsonFormatValidator}

Building your schemas from code

If you want to build schemas from code, you can use the included DSL. Only Draft-7 is supported for this feature.

To start, add static imports for {@link io.vertx.json.schema.common.dsl.Schemas} and {@link io.vertx.json.schema.common.dsl.Keywords}

Creating the schema

Inside {@link io.vertx.json.schema.common.dsl.Schemas} there are static methods to create the schema:

{@link examples.JsonSchemaDslExamples#createSchema}

Using the keywords

For every schema you can add keywords built with {@link io.vertx.json.schema.common.dsl.Keywords} methods, depending on the type of the schema:

{@link examples.JsonSchemaDslExamples#keywords}

Defining the schema structure

Depending on the schema you create, you can define a structure.

To create an object schema with some properties schemas and additional properties schema:

{@link examples.JsonSchemaDslExamples#createObject}

To create an array schema:

{@link examples.JsonSchemaDslExamples#createArray}

To create a tuple schema:

{@link examples.JsonSchemaDslExamples#createTuple}

$ref and aliases

To add a $ref schema you can use the {@link io.vertx.json.schema.common.dsl.Schemas#ref(JsonPointer)} method. To assign an $id keyword to a schema, use {@link io.vertx.json.schema.common.dsl.SchemaBuilder#id(JsonPointer)}

You can also refer to schemas defined with this dsl using aliases. You can use {@link io.vertx.json.schema.common.dsl.SchemaBuilder#alias(String)} to assign an alias to a schema. Then you can refer to a schema with an alias using {@link io.vertx.json.schema.common.dsl.Schemas#refToAlias(String)}:

{@link examples.JsonSchemaDslExamples#alias}

Using the schema

After you defined the schema, you can call {@link io.vertx.json.schema.common.dsl.SchemaBuilder#toJson()} to return the JSON notation of the schema:

{@link examples.JsonSchemaDslExamples#parse}