Related packages

JSON Schema and Julia types meet in a few different problems, which different packages solve:

  1. Validating JSON documents against a schema, keeping them as dictionaries.
  2. Generating Julia types from a schema (what JSONSchema2Types.jl does), to read, write and build documents as typed values.
  3. Generating a schema from Julia types: describing existing structs, e.g. for an API or for the tools of an LLM agent.
  4. Generating Julia types from sample JSON, without a schema.
  5. Reading JSON into hand-written Julia types.

Packages

Validators

  • JSONSchema.jl (JuliaIO) validates parsed JSON documents against a schema with validate(schema, data), which returns nothing or a report of the first failure, with its location. It supports drafts 4, 6 and 7, and is tested with the corresponding parts of the JSON Schema Test Suite. It does not implement the newer keywords of 2019-09 and 2020-12 (unevaluatedProperties, prefixItems, $dynamicRef...), nor the checks of format. Recent versions also generate simple schemas from Julia types, with JSONSchema.schema(T) (problem 3).
  • CorvusJsonSchema.jl is a JSON Schema evaluator ported from the .NET library Corvus.JsonSchema. It supports drafts 4, 6, 7, 2019-09 and 2020-12, passes the whole JSON Schema Test Suite (required and optional tests, including $dynamicRef and the IDN formats) and its annotation tests, has no dependencies, and is fast and allocation-free. It validates JSON text or parsed documents (compile_schema, isvalid, validate), with detailed results; it does not generate types.

From Julia types to schemas

  • JSONSchema.jl, with JSONSchema.schema(T): small schemas for named tuples, concrete structs, scalars, vectors, dicts, tuples and Union{Nothing, T}, inlined (no $refs), meant for the parameters of agent tools and APIs.
  • JSONSchemaGenerator.jl generates minimal schemas from structs declared with StructTypes.jl, optionally with $refs to $defs, and with allOf/anyOf/oneOf/not through special types. It does not support parametric types, nor unions other than Union{Nothing, T}.
  • Struct2JSONSchema.jl generates 2020-12 schemas from existing structs without modifying them, with hooks to customize the schema of types and fields (formats, descriptions from docstrings, defaults, optional fields), and never fails: what it cannot represent becomes {}.

From JSON to Julia types

  • JSON3.jl generates types from sample JSON documents (JSON3.@generatetypes, JSON3.writetypes), inferred from the data rather than from a schema, to read documents with StructTypes.jl.
  • JSON.jl 1.x reads JSON directly into hand-written types (JSON.parse(json, T)), with the conventions of StructUtils.jl for names, defaults and unions.

In other languages

The idea of generating types from a schema is common elsewhere: for instance quicktype (many languages), datamodel-code-generator (Python, Pydantic models) and Corvus.JsonSchema itself (C#).

Comparison

JSONSchema2Types.jlJSONSchema.jlCorvusJsonSchema.jlJSONSchemaGenerator.jl, Struct2JSONSchema.jlJSON3.jl types
Directionschema → Julia typesschema → validation (and simple types → schema)schema → validationJulia types → schemasample JSON → Julia types
Drafts2020-12 (and earlier)4, 6, 74 to 2020-122020-12 (Struct2JSONSchema)—
Typed access to documentsyesnono—yes
Reading and writing documentsyes, lossless (unknown properties kept)———yes
Validationin constructors and when reading; 95% of the test suitedrafts 4–7100% of the test suite—no
Numeric typeschosen by the user (Int64/Float64, BigInt/BigFloat, ...)———inferred
Outputa self-contained Julia module (one file or one per schema file)——a schemaa Julia module

These packages can be combined. A schema can be used with JSONSchema2Types.jl for typed access to documents and with CorvusJsonSchema.jl for a complete validation, e.g. of documents coming from untrusted sources before reading them. And a schema written for Julia types with Struct2JSONSchema.jl can be turned back into a module with JSONSchema2Types.jl, to share the types with other languages and tools through the schema.