Command line reference

Usage: schematrix [OPTIONS] INPUT [INPUT...]

Generate code matching a JSON Schema

Options:
      --closed-shapes      Treat absent additionalProperties as false: closed
                           classes with no catch-all, instead of the spec
                           default
      --enums string       Enum slot types: classes or unions (default depends
                           on generators)
  -g, --generators list    Output generators to use, e.g.: plain_ruby,
                           dsl_plain_ruby
  -h, --help               Print usage
      --immutable          Generate data classes as frozen value objects:
                           readers, a with copier, and value equality; data
                           generators only
  -m, --module string      Module where the output code will be placed
  -o, --output string      Directory where the output will be written
      --schema-dir string  Directory where remote schema URIs resolve to local
                           files; may be given multiple times, defaults to
                           vendor/schemas
  -v, --verbose            Each additional occurrence lowers logger level,
                           -vvv for the minimum

Examples:
  Produce plain Ruby code for the given schema
    $ schematrix -g plain_ruby -m MyModule -o /output/dir my-json-schema.json

Inputs

INPUT names one or more schema documents. Each one is a compilation root: the compiler walks every schema node reachable from it, following $ref edges, and generates a class per object schema it finds. JSON and YAML both load.

Two input files may not share a basename (a.json and a.yaml fold to the same class name). The run refuses with OutputCollisionError before any file is written. See Names and files.

Options

`-g, --generators`

Required. One or more generator names, given as repeated flags or as a comma-separated list. The names are plain_ruby, sorbet_ruby, rbi, rbs, the dsl_ prefixed builders of each (dsl_plain_ruby, dsl_sorbet_ruby, dsl_rbi, dsl_rbs), dsl_parser, the four partial_ generators, and plain_ruby_enums, sorbet_ruby_enums, rbi_enums, rbs_enums. Only the *_enums generators write enum files. There is also auxiliary_files, the run-once generator that writes the auxiliary files (see generators). An unknown name stops the run with a fatal log message and exit status 1.

schematrix -g plain_ruby,rbs,auxiliary_files -m MyApp schema.json
schematrix -g plain_ruby -g rbs -g auxiliary_files -m MyApp schema.json

Generate a standalone parser for DSL source:

schematrix -g dsl_parser -m MyApp -o out input.json

This writes out/parser/input.rb and automatically includes out/parser/runtime.rb and out/parser/parse_error.rb. It needs no builder or enum generator and no separate support generator. Generated parsers require Prism 1.4 or later, but do not need Schematrix at runtime. See The instance DSL for parsing and error handling.

`-m, --module`

Required. The namespace the generated code is placed in. Dotted names nest modules:

schematrix -g plain_ruby -m "Acme::Contracts" schema.json

`-o, --output`

Optional. The output directory, created when missing. The flag pairs with -g:

No -o: every generator writes to generated/.
One -o: every generator writes to that directory. Generators with different file extensions (.rb, .rbs, .rbi) share a directory without colliding.
One -o per -g: each generator writes to its own directory, paired in flag order.

A count of output directories that matches neither 1 nor the generator count stops the run with exit status 1.

# Ruby code in generated/, RBS in sig/
schematrix -g plain_ruby -o generated -g rbs -o sig schema.json

# Both formats in generated/
schematrix -g plain_ruby,rbs -o generated schema.json

Two generators writing the same schema site with the same extension and directory collide with OutputCollisionError. Data and enum writers can share a directory and extension because their sites differ.

`--closed-shapes`

The JSON Schema default for an absent additionalProperties is “extra keys accepted”. The flag switches that default to “closed”: generated classes carry no catch-all accessors and drop unknown keys on load. Explicit additionalProperties in the document always wins over the flag. See Schema features.

`--enums`

Selects classes or unions for every generator in the run. Other values stop the run with exit status 1. Without the flag, any *_enums generator selects classes; otherwise the default is unions. An explicit flag overrides that default.

schematrix -g plain_ruby,plain_ruby_enums,auxiliary_files -m MyApp person.schema.json
schematrix -g rbs --enums unions -m MyApp person.schema.json

classes makes qualifying enum slots reference generated classes. Without an enum writer it warns and continues, leaving the caller to supply those constants. unions spells literal unions in RBS and scalar types in Sorbet. Enum writers still write files when the flag is unions; the slots simply do not use the classes. See Enums.

`--immutable`

Generates data classes as frozen value objects: readers instead of accessors, frozen instances, a with copier, and value equality. The flag applies to every data generator of the run; the dsl_ builders are unaffected, since a builder is mutable by construction. See Immutable classes.

`--schema-dir`

Remote schema URIs (http/https $ref targets) never touch the network. They resolve to files under the given directories, which mirror the URI as host/path. The flag may repeat; directories are searched in order, and the first match wins. With no flag the default is vendor/schemas; an explicit --schema-dir replaces the default entirely. See Schema features for the layout.

`-v, --verbose`

Sets the log level of the built-in TTY::Logger output on stderr:

Occurrences	Level
none	warn
`-v`	info
`-vv`	debug
`-vvv`	debug

Debug output logs CLI arguments, each written file, ignored keywords, and $dynamicRef fallbacks.