Repository navigation
Emit plain types for optional fields in generated JSON Schema - #78
Merged
Merged
Conversation
An optional config field reached `blueprint schema` as
`anyOf: [{"type": "string"}, {"type": "null"}]`, which client generators
turn into a union wrapper type rather than a plain optional. Optionality
is already carried by the schema's `required` array, so the redundant
null branch and the `null` default are now dropped and the field keeps
its single-valued type.
Airflow params keep null as a legal value. A param always holds a value,
so an unset optional field is validated as an explicit null rather than
as an absent key, and stripping null there would fail every DAG that
leaves an optional field unset.
Drops the README section and the advanced-example demonstration. The emitted shape is a minor tweak that does not need documenting alongside the project's larger features.
Pins three invariants of the two rewrites: a non-None default on an optional field survives stripping, an optional field nested inside a model or list item is rewritten too, and the params form admits null as an enum member.
schnie
approved these changes
Aug 20, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
An optional config field arrived in
blueprint schemaoutput asanyOf: [{"type": "string"}, {"type": "null"}], which client generators turn into a union wrapper type instead of a plain optional — reported by a user building a non-Python client from the generated schema. Optionality is already expressed by the schema'srequiredarray, so the null branch is redundant there and is now dropped, along with thenulldefault:Airflow params are the exception and keep
{"type": ["string", "null"]}. A param always holds a value, so an unset optional field is validated as an explicit null rather than an absent key — stripping null there fails every DAG that leaves an optional field unset, withParamValidationError: None is not of type 'string'.This changes the shape of emitted JSON Schema, which is consumer-visible, so it wants a MINOR bump at release. No Python API changes.
Files to review (8, +363 / -7):
blueprint/core.py(start here)_rewrite_nullablewalker plus the two rewrites,_strip_nullableand_collapse_nullable.blueprint/builder.pytests/test_core.py,tests/test_builder.pytests/integration/suffixfield on thegreetblueprint, exercised through a real trigger.The two consumers of the same Pydantic schema, and where they now diverge:
Unchanged:
required(Pydantic already omits defaulted fields), every non-optional field, and_resolve_refsitself — the rewrite deliberately sits outside it, since that is the one function both paths share.Reviewer notes
test_params_keep_null_legal_where_published_schema_drops_itasserts the published schema says"string"while the same field's Param says["string", "null"], so the inconsistency is not later "fixed" into a trigger-time failure.SchemaPropertyField.tsxin theastrorepo) branches ontype === 'string',type === 'integer'and so on, falling through to an "Unsupported field" placeholder, and typestypeas a single string. A nullable type array in the published schema would render every optional field as unsupported. It already reads optionality fromrequired, and bare types pass through itsunwrapNullableAnyOfuntouched, so no IDE change is needed.Literal[...] | Nonekeeps a clean enum. Stripping leavesenum: ["a", "b"]; the params form appendsnull, which is required or null fails validation against its own type.$def, whose docstring-deriveddescriptionwould otherwise displace theField(description=...)on the field itself.examples/advanced/, deliberately. This changes the shape of emitted JSON rather than adding a feature a DAG author writes, so there is nothing to show in an example DAG; the integration project carries the coverage instead._strip_nullable's key merge. It is where a schema could silently lose a constraint.X | Nonewith no default (nullable but required) is the edge that already bit once —"default" in mergedguards it, covered bytest_nullable_field_without_default_stays_required.Multi-member unions were already impossible.
_is_yaml_compatiblerejects any union with more than one non-Nonemember at class-definition time, so onlyX | Nonereaches the schema and neither rewrite handles a wider union. AnanyOfwhose non-null branch has no stringtypeis left untouched rather than guessed at.Evidence
ruff check,ruff format --checkandty checkclean onblueprint/ tests/.main+ 5 added): an optional param left null triggers successfully, a typed override runs, and a wrong-typed value is rejected with a 400.StringField/NumberField/BooleanField/EnumFieldexactly like required ones. The only fallthrough issteps, which the IDE filters viaRESERVED_DAG_KEYSbefore rendering, unchanged by this PR.Important
An explicit
field: nullin YAML is still accepted byblueprint lint, because Pydantic allows it, but is no longer described by the published schema. A schema-driven editor may flag it; omitting the key is the supported spelling. Nothing in the Astro IDE validates YAML text against these schemas today, so there is no visible effect there.Two follow-ups, both out of this diff: the
examples/editor-and-cischema fixtures on the in-flight examples branch still contain the oldanyOfform, and whatever writesblueprint/generated-schemas/in a Polaris session determines when existing IDE sessions pick up the new shape.