fix(jsonschema): align nullability with JSON Schema 2020-12

[asoorm]

Stacked on top of #1513. Review #1513 first; this PR's diff is only the nullability change.

Problem

The generator emits the OpenAPI 3.0 keyword "nullable": true for nullable fields.

Standard JSON Schema 2020-12 validators (e.g. santhosh-tekuri/jsonschema, used by Cosmo's router) silently ignore unknown keywords, so a payload containing null for an otherwise-valid optional field is rejected at the schema-validation boundary.

LLMs that legitimately emit null for absent optional fields - OpenAI's gpt-4o does this routinely in tool-call arguments - then have their output rejected before reaching the resolver.

Same failure pattern as #1513 (ENG-9631) but different root cause.

Discovered while building the provider-compatibility evidence for that PR.

Fix

Switch nullability to the JSON Schema 2020-12 form:

Schema kind	Before (OpenAPI 3.0)	After (JSON Schema 2020-12)
typed	{"type": "string", "nullable": true}	{"type": ["string", "null"]}
enum	{"type": "string", "enum": [...], "nullable": true}	{"type": ["string", "null"], "enum": [..., null]}
$ref	{"$ref": "...", "nullable": true}	{"anyOf": [{"$ref": "..."}, {"type": "null"}]}

The "nullable" key is no longer emitted. The internal Nullable field is retained for construction-time logic; only the JSON serialization changes. Definition bodies under $defs are now marked non-nullable explicitly so the def carries the single canonical type and per-use-site nullability is applied via the surrounding ref.

Tests

• New nullable_2020_12_test.go: validates explicit-null payloads against the generated schema for nullable scalar, enum, and recursive ref fields (red before, green after).
• Existing golden-JSON tests across schema_test.go and variables_schema_test.go updated to assert the 2020-12 shape.

All package tests pass; gofmt clean; go vet clean.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 054612f9-f755-4673-af9a-e12809face3e

📥 Commits

Reviewing files that changed from the base of the PR and between d0ad76b and 6bc6bfc.

📒 Files selected for processing (5)

• v2/pkg/engine/jsonschema/nullable_2020_12_test.go
• v2/pkg/engine/jsonschema/schema.go
• v2/pkg/engine/jsonschema/schema_test.go
• v2/pkg/engine/jsonschema/variables_schema.go
• v2/pkg/engine/jsonschema/variables_schema_test.go

🚧 Files skipped from review as they are similar to previous changes (5)

• v2/pkg/engine/jsonschema/variables_schema.go
• v2/pkg/engine/jsonschema/nullable_2020_12_test.go
• v2/pkg/engine/jsonschema/schema.go
• v2/pkg/engine/jsonschema/schema_test.go
• v2/pkg/engine/jsonschema/variables_schema_test.go

---

📝 Walkthrough

Walkthrough

This PR migrates JSON Schema nullability representation from OpenAPI-style "nullable": true to JSON Schema 2020-12 conventions. The core MarshalJSON method in schema.go now emits type unions (["string", "null"]), appends null to enums, and uses anyOf constructs for refs. All dependent tests in schema_test.go and variables_schema_test.go are updated accordingly, with a new compliance test validating the generated output.

Changes

JSON Schema 2020-12 Nullability Format

Layer / File(s)	Summary
Serialization contract: Nullable field and MarshalJSON update v2/pkg/engine/jsonschema/schema.go	The Nullable field becomes internal-only (json:"-"). MarshalJSON now emits type unions ["<type>", "null"] for nullable typed fields, appends null to nullable enums, and serializes nullable refs via anyOf containing the ref and a {"type":"null"} branch.
Schema generation test expectations v2/pkg/engine/jsonschema/schema_test.go	Test assertions updated to expect nullability via type arrays/unions, null enum entries, and anyOf constructs; validates object schemas, enum schemas, required fields, numeric constraints, and complex nested structures.
Recursive input type definition handling v2/pkg/engine/jsonschema/variables_schema.go	During recursive ensureDef finalization, the processed input-object body is stored with Nullable = false, ensuring definitions themselves remain non-nullable.
Variables schema test expectations v2/pkg/engine/jsonschema/variables_schema_test.go	All test assertions updated to expect nullability via type arrays, enum null values, and anyOf constructs across simple/nested input objects, scalar arguments, deeply nested types, recursive types, and root schema cases.
JSON Schema 2020-12 compliance test v2/pkg/engine/jsonschema/nullable_2020_12_test.go	New test validates that generated schemas compile with a strict JSON Schema 2020-12 validator and correctly accept explicit null values for nullable scalars, enums, and recursive refs.

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• wundergraph/graphql-go-tools#1513: Touches v2/pkg/engine/jsonschema/variables_schema.go recursive input schema generation and relates to $ref/$defs recursive-type emission changes.

🚥 Pre-merge checks | ✅ 4

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'fix(jsonschema): align nullability with JSON Schema 2020-12' clearly and concisely summarizes the main change: updating JSON Schema nullability encoding from OpenAPI 3.0 style to JSON Schema 2020-12 standard.
Description check	✅ Passed	The description provides relevant context explaining the problem (OpenAPI nullable ignored by standard validators), the fix (JSON Schema 2020-12 encoding), example transformations, and testing approach—all directly related to the changeset.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ahmet/jsonschema-2020-12-nullable

Warning

Review ran into problems

🔥 Problems

Stopped waiting for pipeline failures after 30000ms. One of your pipelines takes longer than our 30000ms fetch window to run, so review may not consider pipeline-failure results for inline comments if any failures occurred after the fetch window. Increase the timeout if you want to wait longer or run a @coderabbit review after the pipeline has finished.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review and subscribe this PR to future pushes, or @claude review once for a one-time review.

_{Tip: disable this comment in your organization's Code Review settings.}