update_schema_incremental
Incrementally update a schema by adding fields (fields_to_add — minor version bump), removing fields (fields_to_remove — major version bump; observation data preserved, snapshot-excluded until re-added), or changing the identity rule…
Instructions
Incrementally update a schema by adding fields (fields_to_add — minor version bump), removing fields (fields_to_remove — major version bump; observation data preserved, snapshot-excluded until re-added), or changing the identity rule (canonical_name_fields — major version bump). Creates a new schema version and activates it immediately, so all new data stored after this call uses the updated schema. Optionally migrates existing raw_fragments to observations for historical data backfill.
canonical_name_fields re-keys how the type derives canonical_name / identity. Rules are ordered precedence with fallback — the first rule whose fields are all present wins, e.g. [{composite:["linkedin_url"]},"email","name"] keys on linkedin_url, else email, else name. Reach for it when same-name-different-entity collisions appear (e.g. a bulk import collapses distinct people who share a name because identity resolves on name alone). The existing reducer_config is preserved automatically, so this is the safe way to re-key without a full register_schema re-supply. Applies to NEW writes only — it does not retroactively re-key existing entities, so it will not by itself merge existing duplicates. Omit to keep the current rule; pass [] to clear it (succeeds only if the schema also declares identity_opt_out). The response echoes the resolved canonical_name_fields; call describe_entity_type first to see the current rule before replacing it.
Scope: omit user_specific to write to whichever scope your schema resolves to (your user-scoped override if you have one, else global); the response's scope (and user_id when scope is user) reports what was written. Pass user_specific: true or false only to override that. migrated_existing is true only when migrate_existing actually promoted fragments; migration_result.skipped says why any did not. If entity_type is rejected by a naming guard whose message names force: true as the remedy, retry with force: true.
On ERR_SCHEMA_SCOPE_MISMATCH (only after an explicit user_specific: false, when the type has no global registry row and no code-defined baseline) an active schema exists in a different scope than the call checked (details.guard_scope vs details.found_scope). Retry without user_specific, or with user_specific matching details.found_scope. Never call register_schema for that code — a second active row for the same entity_type risks dual-active corruption (#2374/#2378).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | Bypass the entity-type naming guards (forbidden test-artifact patterns and the plural-name guard) for this call only. Required when entity_type is rejected with a message naming "force: true" as the remedy — e.g. a name the plural guard misclassifies (like "hypothesis"). Does not affect any other validation. | |
| user_id | No | User ID for user-specific schema (required if user_specific=true) | |
| activate | No | Activate schema immediately so it applies to new data (default: true). If false, schema is registered but not active. | |
| entity_type | Yes | Entity type to update | |
| fields_to_add | No | Fields to add to schema | |
| user_specific | No | Explicit scope override. Omit this to write to whichever scope your own read of the schema resolved (global row, or your user-scoped override if you have one) — the common case, and the safe default. Pass true to create or extend a user-specific override for you even if you currently resolve the global row. Pass false to extend the global row even if you have a user-scoped override: the new global version is built from the current global schema, never from your override; if the type has no global registry row and no code-defined baseline (but has your user-scoped schema), the call returns ERR_SCHEMA_SCOPE_MISMATCH. The response's "scope" field reports which scope was actually written. | |
| schema_version | No | New schema version (auto-increments if not provided) | |
| fields_to_remove | No | Field names to remove from schema (triggers major version bump). Observation data is preserved; fields can be restored by re-adding them later. | |
| migrate_existing | No | Migrate existing raw_fragments to observations for historical data backfill (default: false). Note: New data automatically uses updated schema after activation, migration is only for old data. The response's "migrated_existing" reflects whether anything actually promoted, and "migration_result.skipped" names any fragment groups that did not (e.g. ambiguous ownership, already promoted by a prior call) — a request with migrate_existing: true can legitimately promote zero fragments. | |
| canonical_name_fields | No | Replace the entity type's identity rule (how canonical_name / entity identity is derived). Triggers a major version bump. Each item is a single field name (string) or an all-required composite ({composite:[...]}). Rules are ORDERED PRECEDENCE WITH FALLBACK: the resolver uses the first rule whose fields are all present, not an unordered set. Example: [{"composite":["linkedin_url"]},"email","name"] keys on linkedin_url when present, else email, else name. Omit to keep the current rule. Passing [] clears the rule, but only succeeds when the schema also declares identity_opt_out; otherwise it is rejected (a schema must declare canonical_name_fields OR identity_opt_out). The existing reducer_config is preserved automatically — this is the safe way to re-key a type without reconstructing it. Applies to NEW writes only; it does NOT retroactively re-key existing entities (they keep their stored canonical_name until re-derived), so re-keying will not by itself merge existing duplicates. To see the current rule before replacing it, call describe_entity_type first; the update response also echoes the resolved canonical_name_fields. |