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:
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.
[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.