From 45673392d2c97b9b5ae7edd148d6e01cfae3757f Mon Sep 17 00:00:00 2001 From: Anthony Watherston Date: Mon, 3 Feb 2025 11:03:11 +1100 Subject: [PATCH] Updates to schemas (#869) Co-authored-by: Anthony Watherston --- .../operational-scripts-documenting-policy.md | 15 +++++---- Schemas/policy-documentation-schema.json | 31 ++++++++++++------- Schemas/policy-set-definition-schema.json | 3 ++ 3 files changed, 32 insertions(+), 17 deletions(-) diff --git a/Docs/operational-scripts-documenting-policy.md b/Docs/operational-scripts-documenting-policy.md index d6eaadad..f7b40d5e 100644 --- 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 index 5853c9d3..2552a095 100644 --- 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 index a962653b..36d0e876 100644 --- 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" },