Template Format

File structure

A template has a top-level definitions array, plus optional project-wide settings. The base package comes from the file's path under src/main/resources/nomos/templates/.

{
  "listType": "List",
  "definitions": [
    {
      "name": "User",
      "subPackage": "user",
      "description": "A user record",
      "template": { "id": "string" }
    }
  ]
}

Scalar types

Constraints

Use the long form { "type": ..., ...constraints } to attach validation constraints.

{
  "username": { "type": "string", "minLength": 1, "maxLength": 40, "pattern": "^[a-z0-9_]+$" },
  "email":    { "type": "string", "format": "email" },
  "age":      { "type": "int", "min": 0, "max": 150 },
  "ratio":    { "type": "number", "multipleOf": 0.5 }
}

Built-in format values (register more — see Validation):

A required string field may also declare an adapter to map between its on-the-wire form and the model value, e.g. { "type": "string", "adapter": "epochMillis" }. Adapters are accepted only on required string fields — see Validation.

Enums

A closed value set either validates a String, or generates a dedicated enum type.

To validate a string against a closed set:

{ "priority": { "type": "string", "enum": ["low", "medium", "high"] } }

To generate a sealed-trait enum type named Priority and type the field as it:

{ "priority": { "type": "string", "enum": ["low", "high"], "as": "enumType", "name": "Priority" } }

Arrays & maps

{
  "tags":   ["string"],
  "scores": { "type": "array", "items": "number", "minItems": 1, "uniqueItems": true },
  "entries": { "type": "array", "items": "$ref:Entry", "uniqueBy": "id" },
  "labels": { "type": "array", "items": "string", "enum": ["red", "green", "blue"] },
  "settings": { "$map": "string" }
}

uniqueItems compares whole elements, so two objects sharing an id but differing elsewhere both pass it. uniqueBy compares only the named field, and a list of names forms a composite key ("uniqueBy": ["group", "name"]). A duplicate is reported at the offending element's index, naming the key fields. Elements that are not objects, or that omit a key field, carry no key and are skipped — their shape is already reported by the element's own type check.

$map generates a Map[String, T] with unrestricted keys and validated values. Set the project-wide mapType to java.util.Map to generate java.util.Map[String, T] instead — useful when the generated models are consumed from Java.

A JSON array with more than one element type is a union. It generates an Any-typed field whose value round-trips as-is (the codec passes the raw JSON through, so branches aren't validated individually):

{ "value": ["string", "number"] }

Extra object properties

By default an object rejects any property not named in its template. $additionalProperties relaxes that:

{ "id": "string", "$additionalProperties": "string" }

Presence groups

Some objects offer several mutually exclusive ways to say the same thing — an inline value or a reference to one, but not both. Each key is optional on its own, and a presence group declared on the enclosing object decides how many of them must be present.

{
  "$oneOf": ["inline_value", "value_ref"],
  "inline_value": { "$optional": "string" },
  "value_ref":    { "$optional": "string" }
}

Wrap the key list in $optional to also accept none of them being present — a $oneOf group still rejects more than one:

{ "$oneOf": { "$optional": ["inline_value", "value_ref"] } }

A key present with a JSON null counts as absent, matching how decoding treats null for an optional field. Both directives may appear on the same object (and on a discriminator variant), and each is checked independently.

The listed keys must be declared siblings and must be optional — the group, not the field, decides what is required. A group naming an undeclared key, a required key, a duplicate key, or fewer than two keys is a template error rather than a rule that can never hold.

Optional, nullable & defaults

{
  "nickname": { "$optional": "string" },
  "tags":     { "$optional": ["string"], "nullable": true },
  "region":   { "$optional": "string", "nullable": "surfaceOnly" },
  "retries":  { "$optional": "int", "nullable": true },
  "verbose":  { "type": "boolean", "default": false }
}

References

{
  "address":  "$ref:Address",
  "shipping": "$gen:com.example.other.Address",
  "rule":     "$extern:com.example.legacy.Rule"
}

Self-references (recursive types) work too: a TreeNode may contain ["$ref:TreeNode"].

Type discriminators

A discriminator becomes a sealed trait with a case-class variant per value.

Prefix matching supports parameterized tags while preserving the complete discriminator value:

{
  "$type": {
    "discriminator": "kind",
    "variantMatch": "prefix",
    "variants": {
      "Decimal": { "scale": "int" },
      "String": {}
    }
  }
}

Regex matching constrains the complete tag syntax and requires an explicit class name for every pattern:

{
  "$type": {
    "discriminator": "kind",
    "variantMatch": "regex",
    "variantNames": {
      "^Decimal(\\((\\d{1,2}),(\\d{1,2})\\))?$": "DecimalColumn",
      "^Circle$": "Circle"
    },
    "variantSubPackage": "shapes",
    "commonFields": { "label": "string" },
    "variants": {
      "^Decimal(\\((\\d{1,2}),(\\d{1,2})\\))?$": { "scale": "int" },
      "^Circle$":  "$ref:Circle"
    }
  }
}

Reserved keys & escaping

A field literally named like a template keyword (type, enum, …) must be backtick-quoted so it's read as a field, not a directive. Nomos strips the backticks and re-escapes Scala keywords in the output.

{ "name": "string", "`type`": "string" }

Next: Validation — how the embedded template validates JSON, and how to extend it.