feat(schema): report the schema fields the load endpoint does not apply
Why
#9814 made POST /api/schema/load validate against a generated user-facing write contract, and — after review reversed that half of the design — set extra="ignore" so a field the user may not set is dropped rather than rejected. That kept the read-back, edit, re-load round trip working, but it was too permissive in one direction: any extra key was accepted and the author was told nothing, so a misspelled key produced a schema quietly different from the one they wrote. ADR 0010 flagged this as the follow-up to revisit.
What changed
Extra keys are now classified rather than uniformly dropped:
- a name the contract knows at that location but the user may not set → warning, value still dropped;
- any other name → error, since the only ways to produce one are a typo and a field that no longer exists.
$ infrahubctl validate schema models/base/dcim.yml # with `inherited: true` added
nodes[0].attributes[0].inherited: Read-only field, the submitted value is ignored (received: True)
Schema is valid !!
$ infrahubctl validate schema typo.yml # `optionl: true`
Schema not valid, found 1 error(s)
nodes[0].attributes[0].optionl: Unknown field, it is not part of the schema (received: True)
POST /api/schema/load and /check return the warnings on the response, one per distinct field, naming every kind and element that carried it:
'inherited' is a read-only field, the submitted value is ignored [InfraDevice.name, InfraDevice.interfaces]
The published request schema is unchanged. The endpoint still validates through InfrahubSchemaWrite alone — no read-only field is advertised as settable, and schema/openapi.json is byte-identical after regeneration. That was the design constraint: keep the load contract clean and put the feedback in a separate layer.
Implementation notes
A generated table, not a third model family. SdkSchemaGenerator._read_only_fields emits python_sdk/infrahub_sdk/schema/generated/contract.py (17 entries) from two diffs:
- the read variant of a class against its write variant —
inherited,used_by,hierarchy,hash, the derivedkind; - the internal pydantic counterpart of a value model against its generated write model.
The second diff is the one that isn't obvious. The parameters, choice, computed-attribute and extension models are declared in the generator rather than derived from internal.py, so they omit the id/state bookkeeping every internal schema model carries, and each computed-attribute variant omits its siblings' fields. All of those names appear in a full SchemaRoot.model_dump() — which integration tests submit — so classifying them as unknown would have broken the round trip. Deriving from the internal models rather than hardcoding also means a new field on an internal parameters model is tolerated automatically instead of becoming a spurious error.
Root-level keys that GET /api/schema adds over the write root (main, profiles, templates, namespaces) are listed explicitly in the generator and pinned against SchemaReadAPI by a test, so a raw response body resubmitted warns rather than fails.
Applying the table needs to know which model governs each place in the payload. _collect_extra_fields (SDK) walks the raw payload alongside the validated write document: the document resolves the model at every location, including which member of a discriminated union an attribute matched, so raw keys are compared against the fields that location actually accepts. Alternatives considered and rejected — a generated extra="allow" model family, and a mode="before" hook writing into the pydantic validation context — are recorded in ADR 0010.
One consequence: extra fields surface only once the payload is otherwise valid. A payload rejected for another reason names them on the next run.
Warning transport. SchemaLoadAPI's validator becomes mode="wrap" so the warnings, which are only visible on the raw payload, can be set on the instance the handler returns and merged into the response next to gather_warnings(). They ride the existing deprecation warning type rather than a new enum member, so an SDK released before this change can still parse a load response; a dedicated type has to wait until a tolerant SDK is the supported floor.
Behaviour changes to be aware of
Two shapes that previously loaded now fail. Both were silently dropped before, so the loaded schema differed from the authored one:
- a misspelled field name;
- attribute
parametersbelonging to a different attributekind— e.g.start_rangeon aNumberattribute. (Dropdown+regexwas already rejected pre-#9814, so that one is unchanged.)
This means a repository whose committed schema carries either one stops importing until corrected. Covered by the changed changelog fragment and the deprecation guide.
Also fixed: load_schema returned early when the submitted schema matched the one already loaded and dropped warnings entirely, so a deprecation warning went unreported on every load after the first.
Testing
- Backend unit suite: 2177 passed.
test_schema_load_contract.pyreworked — the five*-toleratedcases split into accepted-with-warning and rejected; new tests for warning aggregation, the root-key pin, and unknown-field rejection.test_generated_visibility.pygains an invariant test that the generated table is exactly the read/write delta per family. - Swept every schema file in the repo (
models/**,backend/tests/**,development/**— 28 files) through the new validator: no unknown-field errors anywhere; onlymodels/base/dcim.ymlwith a deliberately-addedinheritedproduces a warning. invoke lint(ruff/ty/mypy) andinvoke docs.lintclean.schema/openapi.jsonbyte-identical afterinvoke schema.generate-jsonschema.- Functional tests in
test_load_schema.pyare updated but not run locally — they need the testcontainers stack, so CI is the first execution.
Submodule
python_sdk is bumped to the head of the companion PR, opsmill/infrahub-sdk-python#1223, whose parent is the commit release-1.11 previously pinned — so the pointer moves strictly forward. This needs re-pointing at the merged commit once #1223 lands, as was done for #9814.
Note #1223 targets infrahub-develop while this PR targets release-1.11, per the requested targets.
Docs
dev/adr/0010-generated-user-facing-schema-contract.md— decision updated, the anticipated negative consequence resolved, and the two rejected alternatives recorded.dev/knowledge/backend/schema-definitions.md— new section on how the warning/error split is derived and applied.docs/docs/release-notes/deprecation-guides/schema-load-write-contract.mdx— the "extra fields are dropped" section was now wrong; rewritten with both categories and the remediation steps.
🤖 Generated with Claude Code