feat: new linter rules to enforce descriptions on types, params, var, type properties and output by johnlokerse · Pull Request #20036 · Azure/bicep

John (johnlokerse) · 2026-07-10T08:53:14Z

Description

This change adds a new Bicep linter rule called use-parameter-descriptions. Default the rule level is off but when set to error it checks if the parameter has either the @sys.description or @description decorator above a parameter. Additionally, it checks if the description is not empty.

Anthony Martin (@anthony-c-martin) stephaniezyen This implements issue #9453 and #5595.

Example Usage

It works through the bicep linter command or using the VSCode extension:

Checklist

I have read and adhere to the contribution guide.

Microsoft Reviewers: Open in CodeFlow

…ed tests

John (johnlokerse) · 2026-07-10T08:55:10Z

Documentation is needed for this

John (johnlokerse) · 2026-07-23T14:29:08Z

Anthony Martin (@anthony-c-martin) does anyone on the team have time for a review? 😃

Stanislav Zhelyazkov (slavizh) · 2026-07-23T17:03:08Z

John (@johnlokerse) does it works for types as well? Would be very good if it applies to types as well or if there is separate rule for it. There is one exception for types though - discriminator. for the example below it should not apply as the description for foo is where foo is referenced. If there is description directly on the type it does not appear anywhere.

...
@discriminator('type)
type foo = foo1 | foo2
...

John (johnlokerse) · 2026-07-24T12:38:56Z

John (@johnlokerse) does it works for types as well? Would be very good if it applies to types as well or if there is separate rule for it. There is one exception for types though - discriminator. for the example below it should not apply as the description for foo is where foo is referenced. If there is description directly on the type it does not appear anywhere.
...
@discriminator('type)
type foo = foo1 | foo2
...

Stanislav Zhelyazkov (@slavizh) This can be done. I would do it separately from this linter, though, since not everyone wants to put descriptions on properties in types or on the type itself. The same thing applies to variables and outputs if you ask me.

Or as another option we introduce a configuration to the new use-descriptions linter rule, just like use-recent-api-versions has with the maxAllowedAgeInDays configuration in the bicepconfig.json. Like so:

	"analyzers": {
		"core": {
			"rules": {
				"use-recent-api-versions": {
					"level": "warning",
					"maxAllowedAgeInDays": 500
				},
				"use-descriptions": {
					"level": "error",
					"variables": false,
					"userDefinedTypes": true,
					"parameters": true,
					"outputs": true
				}
			}
		}
	}

Anthony Martin (anthony-c-martin) · 2026-07-24T19:55:59Z

Or as another option we introduce a configuration to the new use-descriptions linter rule, just like use-recent-api-versions has with the maxAllowedAgeInDays configuration in the bicepconfig.json. Like so:

John (@johnlokerse) - the changes in this PR look good to me, but I think it would be a good idea to close on this discussion first - I wouldn't want to release something and then immediately change it.

John (johnlokerse) · 2026-07-27T17:55:01Z

Or as another option we introduce a configuration to the new use-descriptions linter rule, just like use-recent-api-versions has with the maxAllowedAgeInDays configuration in the bicepconfig.json. Like so:

John (@johnlokerse) - the changes in this PR look good to me, but I think it would be a good idea to close on this discussion first - I wouldn't want to release something and then immediately change it.

I agree.

Anthony Martin (@anthony-c-martin) Stanislav Zhelyazkov (@slavizh) What is your take on the proposed configuration in the bicepconfig.json? If you think it's good, I would suggest setting the configurable option (= variables, parameters, udt and output bool toggles) to true if not set in the bicepconfig else use the user-defined value set in the bicepconfig.

Anthony Martin (anthony-c-martin) · 2026-07-27T22:37:00Z

Anthony Martin (@anthony-c-martin) Stanislav Zhelyazkov (@slavizh) What is your take on the proposed configuration in the bicepconfig.json? If you think it's good, I would suggest setting the configurable option (= variables, parameters, udt and output bool toggles) to true if not set in the bicepconfig else use the user-defined value set in the bicepconfig.

What would the "default" behavior be - just parameters?

Another option to consider for how you express this in config is with an array of enums - e.g.:

"use-descriptions": {
  "level": "error",
  "requireOn": ["parameter", "type", "typeProperty", "output"]
}

Stanislav Zhelyazkov (slavizh) · 2026-07-28T05:48:03Z

Anthony Martin (@anthony-c-martin) looks good to me. For parameters by default the highest could be only warning otherwise it will be a breaking change. I am ok to be a warning instead of off. For the others from my perspective they should be warnings by default but I think that might be too aggressive for many users and I do not know if they will react positively on it. Note that the exception on discriminator type is important as that description does not really appear anywhere when it is standalone type referenced.

John (johnlokerse) · 2026-07-28T14:37:36Z

Anthony Martin (@anthony-c-martin) Looks good to me too, and I like the requiredOn property with the array values. However, if we look at the current list of linter rules, this introduces an inconsistency with how the other linter rules work:

If we choose the same approach as the no-unused-* rules, it would be use-description-* instead of configuring it in bicepconfig.json via requiredOn. This would be consistent with the other linter rules. What do you think?

Stanislav Zhelyazkov (@slavizh) I agree on the warning default for parameters, but not for the others. I don’t see many organisations using descriptions for anything besides parameters. I recommend turning these off by default.

Stanislav Zhelyazkov (slavizh) · 2026-07-28T17:13:13Z

John (@johnlokerse) note my suggestion is not based on what is popular but rather what should be the best practice. For example you will see most folks using multiple parameters trying to implement different features for different services that are deployed within the same module instead of trying to group those into a single parameter per resource. Very small example:

param resource1Name string
param resource1Sku string
param resource1MinimumTlsVersion string

param resource2Name string
param resource2MinimumTlsVersion string
param resource2PublicNetworkAccess string

vs.

type resource1Type = {
  name: string
  sku: string
  minimumTlsVersion: string
}

type resource2Type = {
  name: string
  publicNetworkAccess: string
  minimumTlsVersion: string
}
param resource1 resource1Type

param resource2 resource2Type

The latter has a ton of benefits that makes the user experience of modules better. Unfortunately even AVD is implementing that partially. One of the reason for not being widely used is that most folks moved from ARM templates where we did not have such features and everything was flat. Another is that the Portal does not supports such types very well thus the examples created by Microsoft employees also have flat structure. However this is another topic. Overall I think the standard values should represent the desired standard for coding even if it is not what is widely used in order to promote that standard. I also know that some warnings might be annoying in simple scenarios.

Anthony Martin (anthony-c-martin) · 2026-07-29T03:23:23Z

John (@johnlokerse), I'm happy defaulting to "off" for everything, because of the sheer quantity of .bicep files this would flag if enabled by default.

If we choose the same approach as the no-unused-* rules, it would be use-description-* instead of configuring it in bicepconfig.json via requiredOn. This would be consistent with the other linter rules. What do you think?

Good point! I'm fine either way. I think there's benefit to the ease of enabling/disabling if we create separate linters for each.

John (johnlokerse) · 2026-07-29T15:28:51Z

John (@johnlokerse), I'm happy defaulting to "off" for everything, because of the sheer quantity of .bicep files this would flag if enabled by default.

If we choose the same approach as the no-unused-* rules, it would be use-description-* instead of configuring it in bicepconfig.json via requiredOn. This would be consistent with the other linter rules. What do you think?

Good point! I'm fine either way. I think there's benefit to the ease of enabling/disabling if we create separate linters for each.

Anthony Martin (@anthony-c-martin) Okay, so let's keep it consistent with the other linter rules. We default to off, and the following linters will be implemented:

use-description-parameters
use-description-vars
use-description-type
use-description-type-property
use-description-output

Additionally, documentation needs to be created. Will use the same style as this page: https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/linter-rule-no-unused-parameters.

Do I miss anything? If not, I will start building and will update this PR with the new linter rules. 😃

Anthony Martin (anthony-c-martin) · 2026-08-01T18:58:03Z

John (@johnlokerse), I'm happy defaulting to "off" for everything, because of the sheer quantity of .bicep files this would flag if enabled by default.

If we choose the same approach as the no-unused-* rules, it would be use-description-* instead of configuring it in bicepconfig.json via requiredOn. This would be consistent with the other linter rules. What do you think?

Good point! I'm fine either way. I think there's benefit to the ease of enabling/disabling if we create separate linters for each.

Anthony Martin (@anthony-c-martin) Okay, so let's keep it consistent with the other linter rules. We default to off, and the following linters will be implemented:

use-description-parameters

use-description-vars

use-description-type

use-description-type-property

use-description-output

Additionally, documentation needs to be created. Will use the same style as this page: https://learn.microsoft.com/en-us/azure/azure-resource-manager/bicep/linter-rule-no-unused-parameters.

Do I miss anything? If not, I will start building and will update this PR with the new linter rules. 😃

Sounds good to me!

Xelu86 · 2026-08-06T21:48:50Z

Hey John (@johnlokerse) & Anthony Martin (@anthony-c-martin), I've started documenting the "use-parameter-descriptions" rule in an internal draft.

I do have a question. In src/Bicep.Core/Analyzers/Linter/Rules/UseParameterDescriptionsRule.cs‎ & src/vscode-bicep/schemas/bicepconfig.schema.json, I see "use-parameter-descriptions" being used. Will this perhaps change to use-description-parameters for consistency in both code and documentation to match the following linters?

use-description-parameters
use-description-vars
use-description-type
use-description-type-property
use-description-output

…linter rule

Anthony Martin (anthony-c-martin)

Changes look good, but note that you have a merge conflict to fix

…properties

John (johnlokerse) · 2026-08-07T11:06:37Z

Anthony Martin (@anthony-c-martin) Implemented 5 new linter rules to enforce descriptions. As requested by Stanislav Zhelyazkov (@slavizh) a type decorated with @discriminator is skipped. Default is off and linter names are now use-descriptions-<output/parameters/vars/type/type-property>. See video:

CleanShot.2026-08-07.at.12.57.52.mp4

Xelu86 For the documentation the names will be like this:

    use-description-parameters -> https://aka.ms/bicep/linter-diagnostics#use-description-parameters
    use-description-vars -> https://aka.ms/bicep/linter-diagnostics#use-description-vars
    use-description-output -> https://aka.ms/bicep/linter-diagnostics#use-description-output
    use-description-type -> https://aka.ms/bicep/linter-diagnostics#use-description-type
    use-description-type-property -> https://aka.ms/bicep/linter-diagnostics#use-description-type-property

John (johnlokerse) · 2026-08-07T11:16:50Z

The only problem I am seeing is when you right-click on the type property (for example value from the screenshot) and select add @description it adds the description('') to the type instead of the property. Anthony Martin (@anthony-c-martin) Do we want to fix it in this PR or separately?

Anthony Martin (anthony-c-martin) · 2026-08-09T08:00:24Z

Anthony Martin (Anthony Martin (@anthony-c-martin)) Do we want to fix it in this PR or separately?

I think this is fine to address separtely

Anthony Martin (anthony-c-martin) · 2026-08-09T08:02:45Z

John (@johnlokerse) - could we rename the linter rules for parity with the no-unused-<x> linter rules? These rules use plural (types rather than type), and refer to the language constructs by their keywords in Bicep (params rather than parameters).

These would be the updated names:

use-description-params
use-description-vars
use-description-types
use-description-type-properties
use-description-outputs

John (johnlokerse) · 2026-08-10T18:31:00Z

John (John (@johnlokerse)) - could we rename the linter rules for parity with the no-unused-<x> linter rules? These rules use plural (types rather than type), and refer to the language constructs by their keywords in Bicep (params rather than parameters).

These would be the updated names:
use-description-params
use-description-vars
use-description-types
use-description-type-properties
use-description-outputs

Done!

Xelu86 The linter rules are renamed to what Anthony mentioned

John (johnlokerse) added 3 commits July 10, 2026 09:55

use-parameter-descriptions linter tests and logic added

68b7999

Implement new linter rule for parameter descriptions and update relat…

084c064

…ed tests

Removed disable next line comment

a173464

Anthony Martin (anthony-c-martin) added 📘 Docs Not Needed 📘 Docs Needed and removed 📘 Docs Not Needed labels Jul 24, 2026

Renamed parameter description linter rule and added vars description …

9ad9112

…linter rule

Anthony Martin (anthony-c-martin) approved these changes Aug 7, 2026

View reviewed changes

Added description enforcement linter rules for output, type and type …

896a220

…properties

John (johnlokerse) changed the title ~~feat: new Bicep linter rule use-parameter-descriptions~~ feat: 5 new linter rules to enforce descriptions on types, params, var, type properties and output Aug 7, 2026

John (johnlokerse) changed the title ~~feat: 5 new linter rules to enforce descriptions on types, params, var, type properties and output~~ feat: new linter rules to enforce descriptions on types, params, var, type properties and output Aug 7, 2026

John (johnlokerse) added 3 commits August 7, 2026 11:59

Exclude description when discriminator is present

ca6aff9

Cleanup

19df3d1

Cleanup bicep test files

d6b4023

Merge branch 'main' into johnlokerse/new-linter-rule-param-descriptions

1befd1a

John (johnlokerse) added 2 commits August 7, 2026 13:30

Fix merge conflict

f81b684

Fixed failing test

86d5222

John (johnlokerse) requested a review from Anthony Martin (anthony-c-martin) August 7, 2026 17:29

Renamed linter rules for parity

0c9d61b

Uh oh!

Conversation

John (johnlokerse) commented Jul 10, 2026 • edited by microsoft-github-policy-service Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Example Usage

Checklist

Microsoft Reviewers: Open in CodeFlow

Uh oh!

John (johnlokerse) commented Jul 10, 2026

Uh oh!

John (johnlokerse) commented Jul 23, 2026

Uh oh!

Stanislav Zhelyazkov (slavizh) commented Jul 23, 2026

Uh oh!

John (johnlokerse) commented Jul 24, 2026

Uh oh!

Anthony Martin (anthony-c-martin) commented Jul 24, 2026

Uh oh!

John (johnlokerse) commented Jul 27, 2026

Uh oh!

Anthony Martin (anthony-c-martin) commented Jul 27, 2026

Uh oh!

Stanislav Zhelyazkov (slavizh) commented Jul 28, 2026

Uh oh!

John (johnlokerse) commented Jul 28, 2026

Uh oh!

Stanislav Zhelyazkov (slavizh) commented Jul 28, 2026

Uh oh!

Anthony Martin (anthony-c-martin) commented Jul 29, 2026

Uh oh!

John (johnlokerse) commented Jul 29, 2026

Uh oh!

Anthony Martin (anthony-c-martin) commented Aug 1, 2026

Uh oh!

Xelu86 commented Aug 6, 2026

Uh oh!

Anthony Martin (anthony-c-martin) left a comment

Choose a reason for hiding this comment

Uh oh!

John (johnlokerse) commented Aug 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

John (johnlokerse) commented Aug 7, 2026

Uh oh!

Anthony Martin (anthony-c-martin) commented Aug 9, 2026

Uh oh!

Anthony Martin (anthony-c-martin) commented Aug 9, 2026

Uh oh!

John (johnlokerse) commented Aug 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

John (johnlokerse) commented Jul 10, 2026 •

edited by microsoft-github-policy-service Bot

Loading

John (johnlokerse) commented Aug 7, 2026 •

edited

Loading