Thanks @Copilot for the review — both items addressed in a9107c4:

• anyOf constraint — {content|file_id|uri} OR stripped_reason required — good catch. With the payload fields removed from required it was indeed possible to construct a structurally empty part, which would defeat the whole "no media" vs "media stripped" distinction this PR introduces. Fixed by declaring json_schema_extra with the appropriate anyOf on the Config of each of BlobPart/FilePart/UriPart so the notebook stays the source of truth, and applying the matching shape to the three JSON schemas. Now a part must carry at least one of the payload-bearing field or stripped_reason (both is also fine, e.g. for a redactor that captured a hash but not the bytes).
• json → jsonc fence for the multimodal-inputs example — this one was actually a false-positive against the head commit: the multimodal-inputs and multimodal-output blocks under ### Multimodal inputs example / ### Multimodal output example are already fenced as ```jsonc in the file (lines 224 and 289). The new stripped-part example this PR adds (around line 275 of the diff) lives inside that already-jsonc block, so the // comments are valid in the fence. No change required.

make check-policies re-validated locally on the updated branch.

Thanks @Copilot for the second pass — good catch. The first-pass anyOf only checked key presence; since the payload fields are nullable, {..., "content": null} would still satisfy {required: ["content"]} and validate even without stripped_reason. Exactly the structurally-empty case the constraint was supposed to forbid.

Fixed in b00a96f. Each branch now also constrains the corresponding property to non-null:

"anyOf": [
    {
        "properties": {"content": {"not": {"type": "null"}}},
        "required": ["content"]
    },
    {
        "properties": {"stripped_reason": {"not": {"type": "null"}}},
        "required": ["stripped_reason"]
    }
]

So an instance must now carry either a non-null payload (content / file_id / uri) or a non-null stripped_reason (or both).

Functional check with jsonschema against the regenerated schema:

Config.json_schema_extra on each of BlobPart/FilePart/UriPart in models.ipynb updated to match, so the notebook stays the source of truth. make check-policies re-validated.

Thanks @Copilot for the third pass. Addressed in 107f1be:

1 & 2. stripped_reason description was BlobPart-centric. Same issue as PR #143 round-2 (broadening wording leaked BlobPart-specific bytes terminology onto FilePart / UriPart). Now per-part:

Each description also tailors the example reason list — e.g. size_exceeded doesn't really apply to a file_id capture, so it's been dropped from FilePart's example list.

3. Notebook code comment vs Pydantic runtime. Fair — the old comment said the model "must carry" one or the other, but Optional[...] with default=None means a Python instance with both content=None and stripped_reason=None constructs fine at the Pydantic layer; the constraint only kicks in when the schema is exported and a JSON schema validator runs on a serialized instance. Rather than add a @model_validator (the notebook is intended as documentation rather than a production validator), the comment is now explicit:

class Config:
    # JSON-schema-level constraint: serialized instances must carry either a non-null
    # `content` or a non-null `stripped_reason` (or both). The Pydantic *runtime* model
    # still allows both fields to be None; the constraint is exported via
    # `json_schema_extra` and enforced by JSON schema validators on the consumer side.
    json_schema_extra = {
        "anyOf": [
            {"properties": {"content": {"not": {"type": "null"}}}, "required": ["content"]},
            {"properties": {"stripped_reason": {"not": {"type": "null"}}}, "required": ["stripped_reason"]},
        ]
    }

Same clarification applied to FilePart and UriPart's Config blocks. Happy to add a @model_validator instead if maintainers prefer the runtime enforcement — let me know.

PR body has also been filled out against the new PR template (per @trask's request on #143). make check-policies re-validated locally.

Hi! As part of #275, this repository switched to Towncrier changelog fragments to reduce merge conflicts in CHANGELOG.md.

Please move this PR's changelog entry out of CHANGELOG.md and into this Towncrier fragment:

Create changelog.d/144.enhancement.md containing the change log entry, e.g.:

Make `BlobPart.content` optional and add a free-form `stripped_reason` marker on the `gen_ai.input.messages` `BlobPart`, so an instrumentation can record that it observed an inline blob but intentionally did not capture the payload bytes (size cap exceeded, modality not allowed, redactor failure, etc.) while preserving the original part type and modality. A schema-level `anyOf` requires either a non-null `content` or a non-null `stripped_reason`. Scoped to input-messages `BlobPart`; if accepted, follow-up PRs replicate the change to `FilePart`/`UriPart` and to the output-messages and system-instructions schemas.

After adding the fragment, please remove this PR's direct edit to CHANGELOG.md. Towncrier will add the PR link from the fragment filename when release notes are generated.

Thanks!

@trask done — the changelog entry now lives in changelog.d/144.enhancement.md and the direct CHANGELOG.md edit is removed (commit 6244073).

The rebase onto current main also ports the PR to the #226 notebook-to-Python conversion. Since docs/gen-ai/non-normative/models.py now generates all message schemas from one shared part union, the input-only scoping is expressed via input-messages variants of BlobPart/ChatMessage (a small namespace class in models.py that reuses the shared class names, so the generated $defs keys and the wire format stay identical across schemas). gen-ai-input-messages.json is regenerated via make generate-json-schemas; the resulting JSON diff is the same shape that was previously reviewed — top-level anyOf, nullable content, and the stripped_reason property, with no changes to the output-messages or system-instructions schemas.

If maintainers would rather not carry the input-only variant classes in models.py, the alternative is to apply the change to the shared BlobPart (which widens scope back to all three schemas) — happy to go either way.

Thanks @lmolkova — I think we agree on most of this, and the pieces you list map onto the current PR stack:

• A documented capture-size limit option — agreed this is needed and complementary. It is instrumentation configuration rather than schema shape, so I see it as a docs follow-up that this PR's schema change enables (the marker is what an instrumentation sets when that limit fires).
• Size on each affected part — that is exactly gen-ai: add optional byte_size to multimodal content parts #143 (byte_size on BlobPart/FilePart/UriPart). Extending it to TextPart is a one-line addition there; happy to fold it in if you want it.
• Trim-to-size for text — agreed, trimming works for text because a prefix is still useful. It does not transfer to binary parts: a truncated blob is not decodable, so for BlobPart the real choice is captured vs not captured. That is why this PR makes content omittable rather than truncatable.
• content_dropped: true mimicking OTLP dropped attributes vs a reason string — I am open to converging on the boolean form if that is the more OTel-consistent shape; the core of this PR is "content optional + explicit stripped marker", and the marker's type is a one-line change. Two things made me start with a free-form string: (a) it is deliberately non-enumerated, so there is no reason taxonomy for the spec to maintain (the failure-mode concern you mention with recording "why"); and (b) in practice operators do need to distinguish "size cap fired" from "redactor errored" without correlating collector logs — the string costs nothing when unused.

On "presence of non-0 size would be an indication on its own": byte_size alone cannot carry that signal, because it is optional and not always cheaply observable (e.g. a pre-existing remote URI), and absence of content alone is ambiguous against providers that legitimately reference blobs without inline bytes. An explicit marker keeps "instrumentation stripped this" distinguishable from "this was never inline".

If the WG preference lands on size-limit-config + byte_size everywhere + a boolean marker, I can reshape this PR to that in one pass — the schema mechanics (optional content + anyOf constraint) stay the same either way.

Pull request dashboard status

• Waiting on: Reviewers
• Next step: Review the latest changes.