Mission SDKSchemas, documents, and ontology

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

NeedRepresentation
Object identity, placement, position, and quantityMission entity
Site type, site operational lifecycle, or entity domain fieldsEntity ontology
Structured report, assessment, or integration status recordSchema-bound document
Immediate observation notificationTyped Mission event
Continuing high-rate observationsTyped 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:

OperationInputResult
createCreateDocumentParamsCreated Document
getDocument identifierOptional Document
list_by_groupGroup identifier and GroupKindDocuments in the requested authorized scope
update_fieldsDocument identifier and FieldUpdate valuesUpdated Document
archiveDocument identifierRead-only archived Document
get_workflow_stateDocument identifierOptional 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.