Schema constraints are a core invariant: malformed writes should fail at store time, not silently degrade state quality. This page covers the practical CLI workflows.
You don't have to define a schema first
Neotoma infers schemas from your first write. Store any entity with a descriptive entity_type and whatever fields the data implies — Neotoma registers a schema from that observation, and every subsequent field addition bumps a minor version (1.0.0 → 1.1.0) automatically. Fields the active schema doesn't recognize land in a raw_fragments layer so nothing is silently dropped, and breaking changes (removing or retyping a field) require an explicit major version bump (1.x → 2.0) that keeps every historical observation readable.
If you're evaluating Neotoma and don't want to commit, the Test safely guide walks through how to install in shadow mode, let your agent populate schemas from your real data, and walk away without affecting anything in your current stack.
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 unexpected types, the observation is still stored but a warning is recorded in the raw fragments layer, so no data is silently lost or misclassified.
# 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
schemas overview
,
versioning & evolution
,
schema constraints
,
Test safely
, and
architecture
.