Schema reference

2. Columns.

One [[columns]] block per column. Three fields per block.

Extended column types

Beyond the six core scalars, OriginChain accepts purpose-built types. Each is format-validated at write time — a value of the wrong shape is rejected with a 400 type-mismatch. They store and index on the same substrate as their backing scalar, so range scans and filters stay fast.

Picking the right type for common data

3. Indexes.

One [[indexes]] block per index. Without indexes, every filter does a full table scan.

[[indexes]]
name    = "by_status"
columns = ["status"]                  # single-column

[[indexes]]
name    = "by_customer_and_time"
columns = ["customer_id", "placed_ms"]  # composite, in declared order

When to add an index: any column you filter on in WHERE or use as a foreign-key target. Indexes cost write throughput - don't add them speculatively.

4. Relations (graph edges).

A relation turns a foreign-key column into a graph edge. The forward and reverse edges are written atomically when you save a row.

[[relations]]
name          = "supplied_by"         # the verb you'll walk in code
from_col      = "supplier_id"         # the FK column on THIS table
bidirectional = true                  # default; reverse edge written atomically

[relations.target]
namespace = "shop"                    # target table's namespace
table     = "suppliers"               # target table's name
pk        = "id"                      # target table's primary-key column

# Self-relations work - direction tags resolve the collision:
[[relations]]
name          = "follows"
from_col      = "followee_id"
bidirectional = true

[relations.target]
namespace = "social"
table     = "users"
pk        = "id"

Relations alone do not enforce that the target row exists. For that, also declare a foreign key (next section).

5. Foreign keys.

Reject writes that point at non-existent rows. The integrity check is a single key fetch, so it's fast.

[[foreign_keys]]
name          = "fk_customer"         # optional - defaults to "<from_col>_fk"
from_col      = "customer_id"         # column on THIS table
target_schema = "shop.customers"      # "namespace.table" of the target
target_col    = "id"                  # PK or unique-indexed column on target
on_delete     = "no_action"           # no_action | restrict | set_null

6. CHECK constraints.

Reject writes whose values violate a rule. Checks run on every write - keep them simple.

[[check_constraints]]
name       = "qty_positive"
expression = "qty > 0"

[[check_constraints]]
name       = "country_or_continent_set"
expression = "country IS NOT NULL OR continent IS NOT NULL"

[[check_constraints]]
name       = "status_in_set"
expression = "status IN ('pending', 'paid', 'cancelled')"

Expression grammar

Three-valued logic applies: NULL on any operand yields NULL, which fails the CHECK. If a column can be NULL and you want the CHECK to ignore null values, use col IS NULL OR col > 0.

7. JSON extractions.

Pull a value out of a nested JSON row into a queryable column at write time. Useful when your row body is already-structured JSON and you don't want to flatten it manually.

# Pull a derived column out of a nested JSON row at write time.
# The dotted path walks into the JSON; missing fields emit zero values.

[[extractions]]
name = "customer_country"
path = "customer.address.country"
ty   = "str"

[[extractions]]
name = "order_total_cents"
path = "totals.grand_cents"
ty   = "i64"

Extractions are not the same as vector or full-text indexes. There is no [[extractions.fts]] or [[extractions.vector]] block - those live on separate runtime endpoints.

8. Full example.

Every block from this page in one schema.

# A schema using every block at once.
namespace   = "shop"
table       = "orders"
primary_key = ["id"]

[[columns]]
name = "id"
ty   = "str"
required = true

[[columns]]
name = "customer_id"
ty   = "str"
required = true

[[columns]]
name = "product_id"
ty   = "str"
required = true

[[columns]]
name = "qty"
ty   = "i64"

[[columns]]
name = "total_cents"
ty   = "i64"

[[columns]]
name = "placed_ms"
ty   = "u64"

[[indexes]]
name    = "by_customer"
columns = ["customer_id"]

[[indexes]]
name    = "by_product_and_time"
columns = ["product_id", "placed_ms"]

[[relations]]
name          = "bought_product"
from_col      = "product_id"
bidirectional = true

[relations.target]
namespace = "shop"
table     = "products"
pk        = "id"

[[relations]]
name          = "by_customer"
from_col      = "customer_id"
bidirectional = true

[relations.target]
namespace = "shop"
table     = "customers"
pk        = "id"

[[foreign_keys]]
name          = "fk_customer"
from_col      = "customer_id"
target_schema = "shop.customers"
target_col    = "id"
on_delete     = "restrict"

[[check_constraints]]
name       = "qty_positive"
expression = "qty > 0"

[[check_constraints]]
name       = "total_positive"
expression = "total_cents > 0"