Ontology & Schema

RelataDB uses a schema-as-code ontology model. Types are declared as code, versioned via git branches, and enforced at write time.

Types and properties

Each type has a set of typed properties:

curl -X POST http://localhost:9090/types \
  -H "Authorization: Bearer $RELATA_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Person",
    "properties": [
      {"name": "id", "type": "string", "required": true},
      {"name": "name", "type": "string"},
      {"name": "email", "type": "email"},
      {"name": "birth_date", "type": "datetime"}
    ]
  }'

Supported property types

TypeValidation
string, int, float, boolBasic
email, phone, iban, mmsi, vin, imei76 canonical validators
datetimeISO 8601 → i64 ns UTC
uuid128-bit UUID
[]string, []int, []floatArrays
[N]f32, [N]f16, [N]i8Vector types

Computed columns

Define computed properties that derive their value from other fields:

ALTER TYPE Person ADD COMPUTED full_name = CONCAT(first_name, ' ', last_name);

State-machine constraints

Types can declare state machines that constrain valid transitions:

{
  "name": "Case",
  "state_machine": {
    "field": "status",
    "transitions": [
      {"from": "open", "to": "investigating"},
      {"from": "investigating", "to": "closed"},
      {"from": "closed", "to": "reopened"}
    ]
  }
}

An invalid transition (e.g. open → closed) is rejected at write time.

Schema branches (git-branched ontology)

Schema changes can be developed on a branch without affecting production. (Schema branches fork the ontology only; to fork an entire data namespace — every type and every row, in constant time — use BRANCH ... FROM ... / POST /v1/namespaces/{name}/branch. See Branching & Namespaces for the distinction.)

# Create a schema branch
curl -X POST http://localhost:9090/schema/branches/dev-schema \
  -H "Authorization: Bearer $RELATA_BEARER_TOKEN" \
  -d '{"from": "main"}'
 
# Make changes on the branch...
# Merge when ready
 
# Delete if discarded
curl -X DELETE http://localhost:9090/schema/branches/dev-schema \
  -H "Authorization: Bearer $RELATA_BEARER_TOKEN"

Schema evolution

Add or drop properties without downtime:

curl -X PATCH http://localhost:9090/types/Person/schema \
  -H "Authorization: Bearer $RELATA_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"add": [{"name": "department", "type": "string"}]}'

Existing rows get null for new properties. Rows are schema-flexible post-creation.

See also