Disallow null optional GenAI JSON fields by danielpolimac · Pull Request #454 · open-telemetry/semantic-conventions-genai

danielpolimac · 2026-08-16T05:13:30Z

Motivation

Generated GenAI JSON schemas currently accept both a missing optional field and an explicit null. Consumers cannot distinguish omission from an explicit null value.

Changes

Keep optional fields optional while making their declared JSON type non-nullable.
Regenerate the input/output message, tool-definition, retrieval-document, and memory-record schemas.
Add a bugfix changelog fragment.

Validation

make generate-all
make check-policies
Verified an omitted tool-call id is accepted.
Verified an explicit null tool-call id is rejected.

Fixes #53

opentelemetry-pr-dashboard · 2026-08-16T05:14:17Z

Pull request dashboard status

Waiting on the author · refreshed 2026-09-17 08:01 UTC

Respond to 2 review items (e.g. link a commit, explain why not, ask a follow-up):

Inline threads: 1, 2

Status above doesn't look right?

Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
Should this be with reviewers? Comment /dashboard route:reviewers to route it to them.
Anything wrong — including the routing? Report it with what you expected; it helps us improve the dashboard.

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates the GenAI JSON schemas (and the non-normative Pydantic models used to generate them) to disallow null values for fields that are intended to be optional (omittable).

Changes:

Removed anyOf: [{type: ...}, {type: null}] unions from multiple GenAI JSON schema properties and replaced them with non-null type declarations.
Updated non-normative Pydantic models to use non-optional types (e.g., str instead of Optional[str]) for the same fields.
Added a changelog entry describing the behavior change.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
model/gen-ai/gen-ai-tool-definitions.json	Removes nullable unions for `description` / `parameters` in tool definitions.
model/gen-ai/gen-ai-retrieval-documents.json	Removes nullable unions for retrieval doc `id` and `score`.
model/gen-ai/gen-ai-output-messages.json	Removes nullable unions across multiple message-part fields (e.g., `mime_type`, ids, names).
model/gen-ai/gen-ai-memory-records.json	Removes nullable unions for memory record `id` / `metadata` / `score`.
model/gen-ai/gen-ai-input-messages.json	Removes nullable unions across multiple input message-part fields (e.g., `mime_type`, ids, names).
docs/gen-ai/non-normative/models.py	Aligns Pydantic model field types with the non-nullable schema intent.
changelog.d/+.bugfix.2.md	Documents the change in schema nullability.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

danielpolimac · 2026-08-16T05:19:40Z

                    "default": null,
                    "description": "The description of the tool. Since this attribute could be large, it's NOT RECOMMENDED to be populated by default. Instrumentations MAY provide a way to enable populating this property.",
-                    "title": "Description"
+                    "title": "Description",
+                    "type": "string"
                },
                "parameters": {
                    "anyOf": [
                        {
                            "$ref": "http://json-schema.org/draft-07/schema#"
-                        },
-                        {
-                            "type": "null"
                        }
                    ],
                    "default": null,


Addressed in 136ff7e. Optional non-nullable fields now omit the generated default: null annotation.

danielpolimac · 2026-08-16T05:19:49Z

                    "default": null,
                    "description": "A unique identifier for the document.",
-                    "title": "Id"
+                    "title": "Id",
+                    "type": "string"
                },
                "score": {
-                    "anyOf": [
-                        {
-                            "type": "number"
-                        },
-                        {
-                            "type": "null"
-                        }
-                    ],
                    "default": null,
                    "description": "The relevance score of the document.",
-                    "title": "Score"
+                    "title": "Score",
+                    "type": "number"


Addressed in 136ff7e. The generated retrieval-document fields are omittable, non-nullable, and no longer advertise a null default.

danielpolimac · 2026-08-16T05:19:59Z

+                    "title": "Id",
+                    "type": "string"
                },
                "metadata": {
-                    "anyOf": [
-                        {
-                            "additionalProperties": true,
-                            "type": "object"
-                        },
-                        {
-                            "type": "null"
-                        }
-                    ],
+                    "additionalProperties": true,
                    "default": null,
                    "description": "Provider-specific metadata associated with the memory record.",
-                    "title": "Metadata"
+                    "title": "Metadata",
+                    "type": "object"
                },
                "score": {
-                    "anyOf": [
-                        {
-                            "type": "number"
-                        },
-                        {
-                            "type": "null"
-                        }
-                    ],
                    "default": null,
                    "description": "The relevance score of the memory record when populated on search results.",
-                    "title": "Score"
+                    "title": "Score",
+                    "type": "number"


Addressed in 136ff7e. The generated memory-record fields are omittable, non-nullable, and no longer advertise a null default.

danielpolimac · 2026-08-16T05:20:10Z

    type: Literal["function"] = Field(description="The type of the tool.")
-    description: Optional[str] = Field(
+    description: str = Field(
        default=None,
        description=(
            "The description of the tool. "
            "Since this attribute could be large, it's NOT RECOMMENDED to be populated by default. "
            "Instrumentations MAY provide a way to enable populating this property."
        ),
    )
-    parameters: Optional[JsonSchemaDraft7Dict] = Field(
+    parameters: JsonSchemaDraft7Dict = Field(
        default=None,
        description=(


Addressed in 136ff7e. Added a shared omittable_field helper that preserves the runtime default while omitting default: null from the generated schema, keeping the omittable/non-nullable contract consistent.

lmolkova · 2026-08-16T23:11:38Z

 from pydantic_core import core_schema


+def omittable_field(**kwargs: Any):


Have you explored MISSING / NotRequired as suggested in #53? That is the part of the problem this helper leaves open: it changes what the schema says without changing what the models do, so the annotation is now false and the round trip is broken.

ToolCallRequestPart(type="tool_call", name="x").model_dump_json() # {"type":"tool_call","id":null,"name":"x","arguments":null} <- rejected by the new schema

MISSING (pydantic 2.13) covers serialization and deserialization together - omitted on dump, rejected on parse, and the generated schema is the one this PR wants:

from pydantic.experimental.missing_sentinel import MISSING id: str | MISSING = Field(MISSING, description="Unique identifier for the tool call.")

Addressed in de056bd. The models now use Pydantic MISSING so unavailable fields are omitted during serialization, while explicit null values remain representable where captured.

lmolkova · 2026-08-16T23:11:38Z

    type: Literal["function"] = Field(description="The type of the tool.")
-    description: Optional[str] = Field(
-        default=None,
+    description: str = omittable_field(


Too strict here. Omission of description/parameters already has a defined meaning in this convention - capture is opt-in, so absent means "not collected". A provider-reported null means something different: the tool has no description / takes no parameters. Banning null collapses the two.

It also pushes work onto every producer: SDK objects carry these as optional and serialize to null. The repo's own scenario does it - reference/scenarios/openai-agents/scenario.py:80 emits "description": t.description, which is None for a tool without a docstring.

Either keep null allowed on these two and document what it means, or state that instrumentations MUST drop null before emitting.

Addressed in de056bd. Tool descriptions and parameters are now typed as value, null, or MISSING; their descriptions state the distinct capture semantics.

lmolkova · 2026-08-16T23:11:38Z

    )
    name: str = Field(description="Name of the tool.")
-    arguments: Any = Field(default=None, description="Arguments for the tool call.")
+    arguments: Any = omittable_field(description="Arguments for the tool call.")


arguments is Any, so "arguments": null stays valid while "id": null becomes invalid - and this is the field where the distinction actually carries information (arguments not captured vs. the call genuinely had null arguments). Same for response and memory content.

The PR makes omission normative without saying what it means. Spell out, for each of these fields, what absent means and what null means, otherwise consumers still can't rely on either.

Addressed in de056bd. Arguments uses MISSING, and the model descriptions distinguish omission from captured null for arguments, tool responses, and memory content.

Disallow null optional GenAI JSON fields

faa37e0

Copilot AI lite review requested due to automatic review settings August 16, 2026 05:13

danielpolimac requested a review from a team as a code owner August 16, 2026 05:13

github-project-automation Bot added this to GenAI Semantic Conventions and Instrumentation libraries Aug 16, 2026

opentelemetry-pr-dashboard Bot mentioned this pull request Aug 16, 2026

Pull Request Dashboard #204

Open

Copilot AI reviewed Aug 16, 2026

View reviewed changes

Omit null defaults from GenAI JSON schemas

136ff7e

lmolkova reviewed Aug 16, 2026

View reviewed changes

Use missing sentinels in GenAI JSON models

de056bd

lmolkova added this to Stable GenAI Semantic Conventions Aug 28, 2026

lmolkova moved this to In Progress in Stable GenAI Semantic Conventions Aug 28, 2026

lmolkova moved this from In Progress to Todo in Stable GenAI Semantic Conventions Sep 9, 2026

Navigation Menu

Disallow null optional GenAI JSON fields - #454

Disallow null optional GenAI JSON fields#454
danielpolimac wants to merge 3 commits into
open-telemetry:mainfrom
danielpolimac:tighten-genai-json-schemas

danielpolimac commented Aug 16, 2026

Uh oh!

opentelemetry-pr-dashboard Bot commented Aug 16, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

danielpolimac Aug 16, 2026

Uh oh!

danielpolimac Aug 16, 2026

Uh oh!

danielpolimac Aug 16, 2026

Uh oh!

danielpolimac Aug 16, 2026

Uh oh!

lmolkova Aug 16, 2026

Uh oh!

danielpolimac Aug 17, 2026

Uh oh!

lmolkova Aug 16, 2026

Uh oh!

danielpolimac Aug 17, 2026

Uh oh!

lmolkova Aug 16, 2026

Uh oh!

danielpolimac Aug 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		from pydantic_core import core_schema


		def omittable_field(**kwargs: Any):

Conversation

danielpolimac commented Aug 16, 2026

Motivation

Changes

Validation

Uh oh!

opentelemetry-pr-dashboard Bot commented Aug 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Pull request dashboard status

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

opentelemetry-pr-dashboard Bot commented Aug 16, 2026 •

edited

Loading