Inspector, Schemas

Neotoma is schema-agnostic at write time but schema-aware at read time. The Schemas section of Inspector is where operators see what types have actually been registered, what fields each one carries, which fields define identity, and how that schema has evolved.

Schema list

The list at /schemas shows every registered entity_type with its current schema version, field count, identity rule, and how many entities of that type currently exist. The same numbers back the histogram on the dashboard, but here you can sort by churn, last write, or observation cardinality.

Schema detail, fields & identity

Click a type to drill into its schema. The detail view shows each field's name, inferred JSON type, whether it's part of the identity rule, when it was first observed, and the example values that produced its inferred type. The identity rule itself,schema_rule, canonical_name, or turn_key, is highlighted because it determines how deduplication works at write time.

Schema evolution

Schemas evolve via update_schema_incremental. Adding fields bumps the minor version; removing fields bumps the major version (and removes them from snapshots while preserving the underlying observations). Inspector shows the version history per type with a diff between adjacent versions, so operators can see when a field was introduced, deprecated, or restored.

Identity rules

Three identity bases are exposed:

• schema_rule, a tuple of fields uniquely identifies the entity (e.g. (amount, merchant, billing_period) for transaction).
• canonical_name, a single human-readable name uniquely identifies the row (common for contact, company, place).
• turn_key, used for chat bookkeeping: conversation_message rows resolve per-turn so multiple observations from the same turn collapse to one entity.

Heuristic-name resolution is also surfaced as a fallback identity basis for entities that didn't match a strict rule; the entity list filter for identity_basis uses the same enum.

Suggested fields

When a write introduces a previously-unseen field, the schema registry records it at low coverage. Inspector flags low-coverage fields so operators can decide to: promote them (formalise into the schema), prune them (remove via fields_to_remove), or leave them as ad-hoc metadata. See REST API for the schema mutation endpoints.