[yeongseon]

Summary

OpenAPI 3.0 output for routes whose metadata comes from @validate_http was invalid and nothing reported it. The standard 422 response lists loc items as type: [string, integer], a 3.1-only construct; conversion left it alone, and the 3.0 audit only looked at components.schemas.

Changes

• _convert_schema_to_3_0 rewrites a type array without null to an anyOf of single-type schemas (a one-element array becomes a plain type). Sibling keywords stay on the schema, an existing anyOf moves the union into allOf, and a multi-type array beside a discriminator is left unchanged because adding a combinator would activate it. Schemas under not are converted as well.
• Each generated branch stays valid under 3.0: an array branch gets an empty items, a nullable union carries nullable: true on its first branch (this also fixes type: [string, integer, null], which rejected null on main), and a $ref beside a rewritten type array moves into allOf because 3.0 ignores the siblings of a reference.
• A schema that accepts only null (type: "null", type: ["null"], or a union of null members alone) converts to enum: [null] with nullable: true. A type-less nullable schema would accept every value, and a not over it would reject every value. A sibling enum or const is intersected with it.
• The residual 3.0 audit now also covers inline operation schemas under paths (including response header schemas) and the values of $defs, and each finding names the construct and, for inline schemas, the operation and location.
• Non-strict audit findings are reported as structured version-downgrade-drop warnings, so --fail-on-warnings can gate on them. Strict mode still raises OpenAPISpecConfigError.
• Conversion and audit share one traversal of inline schema positions (_operation_schema_slots), which keeps the visiting order of the previous code and now includes response headers.
• DESIGN.md and docs/configuration.md describe the new behavior.

Validation

Run locally on 52f8f5d:

• make check-all: exit 0 (1852 passed, 30 skipped). The skipped tests need the optional azure-functions-validation package, which the Hatch environment does not install; they pass with azure-functions-validation 0.16.0 in a separate environment. Coverage is 96.03% (gate: 95%) and every line and branch this PR adds to the conversion module is covered.
• The reproduction from fix(spec): make OpenAPI 3.0 output valid for @validate_http bridge routes #858 raises OpenAPIValidationError on origin/main and validates on this branch, with and without hoist_flat_schemas=True and under strict=True.
• A differential check with realistic @validate_http models (Optional, Union, Literal, constraints, Enum, dates, collections, nested models) in four input shapes: all 8 OpenAPI 3.0 documents were invalid on origin/main, and all 16 documents (3.0 and 3.1) are valid here, without warnings.
• A differential check of the null-only conversion compares each original schema with its 3.0 form through the reference validators (OAS31Validator and OAS30Validator): 1440 combinations of null-only forms, sibling keywords and nesting contexts, including not and $ref. The only differences involve schemas that contradict themselves and sit directly in a union, which the existing nullable collapse already treated as plain null.
• Eleven mutation checks: each fix, reverted alone, makes the new tests fail. The conversion tests also pass on Python 3.14, and mkdocs build --strict exits 0.
• GitHub CI on 52f8f5d: all check runs completed with no failures, including the required Analyze, bandit, ci-required, PR title and semgrep contexts.
• Review: GitHub's automated review of the first head raised seven findings. Six are fixed and their threads resolved; the seventh (the nullable-union merge dropping an allOf) is tracked in fix(spec): keep the surrounding schema's keys when 3.0 conversion inlines a nullable reference #870 and its thread is left open for you. Independent AI reviews (advisory) of the follow-up commits ended with an approval of 52f8f5d without blocking issues; DESIGN.md is policy-bearing, so a maintainer review of the final head is still needed.

Compatibility

• No public API or WarningCode change.
• OpenAPI 3.0 documents now contain anyOf where a non-null type array was emitted before; those documents were invalid.
• A schema whose whole type is null now accepts only null in 3.0 output; it used to become a type-less nullable schema that accepted any value. Literal[None] already used this form.
• strict=True now audits inline operation schemas as well, so a residual 3.1-only construct there raises instead of passing silently.
• Response header schemas are converted for every OpenAPI version, so 3.1 and 3.2 documents now get the same legacy nullable and example rewrites there as for other schemas.
• The non-strict log line changes its prefix from OpenAPI 3.0 compatibility: to OpenAPI spec validation:, and its text now names the construct.
• Keywords that OpenAPI 3.0 does not define at all (for example propertyNames, which Pydantic emits for dict[Literal[...], V]) are not handled here; that is tracked in fix(spec): report JSON Schema keywords that OpenAPI 3.0 does not define #867. Overlapping keywords that lose a constraint when folded for 3.0 are tracked in fix(spec): keep the stricter constraint when 3.0 conversion folds overlapping keywords #868, and the nullable-union merge defects in fix(spec): keep the surrounding schema's keys when 3.0 conversion inlines a nullable reference #870.

Related Issues

Closes #858

[Copilot]

🟡 Changes recommended

Type-union and nullability conversions can silently change schema semantics or produce invalid OpenAPI 3.0 documents, while response headers bypass conversion and auditing.

7 open issues

• Add items to generated array type branches · New
• Preserve null acceptance in generated type branches · New
• Preserve type restrictions alongside sibling references · New
• Preserve constraints when collapsing nullable combinators · New
• Preserve null-only predicates under not · New
• Traverse response header schemas during conversion · New
• Allow singleton type arrays through discriminator guard · New

What changed in this PR

This PR addresses #858 by improving OpenAPI 3.0 conversion for validation-producer schemas, including the standard 422 response, and making residual incompatibilities visible through structured warnings.

Changes:

• Converts non-null type arrays and schemas nested under not.
• Shares inline-schema traversal between conversion and auditing, with structured warnings and strict-mode errors.
• Adds conversion and bridge regression tests and documents the behavior and limits.

File	Description
tests/​test_spec_conversion_characterization.py	Adds conversion, audit, warning, and traversal coverage.
tests/​test_bridge_endpoint.py	Validates converted 422 envelopes with and without hoisting.
src/​azure_functions_openapi/​spec.py	Integrates inline auditing and structured compatibility warnings.
src/​azure_functions_openapi/​_schema_version_conversion.py	Implements type-array conversion and shared schema traversal.
docs/​configuration.md	Explains conversion behavior and diagnostic limits.
DESIGN.md	Updates the conversion and compatibility-audit design.

_{Review effort: Balanced}