Schemas in Neotoma are versioned, config-driven definitions that say what fields each entity type carries and how observations of those fields merge into a single deterministic snapshot. They are not primitive record types, they are the configuration that gives the primitives their shape.
Every schema is a row in the schema registry: a versioned schema_definition plus a reducer_config of declarative merge policies. Schemas evolve at runtime via additive minor versions and explicit major-version breaking changes; every version is exported as a public JSON snapshot for reference.
You don’t define schemas upfront.
Store any entity with a descriptive entity_type and whatever fields the data implies. Neotoma infers a schema from the first write, then evolves it additively as new fields appear (minor version bumps that never break existing data).
Unknown fields are preserved in a raw_fragments layer so nothing is silently dropped, and breaking changes (removed or retyped fields) require an explicit major version bump that keeps historical observations readable. See versioning & evolution for the mechanics, or Test safely to try it without touching your current setup.
- Schema registryVersioned, config-driven entity schemas, the single source of truth for what fields each entity type carries
- Merge policiesPer-field declarative rules that turn many observations into one deterministic snapshot
- Storage layersraw_text, properties, and raw_fragments, the three places extracted data can land
- Versioning & evolutionSemver, additive evolution, breaking changes, and the public schema snapshots dump
How schemas relate to the rest of Neotoma
The primitive record types (sources, observations, relationships, snapshots, …) are immutable and universal, they don't depend on any specific entity type. Schemas are what map those primitives onto domain shapes like contact, transaction, and task: they declare which fields are valid, how to coerce values, and how the reducer should merge observations into snapshots.
For runtime CLI workflows (listing, validating, registering schemas) see schema management. For the full architectural picture see the schema registry doc and the schema handling architecture.