Application schemas and records
Define application-owned data, merge semantics, references, and schema validation.
Define field types, validation rules, and merge behavior in your application's schema. Platform can store a temperature notebook, maintenance form, or inventory without imposing domain types.
Define a data contract
Give each application contract a stable name and version. SchemaRef.id names it, and SchemaRef.digest identifies its canonical definition. A primitive SchemaId is content-addressed, not a display label or application name.
Preserve the mapping and exact canonical format. The schema reference defines primitive identity and ontology versions.
Choose merge semantics deliberately
| Field behavior | Primitive | Suitable example |
|---|---|---|
| One winning scalar value | Register | Current label or last saved temperature |
| Concurrent increments accumulate | Counter | Number of completed inspections |
| Unique unordered membership | Set | Tags |
| Character-level edits merge | Text | Shared notes |
| Ordered entries | List | Checklist items |
| Named nested values | Map | Calibration details |
A conflict-free replicated data type, or CRDT, defines how concurrent operations merge. It does not decide whether a business action is valid. Concurrent decrements of a counter can violate a nonnegative business rule unless your application supplies the appropriate invariant.
Register conflict order is deterministic. It is not a guarantee that the most accurate wall clock or most recently displayed value wins. Retain observation time separately from merge ordering.
Save and resolve records
SaveResult returns entity_ref and local_commit. A Record combines an EntityRef, a SchemaRef, and an application payload. EntityRef.kind and EntityRef.id identify application-owned data. They do not supply the richer Entity primitive with Track, Geo, Asset, and Template variants.
ResolveOptions supplies the lookup bound, permitted resolution paths, and independent read authority. See storage and replication for peer visibility.
A document adds a schema-backed container with an optional workflow. Its primitive access group is an application authorization scope, not Mission enrollment. Constructing a document does not save or replicate it. The Document reference defines exact fields and limits.
Validate at the boundary
Validate required fields, kinds, bounds, reference targets, and payload sizes before accepting a write. Validate again on receipt. A declaration of a constraint does not prove every lower-level value constructor enforces it.
A record can arrive before its schema. Preserve the record's source data and show schema-pending state until the definition is available. Do not guess an interpretation or discard unknown operations merely because the current UI cannot display them.
SchemaMismatch rejects an incompatible payload. InvalidArgument rejects malformed data. Keep the unsaved input for correction. Advance schemas through explicit compatible versions rather than editing the meaning of an existing identity. Compatibility describes mixed-version handling.