Schemas#

An open ontology lets a project record knowledge before its model is complete. Some workflows still need an exact definition of what is currently correct. Existing data and current correctness rules remain independent concerns. Rich Hickey describes the mistake of joining independent concerns as complecting in Simple Made Easy.

Correctness is a selected view#

Schemas use JSON Schema Draft-07. A schema evaluates the complete document of an entity. It does not assign a permanent class to that entity. One entity can match more than one schema, and different workflows can select different definitions of correctness.

A device-reading schema is an ordinary entity under definitions/schemas/, and it can be written as DUST:

type       object
required   [temperature]
properties {temperature {type number}}

This schema requires one numeric temperature field. A later edit can add, remove, or change those rules without rewriting stored entities. Existing entities can begin or stop matching when their data or the schema changes. The format keyword is accepted but not checked.

Validation always names a schema. This query clause keeps only entities whose current document validates against the schema reading, the document definitions/schemas/reading:

where [[schema reading ?e]]

The document it checks is the entity's authored fields, nothing else: a data entity carries no stardust/ member. The stardust.entity.validate command and the generated SDK's Validate check a raw value against a named schema instead.

Schemas are knowledge#

A schema is durable project knowledge rather than an opaque validation file. It is an entity, so each accepted change becomes facts with transaction context, like any other entity. Reification explains how those transactions become queryable. Validation itself uses the current schema against the current document.

Every schema under definitions/schemas/ compiles together as one generation. A schema can reference another stored schema by relative path, with either suffix, as in ../common/address.dust#/definitions/street. It can also reference an $id declared by another stored schema, or a local fragment. Stardust rejects references to network addresses that no schema provides. It also rejects unresolved references, duplicate $id values, and reference cycles that never reach a rule. Validation therefore never depends on remote content, latency, or availability.

A write that creates, edits, moves, or deletes a schema recompiles the whole generation first. The write is rejected when the result is not valid Draft-07 or when it would break another schema's references.

An optional write boundary#

Open patches remain available for data that does not need a selected schema. A schema-checked write opts into stricter preparation. Each schema has a live data directory at data/schemas/<path>/ whose entities/ view lists only the conforming data entities, by id. Writing its patch.json or patch.dust stages the same id-keyed merge patch as the top-level patch. A live mutation whose query binds a target with a schema clause applies the same check to that target.

Stardust renders every changed entity from the staged facts and validates each complete document. If any candidate is invalid, no fact commits. A deleted entity has no document to validate. Stardust does not add default values. The document contains only what was written.

Scope of a schema#

A schema change does not rewrite or validate existing entities. Deleting a schema removes its data directory and its availability to queries, and succeeds only if no remaining schema references it. Its earlier documents remain in entity history.

A schema governs only reads and writes that select it. Open patches can still create data outside its rules, so a schema does not guarantee full-store compliance. Projects use schema-checked boundaries for workflows that require strict agreement. Other knowledge remains free to arrive before its definition of correctness exists.

Schema matching identifies entities that satisfy one selected definition.