feat: report the schema fields the write contract does not apply

Merged
DG
4mo ago
+456-93

What changed

The generated write models set extra="ignore", so a field the user may not set never reaches the server. That settled whether such a field has an effect, but not whether the author hears about it โ€” a misspelled key produced a schema quietly different from the one they wrote.

Every extra key in a submitted payload is now classified:

  • a name the contract knows at that location but the user may not set is dropped and reported as a warning, so a schema read back from Infrahub, edited and loaded again keeps working;
  • any other name is an error, since the only ways to produce one are a typo and a field that no longer exists.
nodes[0].attributes[0].inherited: Read-only field, the submitted value is ignored (received: True)
nodes[0].attributes[0].optionl: Unknown field, it is not part of the schema (received: True)

Implementation notes

A generated table, not a third model family. infrahub_sdk/schema/generated/contract.py holds the non-settable field names of each write class (17 entries). It is produced by the Infrahub-side generator from two diffs: the read variant of a class against its write variant, and the internal pydantic counterpart of a value model against its generated write model. The second diff matters โ€” the parameters/choice/computed-attribute/extension models are hand-declared in the generator, so they omit the id/state bookkeeping every internal schema model carries, and each computed-attribute variant omits its siblings' fields. Those names all appear in a schema dumped from Infrahub's own models, so treating them as unknown would have broken the round trip.

Applying the table needs to know which model governs each place in the payload. _collect_extra_fields 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. This is why the walk gives exact dotted paths and the owning kind/element for free, and it avoids both a second generated model family and a hand-rolled discriminator resolver.

One consequence, documented in the docstring: extra fields surface only once the payload is otherwise valid, because the validated document is what resolves the contract. A payload rejected for another reason names its extra fields on the next run.

API changes

  • SchemaValidationResult gains warnings (list[SchemaValidationWarningDetail]) and warning_messages. Each warning carries the dotted path, the bare field name, and the schema kind / element that set it.
  • client.schema.validate() returns the verdict instead of None, and raises ValueError rather than a pydantic ValidationError. ValidationError subclasses ValueError, so except ValueError callers are unaffected; a caller catching ValidationError specifically needs updating.
  • validate_schema_content_and_exit() no longer takes client โ€” it never needed a server.
  • infrahubctl validate schema no longer builds a client, so it works with no server configured. It reports warnings and errors; infrahubctl schema load / schema check report errors locally and leave warnings to the server response, which already carries them, to avoid printing each one twice.

Two shapes that previously passed and now fail

Both were silently dropped before, so the loaded schema differed from the authored one:

  1. a misspelled field name;
  2. attribute parameters belonging to a different attribute kind โ€” for example start_range on a Number attribute, which configured nothing.

Testing

  • tests/unit/test_schema_offline_validation.py restructured: read-only cases assert the exact set of warning paths, unknown-field cases assert the exact set of error paths. Covers every nesting level (root, node, generic, attribute, relationship, parameters, choices, computed_attribute, extensions.nodes[*].attributes), the value-model bookkeeping fields, the sibling-variant field, and the reporting-order consequence above.
  • Full unit suite: 1735 passed. Three pre-existing failures in test_repository_app.py / test_task_app.py (rich table width mismatches) fail identically on a clean tree.
  • invoke format and invoke lint-code (ruff, ty, mypy) clean.

Companion PR

contract.py is generated by invoke backend.generate in the Infrahub repo. The Infrahub side, which generates it and consumes the warnings on POST /api/schema/load, is opsmill/infrahub#10095.

Note this branch is based on the commit the Infrahub release-1.11 submodule currently pins, so it sits behind infrahub-develop; the changes to ctl/schema.py on develop are additive, in a different part of the file.

๐Ÿค– Generated with Claude Code