Schemas, documents, and ontology
Define Mission forms and structured context without confusing documents with entities.
Use a schema-bound document for an adapter's processing status or a structured report. Use entity ontology for properties such as a site's type and operational lifecycle. Each representation has its own readers and lifecycle.
Mission schemas define fields, presentation, validation, data dependencies, effects, and optional workflow. Documents hold values for one schema.
Choose a representation
| Need | Representation |
|---|---|
| Object identity, placement, position, and quantity | Mission entity |
| Site type, site operational lifecycle, or entity domain fields | Entity ontology |
| Structured report, assessment, or integration status record | Schema-bound document |
| Immediate observation notification | Typed Mission event |
| Continuing high-rate observations | Typed telemetry stream |
Platform schemas and records explains generic schema and value primitives. Mission adds forms, module conventions, entity effects, and application workflows.
Define a Mission schema
FormSchema combines a primitive schema with FormLayout, data sources, validation rules, and optional workflow behavior. Layout can describe forms, cards, tables, or sections. A schema is not limited to an input wizard.
Parse with FormSchema::from_yaml and register through the Mission schemas API before creating documents. A startup registry can seed the same immutable definition. Identical content registers idempotently.
The schema identifier is a content hash. Changing fields, layout, or a title produces a new identifier. A changed definition cannot reuse (name, version). Increment the authored version and retain old definitions for existing readers.
Create and update documents
Rust document operations use the host-supplied, initialized atlas.app().documents() facade. Handle a failure to obtain that module before making a document call:
| Operation | Input | Result |
|---|---|---|
create | CreateDocumentParams | Created Document |
get | Document identifier | Optional Document |
list_by_group | Group identifier and GroupKind | Documents in the requested authorized scope |
update_fields | Document identifier and FieldUpdate values | Updated Document |
archive | Document identifier | Read-only archived Document |
get_workflow_state | Document identifier | Optional workflow state |
CreateDocumentParams includes schema_id, group_id, group_kind, title, created_by, initial fields, and optional workflow_id. GroupKind::Org and GroupKind::Team identify document ownership. They do not name the Mission Group access policy.
A supplied created_by value does not replace verification of the signed caller. Team-owned report creation checks native authority. Group-protected content follows its policy. Do not assume a team-owned record is invisible to other organization members when it has no Group policy.
Use FieldValue::Register for scalar status, Counter for additive counts, and the appropriate collection types for collaborative data. Choose merge semantics deliberately. A status update is not a live sample delivery mechanism.
Document archival makes the document read-only. Document workflow state, document lifecycle, entity lifecycle, and site operational lifecycle are separate concepts. Do not use an entity Restore action to reactivate an archived document.
Dart's native binding provides createDocument(input: CreateDocumentInput(...)), updateDocumentFields(docId: ..., updates: ...), and getDocument(id: ...). Read field values separately with getDocumentFields(docId: ...).
Entity ontology
A canonical ontology definition declares field paths, value types, references, and merge behavior. Registering a definition grants no right to edit an entity. The write still checks the entity's ownership and policy.
When declaring nested fields, declare each map namespace before its children. Use typed AtlasValue values for registers, sets, and lists. Keep reference targets explicit so an entity reference cannot be mistaken for an account or another primitive.
Cache Management reads specific module keys, including site_type, lifecycle, and team_id. Arbitrary custom field names do not make an entity appear in that module.
Validation and effects
Validate the schema definition at registration, field values during editing, and cross-field or workflow rules at submission. The native mutation boundary checks authorization again. A UI preflight does not authorize an effect.
Use effects only for declared Mission operations under the caller's authority. A data subscription or schema effect does not supply a physical actuator driver or permission for autonomous action.