Make launch stage the single preview source of truth in schema codegen#5611
Merged
Conversation
Two follow-ups from #5443: Introduce an annotation.LaunchStage type with the known stages as named constants and a single source-of-truth tag map. The annotation parser now validates every launch_stage read from cli.json and fails codegen on an unrecognized stage, so a stage added upstream can't slip through unmapped. Drop the x-databricks-preview remnant. The published schema now carries x-databricks-launch-stage, emitted only for private-preview fields (where it sets doNotSuggest and the Python codegen reads it to mark fields experimental). Generated pydabs models are byte-identical; only the schema key and value change. Co-authored-by: Isaac
janniklasrose
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
janniklasrose
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
Collaborator
Integration test reportCommit: d4e7e90
22 interesting tests: 15 SKIP, 7 RECOVERED
Top 25 slowest tests (at least 2 minutes):
|
pietern
approved these changes
Jun 16, 2026
…llow-up # Conflicts: # bundle/schema/jsonschema.json # bundle/schema/jsonschema_for_docs.json
Per review of #5611: the launch stage is a contract concept, so its type, constants, and closed-set validation now live in internal/clijson (the cli.json contract package) instead of bundle/internal/annotation. The annotation package keeps only the presentation mapping (PreviewTag), now keyed by clijson.LaunchStage. Fully guaranteeing that no other value can be produced by the contract requires the upstream producer to emit this enum for launch_stage; until then clijson.ParseLaunchStage enforces the closed set where the contract is consumed. Co-authored-by: Isaac
Per review of #5611: the launch-stage holder in the Python (pydabs) codegen is renamed from Stage to LaunchStage to match clijson.LaunchStage in the Go code, and all four stages are mirrored as constants for completeness even though jsonschema.json only carries the private-preview stage today. No change to the generated bundle models. Co-authored-by: Isaac
janniklasrose
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
janniklasrose
temporarily deployed
to
test-trigger-is
GitHub Actions
Inactive
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
3 participants
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.
Changes
Two follow-ups requested in the review of #5443:
LaunchStagetype + enforcement (comment). Add aLaunchStagetype ininternal/clijson(the cli.json contract package) with the known stages (GA,PUBLIC_PREVIEW,PUBLIC_BETA,PRIVATE_PREVIEW) as constants and a closed-setParseLaunchStage. Schema generation validates everylaunch_stageread from.codegen/cli.jsonand fails with an actionable error on any unrecognized stage, so a stage introduced upstream can't silently render as GA.bundle/internal/annotationkeeps only the presentation mapping (PreviewTag), keyed byclijson.LaunchStage.Drop the
x-databricks-previewremnant (comment).x-databricks-previewexisted only as a remnant of previous codegen. The published schema now carriesx-databricks-launch-stageinstead, and the Python (pydabs) codegen reads the launch stage exclusively (itsLaunchStageclass mirrorsclijson.LaunchStage).Behavior
Behavior-preserving refactor — the set of hidden/experimental fields is unchanged:
jsonschema.json/jsonschema_for_docs.json: eachx-databricks-preview: PRIVATEentry becomesx-databricks-launch-stage: PRIVATE_PREVIEW;doNotSuggestis unchanged.annotations_openapi.yml: the derivedx-databricks-previewentries are dropped (x-databricks-launch-stagewas already present).python/databricks/bundles/**are byte-identical.Design notes
x-databricks-launch-stageis emitted into the published schema only for the private-preview stage — the only stage any consumer acts on (doNotSuggestand pydabsexperimental). Other stages still surface as the description prefix and the per-valueenumDescriptionslabels, matching the original rationale in Expose stage/release status in schema #5443 for keeping the published schema lean.launch_stageas a plain string (theclijsonwire types are generated by genkit). Fully guaranteeing that no value outside the closed set can be produced requires upstreaming the producer to emit theLaunchStageenum directly; until thenclijson.ParseLaunchStageenforces the set where the contract is consumed.Testing
go test ./internal/clijson/... ./bundle/internal/... ./bundle/schema/... ./libs/jsonschema/...go test ./acceptance -run TestAccept/bundle/refschemapython/codegen/codegen_tests/)./task generate-schema,generate-schema-docs, andpydabs-codegen; verified the only schema change is thex-databricks-preview→x-databricks-launch-stageswap and that the generated pydabs models are unchanged.Follow-up to #5443.
This pull request and its description were written by Isaac, an AI coding agent.