(PowerShellGH-224) Update docs for 2023/10

michaeltlombardi · Oct 20, 2023 · d9d355b · d9d355b
1 parent 1711c12
commit d9d355b
Show file tree

Hide file tree

Showing 28 changed files with 108 additions and 49 deletions.
diff --git a/docs/reference/cli/config/get.md b/docs/reference/cli/config/get.md
@@ -34,12 +34,12 @@ document saved as `example.dsc.config.yaml`.
 
 ```yaml
 # example.dsc.config.yaml
-$schema: https://schemas.microsoft.com/dsc/2023/03/configuration.schema.json
+$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json
 resources:
 - name: Windows only
   type: DSC/AssertionGroup
   properties:
-    $schema: https://schemas.microsoft.com/dsc/2023/03/configuration.schema.json
+    $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json
     resources:
     - name: os
       type: Microsoft/OSInfo

diff --git a/docs/reference/cli/config/set.md b/docs/reference/cli/config/set.md
@@ -35,12 +35,12 @@ The command inspects the resource instances defined in the configuration documen
 
 ```yaml
 # example.dsc.config.yaml
-$schema: https://schemas.microsoft.com/dsc/2023/03/configuration.schema.json
+$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json
 resources:
 - name: Windows only
   type: DSC/AssertionGroup
   properties:
-    $schema: https://schemas.microsoft.com/dsc/2023/03/configuration.schema.json
+    $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json
     resources:
     - name: os
       type: Microsoft/OSInfo

diff --git a/docs/reference/cli/config/test.md b/docs/reference/cli/config/test.md
@@ -34,12 +34,12 @@ resource instances defined in the configuration document saved as `example.dsc.c
 
 ```yaml
 # example.dsc.config.yaml
-$schema: https://schemas.microsoft.com/dsc/2023/03/configuration.schema.json
+$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json
 resources:
 - name: Windows only
   type: DSC/AssertionGroup
   properties:
-    $schema: https://schemas.microsoft.com/dsc/2023/03/configuration.schema.json
+    $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json
     resources:
     - name: os
       type: Microsoft/OSInfo

diff --git a/docs/reference/schemas/config/document.md b/docs/reference/schemas/config/document.md
@@ -15,7 +15,7 @@ The YAML or JSON file that defines a DSC Configuration.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json
 Type:          object
 ```
 
@@ -50,16 +50,46 @@ Every configuration document must include these properties:
 
 ### $schema
 
-The `$schema` property indicates the canonical URI for the version of this schema that the document
+The `$schema` property indicates the canonical URL for the version of this schema that the document
 adheres to. DSC uses this property when validating the configuration document before any
 configuration operations.
 
+For every version of the schema, there are three valid urls:
+
+- `.../config/document.json`
+
+  The URL to the canonical non-bundled schema. When it's used for validation, the validating client
+  needs to retrieve this schema and every schema it references.
+
+- `.../bundled/config/document.json`
+
+  The URL to the bundled schema. When it's used for validation, the validating client only needs to
+  retrieve this schema.
+
+  This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can still
+  validate the document when it uses this schema, other tools may error or behave in unexpected
+  ways.
+
+- `.../bundled/config/document.vscode.json`
+
+  The URL to the enhanced authoring schema. This schema is much larger than the other schemas, as
+  it includes additional definitions that provide contextual help and snippets that the others
+  don't include.
+
+  This schema uses keywords that are only recognized by VS Code. While DSC can still validate the
+  document when it uses this schema, other tools may error or behave in unexpected ways.
+
 ```yaml
 Type:        string
 Required:    true
 Format:      URI
 ValidValues: [
+               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json
+               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.json
+               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.vscode.json
                https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
+               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.json
+               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/config/document.vscode.json
              ]
 ```
 
@@ -93,7 +123,7 @@ For more information about defining parameters in a configuration, see
 ```yaml
 Type:                object
 Required:            false
-ValidPropertySchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json
+ValidPropertySchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.parameter.json
 ```
 
 ### variables
@@ -129,7 +159,7 @@ For more information about defining a valid resource instance in a configuration
 Type:             array
 Required:         true
 MinimumItemCount: 1
-ValidItemSchema:  https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json
+ValidItemSchema:  https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.resource.json
 ```
 
 <!-- [01]: ../../../configurations/overview.md -->

diff --git a/docs/reference/schemas/config/parameter.md b/docs/reference/schemas/config/parameter.md
@@ -15,7 +15,7 @@ Defines runtime options for a configuration.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.parameter.json
 Type:          object
 ```
 

diff --git a/docs/reference/schemas/config/resource.md b/docs/reference/schemas/config/resource.md
@@ -15,7 +15,7 @@ Defines a DSC Resource instance in a configuration document.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.resource.json
 Type:          object
 ```
 

diff --git a/docs/reference/schemas/definitions/message.md b/docs/reference/schemas/definitions/message.md
@@ -15,7 +15,7 @@ A message emitted by a DSC Resource with associated metadata.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/message.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/message.json
 Type:          object
 ```
 

diff --git a/docs/reference/schemas/definitions/parameters/dataTypes.md b/docs/reference/schemas/definitions/parameters/dataTypes.md
@@ -15,7 +15,7 @@ Defines valid data types for a DSC configuration parameter
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/parameters/dataTypes.json
 Type:          string
 ValidValues:   [array, bool, int, object, string, secureobject, securestring]
 ```

diff --git a/docs/reference/schemas/definitions/resourceType.md b/docs/reference/schemas/definitions/resourceType.md
@@ -15,7 +15,7 @@ Identifies a DSC Resource.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json
 Type:          string
 Pattern:       ^\w+(\.\w+){0,2}\/\w+$
 ```

diff --git a/docs/reference/schemas/outputs/config/get.md b/docs/reference/schemas/outputs/config/get.md
@@ -15,7 +15,7 @@ The result output from the `dsc config get` command.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/get.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/config/get.json
 Type:          object
 ```
 

diff --git a/docs/reference/schemas/outputs/config/set.md b/docs/reference/schemas/outputs/config/set.md
@@ -15,7 +15,7 @@ The result output from the `dsc config set` command.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/set.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/config/set.json
 Type:          object
 ```
 

diff --git a/docs/reference/schemas/outputs/config/test.md b/docs/reference/schemas/outputs/config/test.md
@@ -15,7 +15,7 @@ The result output from the `dsc config test` command.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/test.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/config/test.json
 Type:          object
 ```
 

diff --git a/docs/reference/schemas/outputs/resource/get.md b/docs/reference/schemas/outputs/resource/get.md
@@ -15,7 +15,7 @@ The result output from the `dsc resource get` command.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/get.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.json
 Type:          object
 ```
 

diff --git a/docs/reference/schemas/outputs/resource/list.md b/docs/reference/schemas/outputs/resource/list.md
@@ -15,7 +15,7 @@ The result output from the `dsc resource list` command.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/list.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/list.json
 Type:          object
 ```
 

diff --git a/docs/reference/schemas/outputs/resource/set.md b/docs/reference/schemas/outputs/resource/set.md
@@ -15,7 +15,7 @@ The result output from the `dsc resource set` command.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/set.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.json
 Type:          object
 ```
 

diff --git a/docs/reference/schemas/outputs/resource/test.md b/docs/reference/schemas/outputs/resource/test.md
@@ -15,7 +15,7 @@ The result output from the `dsc resource test` command.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/test.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.json
 Type:          object
 ```
 

diff --git a/docs/reference/schemas/resource/manifest/export.md b/docs/reference/schemas/resource/manifest/export.md
@@ -15,7 +15,7 @@ Defines how to retrieve the current state of every instance for a DSC Resource.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.export.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.export.json
 Type:          object
 ```
 

diff --git a/docs/reference/schemas/resource/manifest/get.md b/docs/reference/schemas/resource/manifest/get.md
@@ -15,7 +15,7 @@ Defines how to retrieve a DSC Resource instance.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.get.json
 Type:          object
 ```
 

diff --git a/docs/reference/schemas/resource/manifest/provider.md b/docs/reference/schemas/resource/manifest/provider.md
@@ -15,7 +15,7 @@ Defines a DSC Resource as a DSC Resource Provider.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.provider.json
 Type:          object
 ```
 

diff --git a/docs/reference/schemas/resource/manifest/root.md b/docs/reference/schemas/resource/manifest/root.md
@@ -15,7 +15,7 @@ The JSON file that defines a command-based DSC Resource.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json
 Type:          object
 ```
 
@@ -46,12 +46,42 @@ The `$schema` property indicates the canonical URI of this schema that the manif
 against. This property is mandatory. DSC uses this value to validate the manifest against the
 correct JSON schema.
 
+For every version of the schema, there are three valid urls:
+
+- `.../resource/manifest.json`
+
+  The URL to the canonical non-bundled schema. When it's used for validation, the validating client
+  needs to retrieve this schema and every schema it references.
+
+- `.../bundled/resource/manifest.json`
+
+  The URL to the bundled schema. When it's used for validation, the validating client only needs to
+  retrieve this schema.
+
+  This schema uses the bundling model introduced for JSON Schema 2020-12. While DSC can still
+  validate the document when it uses this schema, other tools may error or behave in unexpected
+  ways.
+
+- `.../bundled/resource/manifest.vscode.json`
+
+  The URL to the enhanced authoring schema. This schema is much larger than the other schemas, as
+  it includes additional definitions that provide contextual help and snippets that the others
+  don't include.
+
+  This schema uses keywords that are only recognized by VS Code. While DSC can still validate the
+  document when it uses this schema, other tools may error or behave in unexpected ways.
+
 ```yaml
 Type:        string
 Required:    true
 Format:      URI
 ValidValues: [
+               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json
+               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.json
+               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.vscode.json
+               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json
                https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.json
+               https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/bundled/resource/manifest.vscode.json
              ]
 ```
 

diff --git a/docs/reference/schemas/resource/manifest/schema/embedded.md b/docs/reference/schemas/resource/manifest/schema/embedded.md
@@ -15,7 +15,7 @@ Defines a JSON Schema that validates a DSC Resource instance.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json#/properties/embedded
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.schema.json#/properties/embedded
 Type:          object
 ```
 
@@ -91,24 +91,23 @@ processing. The well-known properties always start with an underscore (`_`) and
 use these properties may not override or extend them. If a resource specifies a well-known property
 in the embedded schema, the schema _must_ define the property as a reference.
 
-- [_ensure](#_ensure)
+- [_exist](#_exist)
 - [_inDesiredState](#_indesiredstate)
 - [_purge](#_purge)
 - [_rebootRequested](#_rebootrequested)
 
-#### _ensure
+#### _exist
 
-The `_ensure` property indicates that the resource can enforce whether instances exist using the
-shared present and absent semantics. If a resource must distinguish between states beyond whether
-an instance is present or absent, the resource should define its own `ensure` property without the
-leading underscore. This property provides shared semantics for DSC Resources and integrating
-tools, but doesn't enable any additional built-in processing with DSC.
+The `_exist` property indicates that the resource can enforce whether instances exist, handling
+whether an instance should be added, updated, or removed during a set operation. This property
+provides shared semantics for DSC Resources and integrating tools, but doesn't enable any
+additional built-in processing with DSC.
 
 If defined, this property must be a reference to the schema for the well-known property:
 
 ```json
-"_ensure": {
-  "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json"
+"_exist": {
+  "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/exist.json"
 }
 ```
 
@@ -124,7 +123,7 @@ If defined, this property must be a reference to the schema for the well-known p
 
 ```json
 "_inDesiredState": {
-  "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json"
+  "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/inDesiredState.json"
 }
 ```
 
@@ -140,7 +139,7 @@ If defined, this property must be a reference to the schema for the well-known p
 
 ```json
 "_inDesiredState": {
-  "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json"
+  "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/purge.json"
 }
 ```
 
@@ -156,7 +155,7 @@ If defined, this property must be a reference to the schema for the well-known p
 
 ```json
 "_rebootRequested": {
-  "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json"
+  "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/rebootRequested.json"
 }
 ```
 

diff --git a/docs/reference/schemas/resource/manifest/schema/property.md b/docs/reference/schemas/resource/manifest/schema/property.md
@@ -15,7 +15,7 @@ Defines how to retrieve the JSON Schema that validates a DSC Resource instance.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.schema.json
 Type:          object
 ```
 

diff --git a/docs/reference/schemas/resource/manifest/set.md b/docs/reference/schemas/resource/manifest/set.md
@@ -15,7 +15,7 @@ Defines how to enforce state for a DSC Resource instance.
 
 ```yaml
 SchemaDialect: https://json-schema.org/draft/2020-12/schema
-SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json
+SchemaID:      https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.set.json
 Type:          object
 ```