Schema management

Schema constraints are a core invariant: malformed writes should fail at store time, not silently degrade state quality. This page covers practical schema workflows for unfamiliar users.

List and inspect schema types

# List known entity types
neotoma schemas list

# Inspect one schema
neotoma schemas get contact

Store data with schema validation

Store operations validate payloads against the target schema. If required fields are missing or have the wrong type, the write fails and no silent mutation occurs.

# Valid write
neotoma store --json='[{"entity_type":"contact","name":"Ana Rivera","email":"ana@acme.com"}]'

# Invalid write (example: wrong type for age)
neotoma store --json='[{"entity_type":"person","name":"Ana Rivera","age":"thirty"}]'

Evolve schemas incrementally

Add new fields without breaking existing workflows. For larger changes, analyze candidates first, then register updates intentionally.

# Analyze candidate fields from observed data
neotoma schemas analyze-candidates --entity-type contact

# Recommend schema updates
neotoma schemas recommendations --entity-type contact

# Register or update schema
neotoma schemas register --file ./contact_schema.json

Operational guidance

• →Prefer additive schema changes over destructive renames.
• →Use versioned changelogs for schema edits with rationale.
• →Test representative payloads before changing production schema.
• →Treat schema updates as state-model changes, not UI tweaks.

See schema constraints, data model walkthrough, and architecture.