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).
The schema of a struct
Section titled “The schema of a struct”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_decimalend
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, :stringend
Curator.to_json_schema == FieldStruct::JSONSchema.generate(Curator) # => trueUse 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) # => falsevalidator.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, :stringend
class Exhibit < FieldStruct::Base required :name, :string optional :annotations, :array, of: Annotation optional :companion, Exhibitend
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 endend
params = FieldStruct::JSONSchema.generate(SearchCards.input_schema)params['properties'].keys # => ["phrase", "max_hits"]params['required'] # => ["phrase"]Overrides
Section titled “Overrides”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: falseend
FieldStruct::JSONSchema.generate(Drawer)['properties']['label'] # => {"type"=>"string", "minLength"=>4}A bad override raises ArgumentError and names the class and field.
Regexps with pattern_for
Section titled “Regexps with pattern_for”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/) # => nilFieldStruct::JSONSchema.pattern_for(/\A(x+)+\z/) # => nilThe 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"}Options
Section titled “Options”| 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? # => trueshared.equal?(FieldStruct::JSONSchema.generate(CatalogCard, freeze: true)) # => trueChanging 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.
Limits
Section titled “Limits”A rule the adapter doesn’t map is left out. It never approximates.
in:on dates, times and decimals,max_items:,strict:,base:andround:are left out of the schema. The struct still enforces them.- A decimal is a
number, becauseto_jsonwrites it as one. A field declaredjson: :stringis a string matching a decimal pattern instead. If you sendas_jsonrather thanto_json, ask forgenerate(klass, decimals: :string), which describes every decimal that way. format:on a date or time becomesformatonly for the default or:iso8601form.- An optional string field with
enum:orformat:accepts a blank string too, since the struct reads a blank string as missing. unknown_attributes :raiseon a struct addsadditionalProperties: false.- The cache notices a new or redeclared field, but not an
enum:Array edited in place. Redeclare the field instead.
See also
Section titled “See also”FieldStruct, Actionable and their adapters are open source under the MIT license.