saved-objects-style-review

# Saved Objects Style Review Use this skill when reviewing or changing Saved Object type registrations, especially code that calls `savedObjects.registerType`, edits `mappings`, or changes `modelVersions`. ## Type Registration Register Saved Object types systematically during plugin setup. We want to encourage—and, where possible, enforce—unconditional `savedObjects.registerType` calls rather than gating registration behind a configuration parameter or feature flag. If registration is conditional, our CI Saved Object check is unlikely to detect the type. The check builds the current registry by starting Kibana; when the gate is off in CI, the type is never registered and the check cannot validate its definition or subsequent updates to mappings, `modelVersions`, or schemas. That bypasses safeguards that catch invalid migrations before they reach production, where bad changes can corrupt stored data or prevent Kibana from starting. For early iteration that genuinely requires conditional registration, follow the documented WIP-type workflows in `docs/extend/key-concepts/saved-objects/validate.md` rather than ad hoc feature-flag gating. ## Mapping Mindset Saved Object mappings are search indexes, not a complete schema. Once added and released, mappings cannot be removed. Add mappings only for fields that Kibana must search, filter, sort, or aggregate on. Stored attributes do not need mappings just because they exist in the Saved Object payload. Default to `dynamic: false` for object mappings so Elasticsearch stores unmapped attributes without indexing them. Do not use `enabled: false` or `index: false`; those choices are hard to change later. ## Review Checklist - If a new field is not queried, filtered, sorted, or aggregated, do not add a mapping, `mappings_addition`, or root mapping entry for it. - If a new field is indexed, add it in both places: the latest type `mappings` and a `modelVersions` `mappings_addition`. - Do not add a `mappings_addition` for a field that already existed in the type's root mappings before the change. Root mappings represent the latest complete mapping state; model version changes describe only what changed in that version. - When adding an indexed field with a default value, pair `mappings_addition` with `data_backfill`. For a non-indexed field with a default, use only `data_backfill`. - For new searchable behavior, prefer a two-release rollout: first add/backfill the indexed field, then depend on it in business logic in the next release. - Keep `create` and `forwardCompatibility` schemas aligned with stored attributes. These schemas may include non-indexed fields even when mappings do not. ## Common Review Findings Check whether the proposed mapping already existed in the saved object root mappings (`created_at`, `created_by` etc.) before this change. Re-declaring an existing root-mapped field adds duplication and wastes resources. ## References - `docs/extend/key-concepts/saved-objects/create.md` - `docs/extend/key-concepts/saved-objects/update.md` - `packages/kbn-check-saved-objects-cli/README.md` - `docs/extend/key-concepts/saved-objects/validate.md`