Skip to content

Generate the boilerplate resource and lifecycle descriptions in the schema annotations #7356

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
janniklasrose wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

Generate the boilerplate resource and lifecycle descriptions in the schema annotations #7356

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9df7d2d
Generate the boilerplate resource and lifecycle descriptions in the s…
janniklasrose Nov 4, 2026
ae42b28
Regenerate the PyDABs models for the boilerplate descriptions
janniklasrose Nov 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 31 additions & 3 deletions bundle/internal/schema/annotations.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,8 @@ import (
"regexp"
"strings"

"github.com/databricks/cli/bundle/config"
"github.com/databricks/cli/bundle/config/resources"
"github.com/databricks/cli/bundle/internal/annotation"
"github.com/databricks/cli/internal/clijson"
"github.com/databricks/cli/libs/dyn"
Expand Down Expand Up @@ -112,15 +114,41 @@ func (d *annotationHandler) addAnnotations(typ reflect.Type, s jsonschema.Schema

for k, v := range s.Properties {
item := ta.Fields[k]
if item.Description == "" {
item.Description = annotation.Placeholder
d.missingAnnotations.SetField(refPath, k, annotation.Descriptor{Description: annotation.Placeholder})
if item.Description == "" || item.Description == annotation.Placeholder {
if text := boilerplateDescription(typ, k); text != "" {
item.Description = text
d.missingAnnotations.SetField(refPath, k, annotation.Descriptor{Description: text})
} else if item.Description == "" {
item.Description = annotation.Placeholder
d.missingAnnotations.SetField(refPath, k, annotation.Descriptor{Description: annotation.Placeholder})
}
}
assignAnnotation(v, item)
}
return s
}

const resourceLifecycleDescription = "Settings that control the deployment lifecycle of the resource, such as preventing it from being destroyed."

// boilerplateDescription returns the text that every resource type repeats for
// field k of typ, or "". Callers apply it only to undocumented or placeholder
// fields, so hand-written text is never replaced.
func boilerplateDescription(typ reflect.Type, k string) string {
switch {
case typ == reflect.TypeFor[config.Resources]():
desc, ok := config.SupportedResources()[k]
if !ok {
return ""
}
name := strings.ReplaceAll(desc.SingularName, "_", " ")
return fmt.Sprintf("The %s definitions for the bundle, where each key is the name of the %s.", name, name)
case k == "lifecycle" && typ.PkgPath() == reflect.TypeFor[resources.Job]().PkgPath():
return resourceLifecycleDescription
default:
return ""
}
}

// Writes the annotations file back in canonical form, adding placeholder
// descriptions for fields that have no documentation anywhere. Entries for
// fields that no longer exist in the config are dropped with a warning.
Expand Down
36 changes: 18 additions & 18 deletions bundle/internal/schema/annotations.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -258,7 +258,7 @@ resources:
"$fields":
"alerts":
"description": |-
PLACEHOLDER
The alert definitions for the bundle, where each key is the name of the alert.
"$fields":
"evaluation":
"description": |-
Expand Down Expand Up @@ -525,7 +525,7 @@ resources:
PLACEHOLDER
"catalogs":
"description": |-
PLACEHOLDER
The catalog definitions for the bundle, where each key is the name of the catalog.
"$fields":
"grants":
"description": |-
Expand Down Expand Up @@ -562,11 +562,11 @@ resources:
PLACEHOLDER
"cluster_policies":
"description": |-
PLACEHOLDER
The cluster policy definitions for the bundle, where each key is the name of the cluster policy.
"$fields":
"lifecycle":
"description": |-
PLACEHOLDER
Settings that control the deployment lifecycle of the resource, such as preventing it from being destroyed.
"permissions":
"description": |-
The permissions to apply to this resource.
Expand Down Expand Up @@ -810,7 +810,7 @@ resources:
Settings that control the deployment lifecycle of the resource, such as preventing it from being destroyed.
"database_catalogs":
"description": |-
PLACEHOLDER
The database catalog definitions for the bundle, where each key is the name of the database catalog.
"$fields":
"create_database_if_not_exists":
"description": |-
Expand All @@ -823,7 +823,7 @@ resources:
PLACEHOLDER
"database_instances":
"description": |-
PLACEHOLDER
The database instance definitions for the bundle, where each key is the name of the database instance.
"$fields":
"lifecycle":
"description": |-
Expand Down Expand Up @@ -902,7 +902,7 @@ resources:
The name of the user granted the permission level.
"external_locations":
"description": |-
PLACEHOLDER
The external location definitions for the bundle, where each key is the name of the external location.
"$fields":
"effective_file_event_queue":
"$fields":
Expand Down Expand Up @@ -987,7 +987,7 @@ resources:
PLACEHOLDER
"lifecycle":
"description": |-
PLACEHOLDER
Settings that control the deployment lifecycle of the resource, such as preventing it from being destroyed.
"source":
"$fields":
"delta_table_source":
Expand All @@ -1011,7 +1011,7 @@ resources:
PLACEHOLDER
"genie_spaces":
"description": |-
PLACEHOLDER
The genie space definitions for the bundle, where each key is the name of the genie space.
"$fields":
"description":
"description": |-
Expand Down Expand Up @@ -1311,7 +1311,7 @@ resources:
Deprecated: setting this field is rejected. Use `cron_schedule_trigger` instead.
"mcp_services":
"description": |-
PLACEHOLDER
The mcp service definitions for the bundle, where each key is the name of the mcp service.
"$fields":
"comment":
"description": |-
Expand All @@ -1324,7 +1324,7 @@ resources:
PLACEHOLDER
"lifecycle":
"description": |-
PLACEHOLDER
Settings that control the deployment lifecycle of the resource, such as preventing it from being destroyed.
"mcp_service_id":
"description": |-
PLACEHOLDER
Expand All @@ -1333,7 +1333,7 @@ resources:
PLACEHOLDER
"model_provider_services":
"description": |-
PLACEHOLDER
The model provider service definitions for the bundle, where each key is the name of the model provider service.
"$fields":
"comment":
"description": |-
Expand All @@ -1346,7 +1346,7 @@ resources:
PLACEHOLDER
"lifecycle":
"description": |-
PLACEHOLDER
Settings that control the deployment lifecycle of the resource, such as preventing it from being destroyed.
"model_provider_service_id":
"description": |-
PLACEHOLDER
Expand All @@ -1355,7 +1355,7 @@ resources:
PLACEHOLDER
"model_services":
"description": |-
PLACEHOLDER
The model service definitions for the bundle, where each key is the name of the model service.
"$fields":
"comment":
"description": |-
Expand All @@ -1368,7 +1368,7 @@ resources:
PLACEHOLDER
"lifecycle":
"description": |-
PLACEHOLDER
Settings that control the deployment lifecycle of the resource, such as preventing it from being destroyed.
"model_service_id":
"description": |-
PLACEHOLDER
Expand Down Expand Up @@ -2115,7 +2115,7 @@ resources:
PLACEHOLDER
"synced_database_tables":
"description": |-
PLACEHOLDER
The synced database table definitions for the bundle, where each key is the name of the synced database table.
"$fields":
"data_synchronization_status":
"$fields":
Expand All @@ -2129,7 +2129,7 @@ resources:
Settings that control the deployment lifecycle of the resource, such as preventing it from being destroyed.
"vector_search_endpoints":
"description": |-
PLACEHOLDER
The vector search endpoint definitions for the bundle, where each key is the name of the vector search endpoint.
"$fields":
"lifecycle":
"description": |-
Expand Down Expand Up @@ -2166,7 +2166,7 @@ resources:
PLACEHOLDER
"vector_search_indexes":
"description": |-
PLACEHOLDER
The vector search index definitions for the bundle, where each key is the name of the vector search index.
"$fields":
"grants":
"description": |-
Expand Down
23 changes: 23 additions & 0 deletions bundle/internal/schema/annotations_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,11 @@
package main

import (
"reflect"
"testing"

"github.com/databricks/cli/bundle/config"
"github.com/databricks/cli/bundle/config/resources"
"github.com/databricks/cli/bundle/internal/annotation"
"github.com/databricks/cli/internal/clijson"
"github.com/databricks/cli/libs/jsonschema"
Expand Down Expand Up @@ -270,3 +273,23 @@ func TestBuildEnumDescriptions(t *testing.T) {
assert.Equal(t, []string{"[Public Preview]", "", "[Beta]"}, got)
})
}

// A new resource with no annotations gets the boilerplate descriptions for its
// resource-level entry and its lifecycle field instead of the placeholder.
func TestBoilerplateDescriptionsForNewResource(t *testing.T) {
h, err := newAnnotationHandler(annotation.File{}, annotation.File{})
require.NoError(t, err)

resourcesSchema := jsonschema.Schema{Properties: map[string]*jsonschema.Schema{"jobs": {}}}
h.addAnnotations(reflect.TypeFor[config.Resources](), resourcesSchema)
const jobsDescription = "The job definitions for the bundle, where each key is the name of the job."
assert.Equal(t, jobsDescription, resourcesSchema.Properties["jobs"].Description)
assert.Equal(t, jobsDescription, h.missingAnnotations[getPath(reflect.TypeFor[config.Resources]())].Fields["jobs"].Description)

jobSchema := jsonschema.Schema{Properties: map[string]*jsonschema.Schema{"lifecycle": {}, "name": {}}}
h.addAnnotations(reflect.TypeFor[resources.Job](), jobSchema)
jobPath := getPath(reflect.TypeFor[resources.Job]())
assert.Equal(t, resourceLifecycleDescription, h.missingAnnotations[jobPath].Fields["lifecycle"].Description)
// Fields without boilerplate keep the placeholder.
assert.Equal(t, annotation.Placeholder, h.missingAnnotations[jobPath].Fields["name"].Description)
}
18 changes: 18 additions & 0 deletions bundle/schema/jsonschema.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

6 changes: 6 additions & 0 deletions python/databricks/bundles/cluster_policies/_models/cluster_policy.py
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

Loading
Loading