model#

Write a type once, as YAML, and generate it everywhere it is needed: Python structs, TypeScript types with runtime validation, Go structs with JSON codecs, a Kotlin client, and PostgreSQL DDL. The constraints travel with the type, so the same rule is enforced in every language rather than restated in each one.

Install#

pip install model

That gives you the model command and the model package. Generated Python imports from that package at runtime, so it stays a dependency of any project that uses the Python output. The other languages install their own dependencies — see Python, TypeScript, Go, and Kotlin.

A model#

A model is a directory of *.yaml files, one top-level type per file, named after the type it defines:

catalog/Product.yaml#
type: struct
display: Product
desc: Something the shop sells.
fields:
    sku:
        display: SKU
        desc: The stock keeping unit that identifies this product.
        type: string
        required: true
        min_length: 3
        max_length: 32

    name:
        display: Name
        desc: The product's display name.
        type: string
        required: true

    price:
        display: Price
        desc: What the product costs, in the shop's currency.
        type: decimal
        required: true
        min: 0

    tags:
        display: Tags
        desc: Free-form labels used to group products.
        type: list
        values:
            type: string
            min_length: 1

Configure the output#

Which languages are generated, and where each one is written, lives in a model.toml at or above the model directory. A language’s table both turns it on and configures it; a language with no table is not generated. There are no command-line flags for any of this.

model.toml#
[tool.model.python]
out = "catalog.py"

[tool.model.typescript]
out = "catalog.mts"

[tool.model.go]
out = "gocatalog/catalog.go"
package = "gocatalog"

Generate#

model ./catalog
Generated gocatalog/catalog.go
Generated catalog.mts
Generated catalog.py

Each language gets one file, holding every type in the directory.

What comes out#

class Product(Struct, kw_only=True):
    """Something the shop sells."""

    sku: str
    price: Decimal
    tags: list[str] = []

    @classmethod
    def decode_json(cls, data: str | bytes) -> Self: ...
    def validate(self, *, file_path=None, ctx=None): ...

decode_json reads the wire shape and fills in defaults; validate collects every constraint violation and raises them as one ExceptionGroup.

export const ProductSchema = v.object({ /* ... */ });

export interface Product {
    sku: string;
    price: Decimal;
    tags: Array<string>;
}

export const Product = Object.freeze({
    validate(input: unknown): Product {
        return v.parse(ProductSchema, input);
    },
});

The interface and the validator share one name, so Product is both the type and the thing you call validate on.

type Product struct {
    sku   string
    name  string
    price decimal.Decimal
    tags  []string
}

func (self *Product) UnmarshalJSON(data []byte) error
func (self *Product) MarshalJSON() ([]byte, error)
func (self *Product) FromRaw(raw *ProductRaw) error
func (self *Product) ToRaw() ProductRaw
func (self *Product) Validate() error

Fields are unexported by default, so the generated file has to live in the package that uses it. Set pascal-case to export them. ProductRaw is the exported wire form the codecs decode into and encode from.

Where to go next#

Start with Writing a model to write the types, Configuration to configure the build, then the page for whichever language you are consuming.