One template for your models, codecs, and validation.

Why Nomos?

Nomos takes inspiration from schema-first ORM tooling, which generates application code from a central schema. It applies that workflow to JSON-heavy Scala systems, where models, serialization, and validation are often maintained separately and can drift apart. Define the JSON structure once, then generate the Scala interface used by application code.

A hand-written model, its codecs, and its validator are separate descriptions of the same data. Add a field, tighten a constraint, or rename a variant and each copy must change together. Nomos replaces that coordination with generation: one declarative JSON template produces the Scala types, serialization code, and embedded runtime validator.

Nomos is not an ORM and does not manage persistence. It is a build-time source generator for the boundary between JSON and Scala, designed to make that boundary typed, validated, lightweight at runtime, and straightforward to extend with domain-specific rules.

In Greek, nomos (νόμος) is the law — the agreed-upon order a community lives by. Nomos makes your template the law: the single declaration your Scala types and your JSON both answer to.

Compared to annotation libraries

Most JSON tooling annotates a hand-written model — serialization hints and validation constraints declared as field annotations (Gson's @SerializedName, Bean Validation's @NotNull/@Size, and the like). The class stays the source of truth, and serialization and validation rules are scattered across annotations on its fields. Nomos inverts that: the template is the source of truth, and the class, its (de)serialization, and its validator are generated from it.

The trade-off is a build-time generation step instead of plain hand-written classes — in return, the model and its validation are always derived from the same declaration.

A quick look

Drop a template under your resources, matching the package you want: src/main/resources/nomos/templates/com/example/models/user.json

{
  "definitions": [
    {
      "name": "User",
      "subPackage": "user",
      "template": {
        "id": "string",
        "username": { "type": "string", "minLength": 1 },
        "email": { "type": "string", "format": "email" },
        "age": { "$optional": "int" },
        "roles": ["string"]
      }
    }
  ]
}

Run mvn generate-sources, and Nomos writes a case class plus a companion with parse, serialize, and validate:

import com.example.models.user.User

// Validate against the embedded template, then parse — no template file needed at runtime
User.validate("""{"id":"1","username":"jo","email":"jo@x.com","roles":["admin"]}""") match {
  case Right(user)  => println(user.email)
  case Left(errors) => errors.foreach(e => println(e.fullMessage))
}

// Or round-trip directly
val json = User.toJson(user)
val back = User.fromJson(json)   // Either[String, User]

What you get

Where to next

• Getting Started — install, write a template, generate, and use it.
• Template Format — the full template DSL: types, constraints, discriminators.
• Validation — embedded validation, custom validators, formats, adapters.
• Code Generation — what Nomos emits and how to configure it.
• Maven Plugin — wiring generation into your build.