Package org.apache.juneau.bean.jsonschema

package org.apache.juneau.bean.jsonschema

JSON Schema Data Transfer Objects

Overview

Juneau supports serializing and parsing of JSON Schema documents through the use of beans defined in the org.apache.juneau.bean.jsonschema package. These beans are used with the existing JsonSerializer and JsonParser classes to produce and consume JSON Schema documents.

NOTE: This implementation follows the JSON Schema Draft 2020-12 specification. For backward compatibility, deprecated properties from earlier drafts (Draft 04) are still supported.

Bean Classes

The bean classes that make up the model are as follows:

• JsonSchema - Top level schema object.
• JsonSchemaProperty - A subclass of JsonSchema for representing properties.
• JsonSchemaPropertySimpleArray - A convenience subclass of JsonSchemaProperty for representing properties of simple array types.
• JsonSchemaRef - Represents a URI reference to another schema.
• JsonSchemaArray - An array of JsonSchema objects.
• JsonType - An enum of possible JSON data types.
• JsonTypeArray - An array of JsonType objects.

Creating JSON Schema Documents

JSON Schema documents can be constructed using the Juneau JSON Schema beans as a document model object. These beans are defined with fluent-style setters to make constructing documents as easy as possible.

The following is an example JSON Schema document:

{ "title": "Example Schema", "type": "object", "properties": { "firstName": { "type": "string" }, "lastName": { "type": "string" }, "age": { "description": "Age in years", "type": "integer", "minimum": 0 } }, "required": ["firstName", "lastName"] }

This document can be constructed using the following code:

// Create the document object model JsonSchema schema = new JsonSchema() .setTitle("Example Schema") .setType(JsonType.OBJECT) .addProperties( new JsonSchemaProperty("firstName", JsonType.STRING), new JsonSchemaProperty("lastName", JsonType.STRING), new JsonSchemaProperty("age", JsonType.INTEGER) .setDescription("Age in years") .setMinimum(0) ) .addRequired("firstName", "lastName"); // Serialize to JSON String json = JsonSerializer.DEFAULT_READABLE.serialize(schema);

The following is a more-complex example showing various kinds of constraints:

{ "$id": "http://some.site.somewhere/entry-schema#", "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "schema for an fstab entry", "type": "object", "required": [ "storage" ], "properties": { "storage": { "type": "object", "oneOf": [ { "$ref": "#/definitions/diskDevice" }, { "$ref": "#/definitions/diskUUID" }, { "$ref": "#/definitions/nfs" }, { "$ref": "#/definitions/tmpfs" } ] }, "fstype": { "enum": [ "ext3", "ext4", "btrfs" ] }, "options": { "type": "array", "minItems": 1, "items": { "type": "string" }, "uniqueItems": true }, "readonly": { "type": "boolean" } }, "definitions": { "diskDevice": {}, "diskUUID": {}, "nfs": {}, "tmpfs": {} } }

This document can be constructed using the following code:

JsonSchema schema = new JsonSchema() .setIdUri("http://some.site.somewhere/entry-schema#") .setSchemaVersionUri("https://json-schema.org/draft/2020-12/schema") .setDescription("schema for an fstab entry") .setType(JsonType.OBJECT) .addRequired("storage") .addProperties( new JsonSchemaProperty("storage") .setType(JsonType.OBJECT) .addOneOf( new JsonSchemaRef("#/definitions/diskDevice"), new JsonSchemaRef("#/definitions/diskUUID"), new JsonSchemaRef("#/definitions/nsf"), new JsonSchemaRef("#/definitions/tmpfs") ), new JsonSchemaProperty("fstype") .addEnum("ext3", "ext4", "btrfs"), new JsonSchemaPropertySimpleArray("options", JsonType.STRING) .setMinItems(1) .setUniqueItems(true), new JsonSchemaProperty("readonly") .setType(JsonType.BOOLEAN) ) .addDefinition("diskDevice", new JsonSchema()) .addDefinition("diskUUID", new JsonSchema()) .addDefinition("nfs", new JsonSchema()) .addDefinition("tmpfs", new JsonSchema()); // Serialize to JSON String json = JsonSerializer.DEFAULT_READABLE.serialize(schema);

Serializing to Other Data Types

Since the JSON Schema DTOs are simple beans, they can be used to serialize to a variety of other language types as well as JSON. This also allows JSON Schema documents to be easily served up using the Juneau REST API.

Parsing JSON Schema Documents

Use the JsonParser to parse JSON Schema documents into DTOs:

// Use parser to load JSON Schema document into JSON Schema DTOs JsonSchema schema = JsonParser.DEFAULT.parse(json, JsonSchema.class);

Schema objects can also be constructed from other media types using the appropriate parsers.

See Also:

• JSON Schema 2020-12 Core
• JSON Schema 2020-12 Validation
• juneau-bean-jsonschema

Related Packages

Package	Description
org.apache.juneau.bean
org.apache.juneau.bean.atom	ATOM Data Transfer Objects
org.apache.juneau.bean.html5	HTML5 Data Transfer Objects
org.apache.juneau.bean.openapi3
org.apache.juneau.bean.swagger

Class	Description
JsonSchema	Represents a top-level schema object bean in the JSON-Schema core specification.
JsonSchema.BooleanOrSchemaArraySwap	Used during parsing to convert the additionalItems property to the correct class type.
JsonSchema.BooleanOrSchemaSwap	Used during parsing to convert the additionalProperties property to the correct class type.
JsonSchema.JsonSchemaOrSchemaArraySwap	Used during parsing to convert the items property to the correct class type.
JsonSchema.JsonTypeOrJsonTypeArraySwap	Used during parsing to convert the type property to the correct class type.
JsonSchemaArray	Represents a list of JsonSchema objects.
JsonSchemaMap	A container for retrieving JSON JsonSchema objects by URI.
JsonSchemaProperty	Represents a JSON property in the JSON-Schema core specification.
JsonSchemaPropertySimpleArray	Convenience class for representing a property that's an array of simple types.
JsonSchemaRef	Convenience class for representing a schema reference such as "{'$ref':'/url/to/ref'}".
JsonType	Represents possible JSON types in the JSON-Schema core specification.
JsonTypeArray	Represents a list of JsonType objects.