Skip to content

JSON Schema

field_struct-json_schema takes the JSON a struct writes with to_json and reads with from_json, and describes it as a JSON Schema (draft 2020-12). It does not validate anything itself. The schema goes to whatever validator, documentation tool or code generator you already run.

gem 'field_struct-json_schema'
require 'field_struct/json_schema'

Requiring it adds FieldStruct::JSONSchema and nothing more. Your own classes stay as they were until you opt in (see How adapters work).

FieldStruct::JSONSchema.generate takes a struct class and hands back a Hash with String keys.

require 'field_struct/json_schema'
class CatalogCard < FieldStruct::Base
required :title, :string
required :shelfmark, :string, format: /\A\d{6}\z/
optional :folios, :integer, in: 1..900
optional :tier, :symbol, enum: %i[open sealed]
optional :keywords, :array, of: :string
serialize :json, folios: 'folioCount'
end
schema = FieldStruct::JSONSchema.generate(CatalogCard)
schema['title'] # => "CatalogCard"
schema['required'] # => ["title", "shelfmark"]
schema['properties'].keys # => ["title", "shelfmark", "folioCount", "tier", "keywords"]
schema['properties']['shelfmark'] # => {"type"=>"string", "pattern"=>"^\\d{6}$"}
schema['properties']['folioCount'] # => {"type"=>["integer", "null"], "minimum"=>1, "maximum"=>900}

Property names follow what to_json writes, which is why folios appears as folioCount. A field is required in the schema when it is required and has no default, since a default fills in a missing key. Optional fields also accept null.

Each generate call returns a fresh copy, so editing one result never touches another.

class Valuation < FieldStruct::Base
required :insured_for, :big_decimal
end
FieldStruct::JSONSchema.generate(Valuation)['properties']['insured_for'] # => {"type"=>"number"}
FieldStruct::JSONSchema.generate(Valuation, decimals: :string)['properties']['insured_for'] # => {"type"=>"string", "pattern"=>"^-?[0-9]+\\.[0-9]+$"}

A :hash field is an object whose keys can be anything. The value schema goes under additionalProperties, and like an array element, a value may be null.

class Reliquary < FieldStruct::Base
optional :loans, :hash, of: :integer, element: {in: 0..40}
end
FieldStruct::JSONSchema.generate(Reliquary)['properties']['loans']
# => {"type"=>["object", "null"], "additionalProperties"=>{"type"=>["integer", "null"], "minimum"=>0, "maximum"=>40}}

If you want CatalogCard.to_json_schema as a class method, include the opt-in module.

class Curator < FieldStruct::Base
include FieldStruct::JSONSchema::Methods
required :surname, :string
end
Curator.to_json_schema == FieldStruct::JSONSchema.generate(Curator) # => true

Use case: validate a payload in another service

Section titled “Use case: validate a payload in another service”

Say a second service receives what the archive app sends and wants to turn away bad payloads before its own code sees them. Publish the schema as a file and let that service load it into its validator. The validator below is json_schemer, a separate gem that this adapter does not depend on.

require 'json_schemer'
validator = JSONSchemer.schema(schema)
good = JSON.parse(CatalogCard.new(title: 'Tide tables', shelfmark: '204117', folios: 88).to_json)
good # => {"title"=>"Tide tables", "shelfmark"=>"204117", "folioCount"=>88, "tier"=>nil, "keywords"=>nil}
validator.valid?(good) # => true
bad = { 'title' => 'Tide tables', 'shelfmark' => 'A12' }
validator.valid?(bad) # => false
validator.validate(bad).map { |error| error['error'] } # => ["string at `/shelfmark` does not match pattern: ^\\d{6}$"]

For canonical JSON the schema is exact: it accepts what the struct accepts and rejects what the struct rejects. The to_json of any valid instance passes.

Use case: API documentation and nested structs

Section titled “Use case: API documentation and nested structs”

A nested struct is written once under $defs and referenced by name. The root class is referenced as #, so a recursive struct works. An anonymous struct is inlined.

class Annotation < FieldStruct::Base
required :rating, :integer, in: 1..5
optional :remark, :string
end
class Exhibit < FieldStruct::Base
required :name, :string
optional :annotations, :array, of: Annotation
optional :companion, Exhibit
end
exhibit = FieldStruct::JSONSchema.generate(Exhibit)
exhibit['$defs'].keys # => ["Annotation"]
exhibit['properties']['annotations']['items'] # => {"anyOf"=>[{"$ref"=>"#/$defs/Annotation"}, {"type"=>"null"}]}
exhibit['properties']['companion'] # => {"anyOf"=>[{"$ref"=>"#"}, {"type"=>"null"}]}

A field’s description: turns into the schema’s description, and a default that to_json would write turns into default. A sensitive field is tagged x-sensitive, and its default stays out.

class AccessGrant < FieldStruct::Base
required :reader, :email, description: 'Address that receives the grant'
optional :tier, :string, enum: %w[public staff], default: 'public'
required :vault_code, :string, sensitive: true, default: 'hush'
end
props = FieldStruct::JSONSchema.generate(AccessGrant)['properties']
props['reader']['description'] # => "Address that receives the grant"
props['tier']['default'] # => "public"
props['vault_code'] # => {"x-sensitive"=>true, "type"=>"string"}

Use case: an action’s input as tool parameters

Section titled “Use case: an action’s input as tool parameters”

An action’s input block defines a struct, so its schema is a single call away. That schema is what a model needs in order to call the action as a tool. The tools adapter wraps this up for you, safety rules included.

class SearchCards < Actionable::Action
input do
required :phrase, :string
optional :max_hits, :integer, in: 1..50
end
end
params = FieldStruct::JSONSchema.generate(SearchCards.input_schema)
params['properties'].keys # => ["phrase", "max_hits"]
params['required'] # => ["phrase"]

The json_schema: option on a field replaces the derived schema. It accepts a Hash, true (no constraint) or false (nothing validates). A custom type can define a json_schema method to the same end, and a type with neither comes out unconstrained and tagged x-ruby-type.

require 'field_struct/json_schema' registers json_schema: as a field option (with FieldStruct.register_option), so require the adapter before the classes that use it. Until then, the option raises and says which file to require.

class Drawer < FieldStruct::Base
required :label, :string, json_schema: { 'type' => 'string', 'minLength' => 4 }
optional :contents, :value, json_schema: false
end
FieldStruct::JSONSchema.generate(Drawer)['properties']['label'] # => {"type"=>"string", "minLength"=>4}

A bad override raises ArgumentError and names the class and field.

Ruby and JavaScript do not treat Regexps the same way. FieldStruct::JSONSchema.pattern_for translates a Ruby Regexp into an ECMA-262 pattern that matches exactly the same strings, or returns nil. Close enough is never good enough here, so any doubt means nil.

FieldStruct::JSONSchema.pattern_for(/\A\d+-\d+\z/) # => "^\\d+-\\d+$"
FieldStruct::JSONSchema.pattern_for(/\bnote\b/) # => nil
FieldStruct::JSONSchema.pattern_for(/\A(x+)+\z/) # => nil

The last Regexp has an exact translation, but a backtracking JavaScript engine could spend exponential time on it, so the adapter refuses. In a struct, a format: Regexp that can’t be translated becomes x-ruby-pattern, an annotation that no validator checks.

class Crate < FieldStruct::Base
required :tag, :string, format: /\A[A-Z]{2}-\d{5}\z/
required :donor, :string, format: /\A\p{L}+\z/
end
props = FieldStruct::JSONSchema.generate(Crate)['properties']
props['tag'] # => {"type"=>"string", "pattern"=>"^[A-Z]{2}-\\d{5}$"}
props['donor'] # => {"type"=>"string", "x-ruby-pattern"=>"\\A\\p{L}+\\z"}
Option On Meaning
serialization: generate which serialize mapping names the properties; default :json
decimals: generate :to_json (the default) describes decimals as to_json writes them; :string describes them all as the decimal string as_json gives
freeze: generate, to_json_schema true returns the shared, deep-frozen schema instead of a fresh copy; default false
json_schema: a field a Hash, true or false that replaces the derived schema
description: a field becomes description
sensitive: a field adds x-sensitive and hides the default
length: a string field becomes minLength and maxLength; :binary counts bytes, so it gets maxLength only
nullable: true a required field keeps it in required, and its type also takes "null"

FieldStruct::JSONSchema.clear_cache empties the per-class cache. That cache keeps classes alive, so call it whenever code reloads.

If you only read the schema, to validate a payload or list it somewhere, pass freeze: true. You get the cached schema itself instead of a copy, deep-frozen, and the same object on every call:

shared = FieldStruct::JSONSchema.generate(CatalogCard, freeze: true)
shared.frozen? # => true
shared.equal?(FieldStruct::JSONSchema.generate(CatalogCard, freeze: true)) # => true

Changing a frozen schema raises FrozenError. A schema that asked a custom type’s json_schema hook is never cached, so freeze: true freezes it but builds it again on each call.

A rule the adapter doesn’t map is left out. It never approximates.

  • in: on dates, times and decimals, max_items:, strict:, base: and round: are left out of the schema. The struct still enforces them.
  • A decimal is a number, because to_json writes it as one. A field declared json: :string is a string matching a decimal pattern instead. If you send as_json rather than to_json, ask for generate(klass, decimals: :string), which describes every decimal that way.
  • format: on a date or time becomes format only for the default or :iso8601 form.
  • An optional string field with enum: or format: accepts a blank string too, since the struct reads a blank string as missing.
  • unknown_attributes :raise on a struct adds additionalProperties: false.
  • The cache notices a new or redeclared field, but not an enum: Array edited in place. Redeclare the field instead.

FieldStruct, Actionable and their adapters are open source under the MIT license.