json-schema-validator

This multiplatform library is an implementation of JSON schema that can validate JsonElement from kotlinx.serialization-json library.

Usage

Supported targets

Target
jvm
js
macosX64
macosArm64
iosArm64
iosSimulatorArm64
linuxX64
linuxArm64
mingwX64

Dependencies

Releases

In order to use releases add Maven Central repository to the list of repositories.

Kotlin

repositories {
  mavenCentral()
}

implementation("io.github.optimumcode:json-schema-validator:0.0.7")

Groovy

repositories {
  mavenCentral()
}

implementation 'io.github.optimumcode:json-schema-validator:0.0.7'

Release are published to Sonatype repository. The synchronization with Maven Central takes time. If you want to use the release right after the publication you should add Sonatype Release repository to your build script.

Kotlin

repositories {
  maven(url = "https://s01.oss.sonatype.org/content/repositories/releases/")
}

Groovy

repositories {
  maven { url 'https://s01.oss.sonatype.org/content/repositories/releases/' }
}

Snapshots

If you want to use SNAPSHOT version you should add Sonatype Snapshot repository to your build script.

Kotlin

repositories {
  maven(url = "https://s01.oss.sonatype.org/content/repositories/snapshots")
}

implementation("io.github.optimumcode:json-schema-validator:0.0.8-SNAPSHOT")

Groovy

repositories {
  maven { url 'https://s01.oss.sonatype.org/content/repositories/snapshots' }
}

implementation 'io.github.optimumcode:json-schema-validator:0.0.8-SNAPSHOT'

Example

import io.github.optimumcode.json.schema.JsonSchema
import io.github.optimumcode.json.schema.ValidationError
import kotlinx.serialization.json.JsonElement

val key = "\$" // to use $ in multiline string
val schema = JsonSchema.fromDefinition(
  """
  {
    "${key}schema": "http://json-schema.org/draft-07/schema#",
    "definitions": {
      "positiveInteger": {
        "type": "integer",
        "minimum": 0
      }
    },
    "properties": {
      "size": { "${key}ref": "#/definitions/positiveInteger" }
    }
  }
  """.trimIndent(),
)
val errors = mutableListOf<ValidationError>()
val elementToValidate: JsonElement = loadJsonToValidate()

val valid = schema.validate(elementToValidate, errors::add)

Supported JSON schema drafts:

• Draft 7

  Supported keywords

  • Core

  Keyword	Status
  $id	Supported. $id in sub-schemas are collected as well and can be used in $ref
  $schema	Supported. Validates if schema is one of the supported schemas. The last supported is used if empty
  $ref	Supported
  definitions	Supported. Definitions are loaded and can be referenced

  • Assertions

  Category	Assertion	Status
  General	type	Supported all type defined in the specification
  	enum	Supported
  	const	Supported
  Numbers	multipleOf	Supported
  	maximum	Supported
  	exclusiveMaximum	Supported
  	minimum	Supported
  	exclusiveMinimum	Supported
  Strings	maxLength	Supported
  	minLength	Supported
  	pattern	Supported (kotlin.text.Regex is used)
  Arrays	items	Supported
  	additionalItems	Supported
  	maxItems	Supported
  	uniqueItems	Supported
  	contains	Supported
  Objects	maxProperties	Supported
  	minProperties	Supported
  	required	Supported
  	properties	Supported
  	patternProperties	Supported (kotlin.text.Regex is used)
  	additionalProperties	Supported
  	dependencies	Supported
  	propertyNames	Supported
  Conditions	if/then/else	Supported
  Boolean logic	allOf	Supported
  	anyOf	Supported (all validation will be executed even if the element matches the first one)
  	oneOf	Supported
  	not	Supported

• Draft 2019-09

  Supported keywords

  • Core

  Keyword	Status
  $id	Supported. $id in sub-schemas are collected as well and can be used in $ref
  $schema	Supported. Validates if schema is one of the supported schemas. The last supported is used if empty
  $ref	Supported
  $recursiveRef	Supported
  $defs/definitions	Supported. Definitions are loaded and can be referenced
  $vocabulary	Supported. You can disable and enable vocabularies through custom meta-schemes

  • Assertions

  Category	Assertion	Status
  General	type	Supported all type defined in the specification
  	enum	Supported
  	const	Supported
  Numbers	multipleOf	Supported
  	maximum	Supported
  	exclusiveMaximum	Supported
  	minimum	Supported
  	exclusiveMinimum	Supported
  Strings	maxLength	Supported
  	minLength	Supported
  	pattern	Supported (kotlin.text.Regex is used)
  Arrays	items	Supported
  	additionalItems	Supported
  	unevaluatedItems	Supported
  	maxItems	Supported
  	uniqueItems	Supported
  	contains	Supported
  	minContains	Supported (does not affect the work of contains assertion anyhow even if minContains=0)
  	maxContains	Supported
  Objects	maxProperties	Supported
  	minProperties	Supported
  	required	Supported
  	properties	Supported
  	patternProperties	Supported (kotlin.text.Regex is used)
  	additionalProperties	Supported
  	unevaluatedProperties	Supported
  	dependentRequired	Supported
  	dependentSchemas	Supported
  	propertyNames	Supported
  Conditions	if/then/else	Supported
  Boolean logic	allOf	Supported
  	anyOf	Supported (all validation will be executed even if the element matches the first one)
  	oneOf	Supported
  	not	Supported

• Draft 2020-12

  Supported keywords

  • Core

  Keyword	Status
  $id	Supported. $id in sub-schemas are collected as well and can be used in $ref
  $schema	Supported. Validates if schema is one of the supported schemas. The last supported is used if empty
  $ref	Supported
  $dynamicRef/$dynamicAnchor	Supported
  $defs/definitions	Supported. Definitions are loaded and can be referenced
  $vocabulary	Supported. You can disable and enable vocabularies through custom meta-schemes

  • Assertions

  Category	Assertion	Status
  General	type	Supported all type defined in the specification
  	enum	Supported
  	const	Supported
  Numbers	multipleOf	Supported
  	maximum	Supported
  	exclusiveMaximum	Supported
  	minimum	Supported
  	exclusiveMinimum	Supported
  Strings	maxLength	Supported
  	minLength	Supported
  	pattern	Supported (kotlin.text.Regex is used)
  Arrays	prefixItems	Supported
  	items	Supported
  	unevaluatedItems	Supported
  	maxItems	Supported
  	uniqueItems	Supported
  	contains	Supported
  	minContains	Supported
  	maxContains	Supported
  Objects	maxProperties	Supported
  	minProperties	Supported
  	required	Supported
  	properties	Supported
  	patternProperties	Supported (kotlin.text.Regex is used)
  	additionalProperties	Supported
  	unevaluatedProperties	Supported
  	dependentRequired	Supported
  	dependentSchemas	Supported
  	propertyNames	Supported
  Conditions	if/then/else	Supported
  Boolean logic	allOf	Supported
  	anyOf	Supported (all validation will be executed even if the element matches the first one)
  	oneOf	Supported
  	not	Supported

Custom assertions

You can implement custom assertions and use them. Read more here.

Compliance to JSON schema test suites

This library uses official JSON schema test suites as a part of the CI to make sure the validation meet the expected behavior. Not everything is supported right now but the missing functionality might be added in the future. The test are located here.

NOTE: Python 3.* is required to run test-suites. It is used to generate list of remote schemas using this script

This library is also integrated into bowtie and runs against the official test suite along with other libraries. You can find the report here.

Benchmarking

There is a benchmark project that compares this library with some other ones:

• OpenAPI schema validator
• Networknt Schema Validator

The benchmark is scheduled to run every night on Monday. You can see the results in the latest workflow execution.

Developer notes

The update to Kotlin 1.9.22 came with an issue for JS incremental compilation. In case you see an error about main function that already bind please execute clean task.

Future plans

• Add $schema property validation (if not set the latest supported will be used)
• Add proper $id support (for nested schemas and for referencing)
• Add support for newer drafts
  • Draft 2019-09 (Draft 8)
  • 2020-12
• Add support for schemas from external documents
  • Load schemas from local sources
  • Load schemas from remote sources
• Formalize error output as it is defined in the latest drafts (have not fully decided if it should be done)