The JSONSchema.make function allows you to generate a JSON Schema from a schema.
Example (Creating a JSON Schema for a Struct)
The following example defines a Person schema with properties for name (a string) and age (a number). It then generates the corresponding JSON Schema.
The JSONSchema.make function aims to produce an optimal JSON Schema representing the input part of the decoding phase.
It does this by traversing the schema from the most nested component, incorporating each refinement, and stops at the first transformation encountered.
Example (Excluding Transformations in JSON Schema)
Consider modifying the age field to include both a refinement and a transformation. Only the refinement is reflected in the JSON Schema.
In this case, the JSON Schema reflects the integer refinement but does not include the transformation that clamps the value.
Specific Outputs for Schema Types
Literals
Literals are transformed into enum types within JSON Schema.
Example (Single Literal)
Example (Union of literals)
Void
Any
Unknown
Object
String
Number
Boolean
Tuples
Arrays
Non Empty Arrays
Represents an array with at least one element.
Example
Structs
Records
Mixed Structs with Records
Combines fixed properties from a struct with dynamic properties from a record.
Example
Enums
Template Literals
Unions
Unions are expressed using anyOf or enum, depending on the types involved:
Example (Generic Union)
Example (Union of literals)
Identifier Annotations
You can add identifier annotations to schemas to improve structure and maintainability. Annotated schemas are included in a $defs object in the root of the JSON Schema and referenced from there.
Example (Using Identifier Annotations)
By using identifier annotations, schemas can be reused and referenced more easily, especially in complex JSON Schemas.
Standard JSON Schema Annotations
Standard JSON Schema annotations such as title, description, default, and examples are supported.
These annotations allow you to enrich your schemas with metadata that can enhance readability and provide additional information about the data structure.
Example (Using Annotations for Metadata)
Adding annotations to Struct properties
To enhance the clarity of your JSON schemas, it’s advisable to add annotations directly to the property signatures rather than to the type itself.
This method is more semantically appropriate as it links descriptive titles and other metadata specifically to the properties they describe, rather than to the generic type.
Example (Annotated Struct Properties)
Recursive and Mutually Recursive Schemas
Recursive and mutually recursive schemas are supported, however it’s mandatory to use identifier annotations for these types of schemas to ensure correct references and definitions within the generated JSON Schema.
Example (Recursive Schema with Identifier Annotations)
In this example, the Category schema refers to itself, making it necessary to use an identifier annotation to facilitate the reference.
Customizing JSON Schema Generation
When working with JSON Schema certain data types, such as bigint, lack a direct representation because JSON Schema does not natively support them.
This absence typically leads to an error when the schema is generated.
Example (Error Due to Missing Annotation)
Attempting to generate a JSON Schema for unsupported types like bigint will lead to a missing annotation error:
To address this, you can enhance the schema with a custom jsonSchema annotation, defining how you intend to represent such types in JSON Schema:
Example (Using Custom Annotation for Unsupported Type)
Refinements
When defining a refinement (e.g., through the Schema.filter function), you can include a JSON Schema annotation to describe the refinement. This annotation is added as a “fragment” that becomes part of the generated JSON Schema. If a schema contains multiple refinements, their respective annotations are merged into the output.
Example (Using Refinements with Merged Annotations)
The jsonSchema annotation is defined as a generic object, allowing it to represent non-standard extensions. This flexibility leaves the responsibility of enforcing type constraints to the user.
If you prefer stricter type enforcement or need to support non-standard extensions, you can introduce a satisfies constraint on the object literal. This constraint should be used in conjunction with the typing library of your choice.
Example (Ensuring Type Correctness)
In the following example, we’ve used the @types/json-schema package to provide TypeScript definitions for JSON Schema. This approach not only ensures type correctness but also enables autocomplete suggestions in your IDE.
For schema types other than refinements, you can override the default generated JSON Schema by providing a custom jsonSchema annotation. The content of this annotation will replace the system-generated schema.
Example (Custom Annotation for a Struct)
Specialized JSON Schema Generation with Schema.parseJson
The Schema.parseJson function provides a unique approach to JSON Schema generation. Instead of defaulting to a schema for a plain string, which represents the “from” side of the transformation, it generates a schema based on the structure provided within the argument.
This behavior ensures that the generated JSON Schema reflects the intended structure of the parsed data, rather than the raw JSON input.
Example (Generating JSON Schema for a Parsed Object)