Expose stage/release status in schema (#5443)

## Changes
Expose launch stage/release status in the bundle schema

## Why
Non-GA fields should be annotated as such when viewing a bundle in IDEs.

## Tests

Example vector search endpoint:

Enum with one GA, one PuPr:
<img width="444" height="208" alt="Screenshot 2026-06-12 at 09 32 00"
src="https://github.com/user-attachments/assets/42fcacb3-fb9d-431a-8f2d-f8f254e610d1"
/>

PuPr field without any annotation:
<img width="444" height="254" alt="Screenshot 2026-06-04 at 14 29 49"
src="https://github.com/user-attachments/assets/4c8e1c9d-5030-4eb9-a4b8-9898c3515d33"
/>

---------

Co-authored-by: Pieter Noordhuis <pieter.noordhuis@databricks.com>

Author: janniklasrose

.vscode/settings.json

@@ -22,5 +22,11 @@
         "script": "shellscript",
         "script.prepare": "shellscript",
         "script.cleanup": "shellscript"
+    },
+    "yaml.schemas": {
+        "./bundle/schema/jsonschema.json": [
+            "databricks.yml",
+            "databricks.yaml",
+        ]
     }
 }

bundle/internal/annotation/descriptor.go

@@ -1,15 +1,18 @@
 package annotation
 
 type Descriptor struct {
-	Description         string `json:"description,omitempty"`
-	MarkdownDescription string `json:"markdown_description,omitempty"`
-	Title               string `json:"title,omitempty"`
-	Default             any    `json:"default,omitempty"`
-	Enum                []any  `json:"enum,omitempty"`
-	MarkdownExamples    string `json:"markdown_examples,omitempty"`
-	DeprecationMessage  string `json:"deprecation_message,omitempty"`
-	Preview             string `json:"x-databricks-preview,omitempty"`
-	OutputOnly          *bool  `json:"x-databricks-field-behaviors_output_only,omitempty"`
+	Description         string            `json:"description,omitempty"`
+	MarkdownDescription string            `json:"markdown_description,omitempty"`
+	Title               string            `json:"title,omitempty"`
+	Default             any               `json:"default,omitempty"`
+	Enum                []any             `json:"enum,omitempty"`
+	MarkdownExamples    string            `json:"markdown_examples,omitempty"`
+	DeprecationMessage  string            `json:"deprecation_message,omitempty"`
+	Preview             string            `json:"x-databricks-preview,omitempty"`
+	LaunchStage         string            `json:"x-databricks-launch-stage,omitempty"`
+	EnumLaunchStages    map[string]string `json:"x-databricks-enum-launch-stages,omitempty"`
+	EnumDescriptions    map[string]string `json:"x-databricks-enum-descriptions,omitempty"`
+	OutputOnly          *bool             `json:"x-databricks-field-behaviors_output_only,omitempty"`
 }
 
 const Placeholder = "PLACEHOLDER"

bundle/internal/annotation/preview.go

@@ -0,0 +1,15 @@
+package annotation
+
+// PreviewTag returns the human-readable launch-stage prefix to prepend to a
+// field's or enum value's description. Others are skipped.
+func PreviewTag(launchStage string) string {
+	switch launchStage {
+	case "PRIVATE_PREVIEW":
+		return "[Private Preview]"
+	case "PUBLIC_BETA":
+		return "[Beta]"
+	case "PUBLIC_PREVIEW":
+		return "[Public Preview]"
+	}
+	return ""
+}

bundle/internal/annotation/preview_test.go

@@ -0,0 +1,25 @@
+package annotation_test
+
+import (
+	"testing"
+
+	"github.com/databricks/cli/bundle/internal/annotation"
+	"github.com/stretchr/testify/assert"
+)
+
+func TestPreviewTag(t *testing.T) {
+	tests := []struct {
+		launchStage string
+		want        string
+	}{
+		{"PUBLIC_PREVIEW", "[Public Preview]"},
+		{"PUBLIC_BETA", "[Beta]"},
+		{"PRIVATE_PREVIEW", "[Private Preview]"},
+		{"GA", ""},
+		{"", ""},
+		{"SOMETHING_ELSE", ""},
+	}
+	for _, tc := range tests {
+		assert.Equal(t, tc.want, annotation.PreviewTag(tc.launchStage))
+	}
+}

bundle/internal/schema/annotations.go

@@ -134,6 +134,13 @@ func assignAnnotation(s *jsonschema.Schema, a annotation.Descriptor) {
 		s.DeprecationMessage = a.DeprecationMessage
 	}
 
+	// The raw launch stage is intentionally not emitted into the published
+	// schema — nothing consumes it there. It surfaces only as the description
+	// prefix below and the per-value enumDescriptions labels.
+	// x-databricks-preview does stay: the parser derives it from launch_stage
+	// (PRIVATE iff PRIVATE_PREVIEW), and pydabs reads it from jsonschema.json
+	// to mark fields experimental, so this branch also covers hiding
+	// private-preview fields.
 	if a.Preview == "PRIVATE" {
 		s.DoNotSuggest = true
 		s.Preview = a.Preview
@@ -146,6 +153,54 @@ func assignAnnotation(s *jsonschema.Schema, a annotation.Descriptor) {
 	s.MarkdownDescription = convertLinksToAbsoluteUrl(a.MarkdownDescription)
 	s.Title = a.Title
 	s.Enum = a.Enum
+	s.EnumDescriptions = buildEnumDescriptions(a.Enum, a.EnumLaunchStages, a.EnumDescriptions)
+
+	// Surface launch stage in hover tooltips. Editors only render the standard
+	// description field, so the tag is baked into the text.
+	if tag := annotation.PreviewTag(a.LaunchStage); tag != "" {
+		s.Description = prefixWithPreviewTag(s.Description, tag)
+	}
+}
+
+// buildEnumDescriptions produces the parallel enumDescriptions array VSCode
+// renders next to each enum value. Each entry combines the launch-stage tag
+// and the per-value description text. Returns nil when every entry would be
+// empty so the field is omitted from the schema. The enum slice is the same
+// one assigned to s.Enum, so the arrays stay index-aligned.
+func buildEnumDescriptions(enum []any, launchStages, descriptions map[string]string) []string {
+	if len(enum) == 0 || (len(launchStages) == 0 && len(descriptions) == 0) {
+		return nil
+	}
+	result := make([]string, len(enum))
+	hasContent := false
+	for i, v := range enum {
+		key, ok := v.(string)
+		if !ok {
+			continue
+		}
+		result[i] = prefixWithPreviewTag(descriptions[key], annotation.PreviewTag(launchStages[key]))
+		if result[i] != "" {
+			hasContent = true
+		}
+	}
+	if !hasContent {
+		return nil
+	}
+	return result
+}
+
+// prefixWithPreviewTag prepends the launch-stage tag to a description while
+// guarding against double-tagging — if the description already starts with
+// the tag, it is returned unchanged. An empty tag (GA) also takes the
+// HasPrefix path, returning the description as-is.
+func prefixWithPreviewTag(description, tag string) string {
+	if description == "" {
+		return tag
+	}
+	if strings.HasPrefix(description, tag) {
+		return description
+	}
+	return tag + " " + description
 }
 
 func saveYamlWithStyle(outputPath string, annotations annotation.File) error {