Updates to schemas (#869)

Co-authored-by: Anthony Watherston <[email protected]>
Azure · Feb 3, 2025 · 4567339 · 4567339
1 parent c93000e
commit 4567339
Show file tree

Hide file tree

Showing 3 changed files with 32 additions and 17 deletions.
diff --git a/Docs/operational-scripts-documenting-policy.md b/Docs/operational-scripts-documenting-policy.md
@@ -21,15 +21,17 @@ To utilize the schema add a ```$schema``` tag to the JSON file.
 
 This schema is new in v7.4.x and may not be complete. Please let us know if we missed anything.
 
-## Example Documentation Specification File using 'documentAllAssignments'
+## Examples
 
-Each file must contain one or both documentation topics. This example file in the StarterKit has both topics. The element `pacEnvironment` references the Policy as Code environment in `global-settings.jsonc` defining the tenant and root scope where the custom Policies and Policy Sets are deployed.
+The following are 2 examples which are both valid. Both are presented and should be used based on requirements and preference.
 
-* [`documentAssignments`](#assignment-documentation)
-* [`documentPolicySets`](#policy-set-documentation)
+### Document All Assignments
+
+Each file must contain one or both documentation topics, [`documentAssignments`](#assignment-documentation) and/or [`documentPolicySets`](#policy-set-documentation). This example file in the StarterKit has both topics. The element `pacEnvironment` references the Policy as Code environment in `global-settings.jsonc` defining the tenant and root scope where the custom Policies and Policy Sets are deployed.
 
 ```json
 {
+    "$schema": "https://raw.githubusercontent.com/Azure/enterprise-azure-policy-as-code/main/Schemas/policy-documentation-schema.json",
     "documentAssignments": {
         "documentAllAssignments": [
             {
@@ -104,15 +106,16 @@ Each file must contain one or both documentation topics. This example file in th
 }
 ```
 
-## Example Documentation Specification File using 'environmentCategories'
+### Document chosen 'Environment Categories'
 
-Each file must contain one or both documentation topics. This example file in the StarterKit has both topics. The element `pacEnvironment` references the Policy as Code environment in `global-settings.jsonc` defining the tenant and root scope where the custom Policies and Policy Sets are deployed.
+Each file must contain one or both documentation topics, [`documentAssignments`](#assignment-documentation) and/or [`documentPolicySets`](#policy-set-documentation). This example file in the StarterKit has both topics. The element `pacEnvironment` references the Policy as Code environment in `global-settings.jsonc` defining the tenant and root scope where the custom Policies and Policy Sets are deployed.
 
 * [`documentAssignments`](#assignment-documentation)
 * [`documentPolicySets`](#policy-set-documentation)
 
 ```json
 {
+    "$schema": "https://raw.githubusercontent.com/Azure/enterprise-azure-policy-as-code/main/Schemas/policy-documentation-schema.json",
     "documentAssignments": {
         "environmentCategories": [
             {

diff --git a/Schemas/policy-documentation-schema.json b/Schemas/policy-documentation-schema.json
@@ -7,7 +7,7 @@
             "properties": {
                 "documentAllAssignments": {
                     "type": "array",
-                    "maxItems": 1,
+                    "minItems": 1,
                     "items": {
                         "type": "object",
                         "properties": {
@@ -99,12 +99,6 @@
                 }
             },
             "anyOf": [
-                {
-                    "required": [
-                        "environmentCategories",
-                        "documentationSpecifications"
-                    ]
-                },
                 {
                     "required": [
                         "documentAllAssignments",
@@ -138,12 +132,27 @@
                                     "type": "string"
                                 },
                                 "id": {
-                                    "type": "string"
+                                    "type": "string",
+                                    "description": "The name of the policy set. This is used for built-in policy sets."
+                                },
+                                "name": {
+                                    "type": "string",
+                                    "description": "The name of the policy set. This is used for custom policy sets."
                                 }
                             },
-                            "required": [
-                                "shortName",
-                                "id"
+                            "oneOf": [
+                                {
+                                    "required": [
+                                        "shortName",
+                                        "id"
+                                    ]
+                                },
+                                {
+                                    "required": [
+                                        "shortName",
+                                        "name"
+                                    ]
+                                }
                             ]
                         }
                     },

diff --git a/Schemas/policy-set-definition-schema.json b/Schemas/policy-set-definition-schema.json
@@ -14,6 +14,9 @@
                 "displayName": {
                     "type": "string"
                 },
+                "policyType": {
+                    "type": "string"
+                },
                 "description": {
                     "type": "string"
                 },