Skip to content

fix(invoke5): warn on unknown v5 fields without breaking parsing#267

Merged
lstein merged 3 commits into
masterfrom
lstein/fix/invoke5-extra-warning
May 22, 2026
Merged

fix(invoke5): warn on unknown v5 fields without breaking parsing#267
lstein merged 3 commits into
masterfrom
lstein/fix/invoke5-extra-warning

Conversation

@lstein
Copy link
Copy Markdown
Owner

@lstein lstein commented May 22, 2026

Why this exists

`GenerationMetadata5` carries `extra="allow"` intentionally — InvokeAI's v5 metadata schema is actively extended between releases, and silently dropping a new upstream field is preferable to refusing to parse the image. The trade-off has been zero visibility into schema drift: new fields slipped through entirely unnoticed.

What lands

A `model_validator(mode="after")` hook on `GenerationMetadata5` walks `self.pydantic_extra` (Pydantic v2's storage for `extra="allow"`'d fields) and logs each unknown field name once per process via a module-level `_warned_extra_fields` set. Subsequent images carrying the same field are silent — the goal is "did anything new show up?", not per-image instrumentation, so log volume stays proportional to the number of distinct schema additions seen.

Sample log output (single warning per field, lifetime of the process):

```
WARNING invoke5metadata: InvokeAI v5 metadata contains field(s) not declared
in GenerationMetadata5: new_field_x, new_field_y. Parsing succeeded
via extra='allow'; add to the schema if useful in the drawer or
recall payload.
```

Behavior preserved

  • Parsing still succeeds for any v5 payload regardless of unknown fields.
  • The discriminated union, the formatter, and `to_recall_payload` are untouched.
  • `extra="allow"` stays — this PR is observability, not enforcement.

Test plan

  • `ruff check` — clean
  • `pytest tests/backend/test_invoke_metadata.py` — 48 passed (4 new)
  • `pytest tests/backend` — 260 passed (was 256; the 4 added tests are the only diff)
  • Manual: re-index an album of recent InvokeAI v5 images and watch the log for any `InvokeAI v5 metadata contains field(s)` warnings — likely surfaces fields worth adding to the schema if any have been added upstream since the last update.

Four new tests cover the contract:

Scenario Asserted
Unknown fields in a payload warning fires, message lists them
Only known fields no warning
Same field seen twice second parse is silent
New field after a known one warning fires for the new one only

The fixture clears `_warned_extra_fields` around each test so test order doesn't influence what counts as first-seen.

Net +119 lines (38 in the schema file for the validator + module-level comment, 81 for the four tests).

🤖 Generated with Claude Code

lstein and others added 3 commits May 21, 2026 21:47
``GenerationMetadata5`` carries ``extra="allow"`` intentionally:
InvokeAI's v5 metadata schema is actively extended between releases,
and silently dropping a new upstream field is preferable to refusing
to parse the image. The trade-off is reduced visibility into schema
drift — the previous behavior was completely silent, so new fields
slipped through unnoticed.

Adds a ``model_validator(mode="after")`` hook on ``GenerationMetadata5``
that walks ``self.__pydantic_extra__`` (Pydantic's storage for
``extra="allow"``'d fields) and logs each new field name once per
process via a module-level ``_warned_extra_fields`` set. Subsequent
images carrying the same field are silent — the goal is "did anything
new show up?", not per-image instrumentation, so log volume stays
proportional to the number of distinct schema additions seen.

Behavior preserved end-to-end: parsing still succeeds for any v5
payload regardless of unknown fields; the warning is purely
observability.

Four new tests cover:
* Unknown fields trigger a warning (and known ones don't).
* Same-named fields seen twice only warn once.
* New fields seen after a known one fire a fresh warning that
  doesn't re-mention the already-known ones.
* Multiple unknown fields in one payload coalesce into one warning
  with all names listed.

Per-test fixture clears ``_warned_extra_fields`` so test order
doesn't influence what counts as first-seen.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@lstein lstein merged commit 99605bd into master May 22, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant