Improve Radius.Core resource type documentation, property descriptions, and default values by zachcasper · Pull Request #12439 · radius-project/radius

zachcasper · 2026-07-15T16:41:46Z

Summary

This pull request improves the documentation for the Radius.Core resource types (applications, environments, recipePacks, bicepSettings, and terraformSettings) so that platform engineers and developers can understand and use them from the resource type definition alone. It combines two related efforts: expanded, example-driven type-level documentation and a full pass over every schema property description. The changes are authored in TypeSpec and reflected in the generated Go models and the OpenAPI specification, and are verified by the unit tests.

The most important changes are:

Resource Type Documentation Improvements:

Expanded the type-level descriptions for ApplicationResource, BicepSettingsResource, EnvironmentResource, RecipePackResource, and TerraformSettingsResource to include detailed explanations, Bicep and CLI examples, and deployment instructions.

Property Description Improvements:

Added (Required), (Optional), and (Read Only) prefixes to every schema property across the five resource types, matching each property's schema optionality.
Rewrote the property descriptions to be accurate, precise, and helpful for platform engineers, conforming to the resource-types-contrib documentation standards.
Documented default values on optional properties. For example, environments.providers now notes it defaults to Kubernetes in the default namespace, and environments.recipePacks notes it defaults to the default Recipe Pack in the default resource group.
Standardized on "Bicep settings" and "Terraform settings" naming throughout.

Testing and Validation:

Updated the unit test in pkg/ucp/initializer/service_test.go to check that the resource type descriptions contain the expected prefixes, ensuring the documentation is present and correct in the API summary.

Reason for change

These changes significantly improve the developer and platform engineer experience by making the API documentation more comprehensive and actionable, and by surfacing default values that were previously undocumented.

Fixes #12429
Fixes #12430
Fixes #12431

How to test

rad resource-type show Radius.Core/applications
rad resource-type show Radius.Core/environments
rad resource-type show Radius.Core/recipePacks
rad resource-type show Radius.Core/terraformSettings
rad resource-type show Radius.Core/bicepSettings

Also view in the dashboard. Screenshots below:

Radius.Core/applications before:

Radius.Core/applications after:

Radius.Core/environments before:

Radius.Core/environments after:

Radius.Core/recipePacks before:

Radius.Core/recipePacks after:

Radius.Core/terraformSettings before:

Radius.Core/terraformSettings after:

Radius.Core/bicepSettings before:

Radius.Core/bicepSettings after:

Copilot

Pull request overview

This PR improves developer/platform-engineer documentation for key Radius.Core resource types by expanding their description text (TypeSpec → generated Go models/responses → OpenAPI), and updates a unit test to validate that the richer descriptions are present in the registered resource type summaries.

Changes:

Expanded @doc(...) descriptions for applications, environments, recipePacks, bicepSettings, and terraformSettings in TypeSpec with usage guidance and examples.
Regenerated/updated corresponding OpenAPI and Go generated artifacts so the richer documentation flows through the API surface.
Updated pkg/ucp/initializer/service_test.go to validate the new description content is present.

Reviewed changes

Copilot reviewed 7 out of 9 changed files in this pull request and generated 18 comments.

Show a summary per file

File	Description
typespec/Radius.Core/applications.tsp	Adds expanded developer documentation for `Radius.Core/applications`, including Bicep/CLI examples.
typespec/Radius.Core/bicepSettings.tsp	Adds expanded documentation for `Radius.Core/bicepSettings` including registry auth examples.
typespec/Radius.Core/environments.tsp	Adds expanded documentation for `Radius.Core/environments` including CLI and Bicep examples and defaults.
typespec/Radius.Core/recipePacks.tsp	Adds expanded documentation for `Radius.Core/recipePacks` including authoring and referencing examples.
typespec/Radius.Core/terraformSettings.tsp	Adds expanded documentation for `Radius.Core/terraformSettings` including private registry + provider mirror examples.
swagger/specification/radius/resource-manager/Radius.Core/preview/2025-08-01-preview/openapi.json	Updates OpenAPI descriptions to match the new expanded TypeSpec docs.
pkg/corerp/api/v20250801preview/zz_generated_models.go	Updates generated Go model comments to carry the new resource type documentation.
pkg/corerp/api/v20250801preview/zz_generated_responses.go	Updates generated Go response comments to carry the new resource type documentation.
pkg/ucp/initializer/service_test.go	Adjusts the test to validate the updated description content is present for registered types.

Files not reviewed (2)

pkg/corerp/api/v20250801preview/zz_generated_models.go: Generated file
pkg/corerp/api/v20250801preview/zz_generated_responses.go: Generated file

codecov · 2026-07-15T17:41:58Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 53.88%. Comparing base (13b3e87) to head (c149c34).

Additional details and impacted files

@@           Coverage Diff           @@
##             main   #12439   +/-   ##
=======================================
  Coverage   53.88%   53.88%           
=======================================
  Files         765      765           
  Lines       50647    50647           
=======================================
  Hits        27290    27290           
  Misses      20787    20787           
  Partials     2570     2570

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

github-actions · 2026-07-16T21:48:52Z

Functional Tests - corerp-cloud

30 tests ±0 29 ✅ +2 22m 11s ⏱️ - 26m 14s
2 suites ±0 1 💤 ±0
1 files ±0 0 ❌ - 2

Results for commit dbeea4a. ± Comparison against base commit 375f076.

♻️ This comment has been updated with latest results.

Copilot

Pull request overview

Copilot reviewed 7 out of 12 changed files in this pull request and generated 3 comments.

Files not reviewed (4)

pkg/corerp/api/v20250801preview/zz_generated_bicepsettings_client.go: Generated file
pkg/corerp/api/v20250801preview/zz_generated_models.go: Generated file
pkg/corerp/api/v20250801preview/zz_generated_responses.go: Generated file
pkg/corerp/api/v20250801preview/zz_generated_terraformsettings_client.go: Generated file

Copilot

Pull request overview

Copilot reviewed 7 out of 12 changed files in this pull request and generated no new comments.

Files not reviewed (4)

pkg/corerp/api/v20250801preview/zz_generated_bicepsettings_client.go: Generated file
pkg/corerp/api/v20250801preview/zz_generated_models.go: Generated file
pkg/corerp/api/v20250801preview/zz_generated_responses.go: Generated file
pkg/corerp/api/v20250801preview/zz_generated_terraformsettings_client.go: Generated file

Comments suppressed due to low confidence (2)

typespec/Radius.Core/bicepSettings.tsp:136

The description for basicAuthSecretId now states only Radius.Security/secrets is supported, but the implementation still supports legacy Applications.Core/secretStores as well (see pkg/recipes/configloader/secrets.go and pkg/corerp/datamodel/bicepsettings.go). Update the doc to reflect both supported secret resource types (and keep Radius.Security/secrets as recommended).

  @doc("(Optional) The ID of a `Radius.Security/secrets` resource containing the username and password. Required when `authenticationMethod` is `BasicAuth`.")

typespec/Radius.Core/terraformSettings.tsp:214

The description for TerraformCredentialConfig.secret now states only Radius.Security/secrets is supported, but the recipes secret loader still supports both Radius.Security/secrets and legacy Applications.Core/secretStores (see pkg/recipes/configloader/secrets.go and pkg/corerp/datamodel/terraformsettings.go). Update the doc to reflect both supported resource types (with Radius.Security/secrets recommended).

  @doc("(Optional) The ID of a `Radius.Security/secrets` resource containing the authentication token. The secret must have a key named `token`.")

Copilot

Pull request overview

Copilot reviewed 7 out of 12 changed files in this pull request and generated no new comments.

Files not reviewed (4)

pkg/corerp/api/v20250801preview/zz_generated_bicepsettings_client.go: Generated file
pkg/corerp/api/v20250801preview/zz_generated_models.go: Generated file
pkg/corerp/api/v20250801preview/zz_generated_responses.go: Generated file
pkg/corerp/api/v20250801preview/zz_generated_terraformsettings_client.go: Generated file

Comments suppressed due to low confidence (2)

typespec/Radius.Core/terraformSettings.tsp:215

The doc for TerraformCredentialConfig.secret now states only Radius.Security/secrets is supported, but the code path that loads secrets still accepts both Radius.Security/secrets and legacy Applications.Core/secretStores IDs (see pkg/recipes/configloader/secrets.go and pkg/corerp/datamodel/terraformsettings.go). Update the description to avoid incorrectly rejecting valid inputs.

@doc("Credential configuration for a Terraform registry or module source host.")
model TerraformCredentialConfig {
  @doc("(Optional) The ID of a `Radius.Security/secrets` resource containing the authentication token. The secret must have a key named `token`.")
  secret?: string;

typespec/Radius.Core/bicepSettings.tsp:137

basicAuthSecretId is documented as only supporting Radius.Security/secrets, but the secrets loader and CoreRP datamodel still support Applications.Core/secretStores as well (legacy compatibility). Update this description to reflect actual supported resource types so users aren't misled.

  @doc("(Optional) How Radius authenticates to the registry.")
  authenticationMethod?: BicepAuthenticationMethod;

  @doc("(Optional) The ID of a `Radius.Security/secrets` resource containing the username and password. Required when `authenticationMethod` is `BasicAuth`.")
  basicAuthSecretId?: string;

Signed-off-by: Zach Casper <zachcasper@microsoft.com>

Add (Required)/(Optional)/(Read Only) prefixes to every schema property across the five Radius.Core resource types (applications, environments, recipePacks, bicepSettings, terraformSettings) and rewrite the descriptions to be accurate, precise, and helpful for platform engineers, conforming to the resource-types-contrib documentation standards. Document default values on optional properties (for example providers and recipePacks on environments). Standardize on "Bicep settings" and "Terraform settings" naming and regenerate the OpenAPI spec and Go clients. Fixes radius-project#12430 Fixes radius-project#12431 Signed-off-by: Zach Casper <zachcasper@microsoft.com>

Signed-off-by: Zach Casper <zachcasper@microsoft.com>

Copilot

Pull request overview

Copilot reviewed 7 out of 12 changed files in this pull request and generated no new comments.

Files not reviewed (4)

pkg/corerp/api/v20250801preview/zz_generated_bicepsettings_client.go: Generated file
pkg/corerp/api/v20250801preview/zz_generated_models.go: Generated file
pkg/corerp/api/v20250801preview/zz_generated_responses.go: Generated file
pkg/corerp/api/v20250801preview/zz_generated_terraformsettings_client.go: Generated file

Comments suppressed due to low confidence (2)

typespec/Radius.Core/bicepSettings.tsp:136

This description now claims only Radius.Security/secrets is supported, but the recipe secret loader and registry auth plumbing still support Applications.Core/secretStores as well (see pkg/recipes/configloader/secrets.go and pkg/corerp/datamodel/recipe_types.go). Update the doc to reflect both supported secret resource types (and optionally mark Radius.Security/secrets as recommended).

  @doc("(Optional) The ID of a `Radius.Security/secrets` resource containing the username and password. Required when `authenticationMethod` is `BasicAuth`.")

typespec/Radius.Core/terraformSettings.tsp:214

This description now claims only Radius.Security/secrets is supported, but the secrets loader used by Terraform recipe execution still supports Applications.Core/secretStores as well (it dispatches by resource type and can load both). Update the doc to reflect both supported secret resource types (and optionally mark Radius.Security/secrets as recommended).

  @doc("(Optional) The ID of a `Radius.Security/secrets` resource containing the authentication token. The secret must have a key named `token`.")

radius-functional-tests · 2026-07-22T21:08:06Z

Radius functional test overview

🔍 Go to test action run

Click here to see the test run details

Name	Value
Repository	zachcasper/radius
Commit ref	`c149c34`
Unique ID	func668f295de5
Image tag	pr-func668f295de5

Dapr: 1.14.4
Azure KeyVault CSI driver: 1.4.2
Azure Workload identity webhook: 1.3.0
Bicep recipe location ghcr.io/radius-project/dev/test/testrecipes/test-bicep-recipes/<name>:pr-func668f295de5
Terraform recipe location http://tf-module-server.radius-test-tf-module-server.svc.cluster.local/<name>.zip (in cluster)
applications-rp test image location: ghcr.io/radius-project/dev/applications-rp:pr-func668f295de5
dynamic-rp test image location: ghcr.io/radius-project/dev/dynamic-rp:pr-func668f295de5
controller test image location: ghcr.io/radius-project/dev/controller:pr-func668f295de5
ucp test image location: ghcr.io/radius-project/dev/ucpd:pr-func668f295de5
deployment-engine test image location: ghcr.io/radius-project/deployment-engine:latest

Test Status

⌛ Building Radius and pushing container images for functional tests...
✅ Container images build succeeded
⌛ Publishing Bicep Recipes for functional tests...
✅ Recipe publishing succeeded
⌛ Starting corerp-cloud functional tests...
✅ Container images build succeeded
⌛ Publishing Bicep Recipes for functional tests...
✅ Recipe publishing succeeded
⌛ Starting corerp-cloud functional tests...
⌛ Starting ucp-cloud functional tests...
✅ ucp-cloud functional tests succeeded
✅ ucp-cloud functional tests succeeded
✅ corerp-cloud functional tests succeeded
✅ corerp-cloud functional tests succeeded

Copilot

Pull request overview

Copilot reviewed 7 out of 12 changed files in this pull request and generated no new comments.

Files not reviewed (4)

pkg/corerp/api/v20250801preview/zz_generated_bicepsettings_client.go: Generated file
pkg/corerp/api/v20250801preview/zz_generated_models.go: Generated file
pkg/corerp/api/v20250801preview/zz_generated_responses.go: Generated file
pkg/corerp/api/v20250801preview/zz_generated_terraformsettings_client.go: Generated file

Comments suppressed due to low confidence (2)

typespec/Radius.Core/terraformSettings.tsp:214

The docs narrow this to only Radius.Security/secrets, but the runtime secret loader and datamodel still support legacy Applications.Core/secretStores IDs as well. This makes the schema docs inaccurate for existing users and conflicts with the actual supported resource types.

  @doc("(Optional) The ID of a `Radius.Security/secrets` resource containing the authentication token. The secret must have a key named `token`.")

typespec/Radius.Core/bicepSettings.tsp:136

This description states only Radius.Security/secrets, but the codebase still supports legacy Applications.Core/secretStores for basicAuthSecretId (see datamodel + secret loader). Update the docs to reflect both supported secret resource types so the TypeSpec/OpenAPI docs don’t mislead existing users.

  @doc("(Optional) The ID of a `Radius.Security/secrets` resource containing the username and password. Required when `authenticationMethod` is `BasicAuth`.")

zachcasper requested review from a team as code owners July 15, 2026 16:41

Copilot AI review requested due to automatic review settings July 15, 2026 16:41

Copilot started reviewing on behalf of zachcasper July 15, 2026 16:42 View session

Copilot AI reviewed Jul 15, 2026

View reviewed changes

zachcasper added the pr:standard label Jul 15, 2026

zachcasper changed the title ~~Add developer and PE documentation for Radius.Core Resource Types~~ Improve Radius.Core resource type documentation, property descriptions, and default values Jul 16, 2026

lakshmimsft reviewed Jul 17, 2026

View reviewed changes

Comment thread typespec/Radius.Core/environments.tsp Outdated

Copilot AI review requested due to automatic review settings July 22, 2026 17:34

Copilot started reviewing on behalf of zachcasper July 22, 2026 17:35 View session

Copilot AI reviewed Jul 22, 2026

View reviewed changes

Comment thread typespec/Radius.Core/bicepSettings.tsp

Comment thread typespec/Radius.Core/bicepSettings.tsp

Comment thread typespec/Radius.Core/terraformSettings.tsp

lakshmimsft previously approved these changes Jul 22, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 22, 2026 20:22

zachcasper dismissed lakshmimsft’s stale review via c5203c5 July 22, 2026 20:22

Copilot started reviewing on behalf of zachcasper July 22, 2026 20:22 View session

zachcasper force-pushed the core-resource-type-desciptions branch from c5203c5 to 8657a65 Compare July 22, 2026 20:25

Copilot AI reviewed Jul 22, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 22, 2026 20:26

Copilot started reviewing on behalf of zachcasper July 22, 2026 20:27 View session

Copilot AI reviewed Jul 22, 2026

View reviewed changes

zachcasper enabled auto-merge July 22, 2026 20:47

Copilot AI review requested due to automatic review settings July 22, 2026 21:03

Copilot started reviewing on behalf of zachcasper July 22, 2026 21:03 View session

zachcasper added 5 commits July 22, 2026 16:06

Added dev docs to Radius.Core/applications

aa0f88a

Signed-off-by: Zach Casper <zachcasper@microsoft.com>

Added PE docs to Radius.Core/environments

31ecad7

Signed-off-by: Zach Casper <zachcasper@microsoft.com>

Added PE docs to Radius.Core/recipePacks

6e48180

Signed-off-by: Zach Casper <zachcasper@microsoft.com>

Added PE docs to Radius.Core/bicepSettings and terraformSettings

1bbdb34

Signed-off-by: Zach Casper <zachcasper@microsoft.com>

Final cleanup for consistency

36c06c6

Signed-off-by: Zach Casper <zachcasper@microsoft.com>

zachcasper added 8 commits July 22, 2026 16:06

Added existing recipe pack to environment example

94bb2b7

Signed-off-by: Zach Casper <zachcasper@microsoft.com>

Use real prefix check for Radius.Core description test

622ddfb

Signed-off-by: Zach Casper <zachcasper@microsoft.com>

Apply tsp format and regenerate Radius.Core openapi and client

23096df

Signed-off-by: Zach Casper <zachcasper@microsoft.com>

Regenerate Radius.Core Bicep types for updated descriptions

80b4eee

Signed-off-by: Zach Casper <zachcasper@microsoft.com>

Adjusted cloud provider docs on env based on feedback

5d53994

Signed-off-by: Zach Casper <zachcasper@microsoft.com>

Fix lint formatting

a347827

Signed-off-by: Zach Casper <zachcasper@microsoft.com>

Regenerate code for Radius.Core environment doc updates

c149c34

Signed-off-by: Zach Casper <zachcasper@microsoft.com>

zachcasper force-pushed the core-resource-type-desciptions branch from 8ebdc6b to c149c34 Compare July 22, 2026 21:07

Copilot AI reviewed Jul 22, 2026

View reviewed changes

Copilot AI review requested due to automatic review settings July 22, 2026 21:07

Copilot started reviewing on behalf of zachcasper July 22, 2026 21:07 View session

Copilot AI reviewed Jul 22, 2026

View reviewed changes

lakshmimsft approved these changes Jul 22, 2026

View reviewed changes

Uh oh!

Conversation

zachcasper commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Reason for change

How to test

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov Bot commented Jul 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

github-actions Bot commented Jul 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Functional Tests - corerp-cloud

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

radius-functional-tests Bot commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Radius functional test overview

Test Status

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

zachcasper commented Jul 15, 2026 •

edited

Loading

codecov Bot commented Jul 15, 2026 •

edited

Loading

github-actions Bot commented Jul 16, 2026 •

edited

Loading

radius-functional-tests Bot commented Jul 22, 2026 •

edited

Loading