(DOCS) Define decomposed schemas

docs/reference/schemas/config/document.md

@@ -0,0 +1,130 @@
+# DSC Configuration document schema reference
+
+## Synopsis
+
+The YAML or JSON file that defines a DSC Configuration.
+
+## Metadata
+
+```yaml
+Schema Dialect : https://json-schema.org/draft/2020-12/schema
+Schema ID      : https://github.com/raw/PowerShell/DSC/main/schemas/2023/08/config/document.json
+Type           : object
+```
+
+## Description
+
+DSC Configurations enable users to define state by combining different DSC Resources. A
+configuration document uses parameters and variables to pass to a set of one or more resources that
+define a desired state.
+
+A configuration document can be defined as either YAML or JSON. For ease of authoring, Microsoft
+recommends drafting configuration documents in YAML.
+
+For DSC's authoring tools to recognize a file as a DSC Configuration document, the filename must
+end with `.dsc.config.json` or `.dsc.config.yaml`.
+
+For more information, see [DSC Configurations overview][01]
+
+The rest of this document describes the schema DSC uses to validation configuration documents.
+
+## Examples
+
+<!-- To-Do -->
+
+## Required Properties
+
+Every configuration document must include these properties:
+
+- [$schema]
+- [resources]
+
+## Properties
+
+### $schema
+
+The `$schema` property indicates the canonical URI for the version of this schema that the document
+adheres to. DSC uses this property when validating the configuration document before any
+configuration operations.
+
+```yaml
+Type:     string
+Required: true
+Format:   URI
+Valid Values:
+  - https://github.com/raw/PowerShell/DSC/main/schemas/2023/08/config/document.json
+```
+
+### metadata
+
+The `metadata` property defines a set of key-value pairs as annotations for the configuration. DSC
+doesn't validate the metadata. A configuration can include any arbitrary information in this
+property.
+
+```yaml
+Type:     object
+Required: false
+```
+
+### parameters
+
+The `parameters` property defines a set of runtime options for the configuration. Each parameter is
+defined as key-value pair. The key for each pair defines the name of the parameter. The value for
+each pair must be an object that defines the `type` keyword to indicate how DSC should process the
+parameter.
+
+Parameters may be overridden at run-time, enabling re-use of the same configuration document for
+different contexts.
+
+For more information about defining parameters in a configuration, see
+[DSC Configuration document parameter schema][02]. For more information about using parameters in a
+configuration, see [DSC Configuration parameters][03]
+
+```yaml
+Type:                  object
+Required:              false
+Valid Property Schema: https://github.com/raw/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json
+```
+
+### variables
+
+The `variables` property defines a set of reusable values for the resources in the document as
+key-value pairs. The key for each pair defines the name of the variable. Resources that reference
+the variable by name can access the variable's value.
+
+This can help reduce the amount of copied values and options for resources in the configuration,
+which makes the document easier to read and maintain. Unlike parameters, variables can only be
+defined in the configuration and can't be overridden at run-time.
+
+For more information about using variables in a configuration, see
+[DSC Configuration variables][04].
+
+```yaml
+Type:     object
+Required: false
+```
+
+### resources
+
+The `resources` property defines a list of DSC Resource instances that the configuration manages.
+Every instance in the list must be unique, but instances may share the same DSC Resource type.
+
+For more information about defining a valid resource instance in a configuration, see
+[DSC Configuration document resource schema][05]. For more information about how DSC uses resources
+in a configuration, see [DSC Configuration resources][06] and
+[DSC Configuration resource groups][07].
+
+```yaml
+Type:               array
+Required:           true
+Minimum Item Count: 1
+Valid Item Schema:  https://github.com/raw/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json
+```
+
+[01]: ../../../configurations/overview.md
+[02]: parameter.md
+[03]: ../../../configurations/parameters.md
+[04]: ../../../configurations/variables.md
+[05]: resource.md
+[06]: ../../../configurations/resources.md
+[07]: ../../../configurations/resource-groups.md

docs/reference/schemas/config/parameter.md

@@ -0,0 +1,185 @@
+# DSC Configuration document parameter schema
+
+## Synopsis
+
+Defines runtime options for a configuration.
+
+## Metadata
+
+```yaml
+Schema Dialect : https://json-schema.org/draft/2020-12/schema
+Schema ID      : https://github.com/raw/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json
+Type           : object
+```
+
+## Description
+
+DSC Configuration documents can include parameters, which users can override at runtime. Parameters
+enable separating secrets from configuration definitions and enable users to write configurations
+that can apply to multiple contexts.
+
+Parameters are defined as key-value pairs in the `parameters` property of a configuration document.
+The key is the parameter's name, which is used to reference the parameter in the [resources][01]
+property of the configuration document. The value is an object that defines the parameter.
+
+Every parameter defines its data type. Parameters may also define a default value, validation
+checks, a description of their purpose, and arbitrary metadata.
+
+## Required Properties
+
+- [type](#type)
+
+## Properties
+
+### description
+
+Parameters may define a short explanation of their purpose and usage with the `description`
+property. To define a longer explanation in YAML, use the folded block syntax or literal block
+syntax.
+
+```yaml
+Type:     string
+Required: false
+```
+
+### metadata
+
+The `metadata` property defines a set of key-value pairs as annotations for the parameter. DSC
+doesn't validate the metadata. A parameter can include any arbitrary information in this property.
+
+```yaml
+Type:     object
+Required: false
+```
+
+### type
+
+Every parameter must define the data type that it expects as the `type` property. DSC validates the
+data type for every passed parameter before executing a configuration operation.
+
+The `secure*` data types indicate that DSC and integrating tools shouldn't log or record the
+values. If a secure data type parameter is used for a resource instance property that doesn't
+expect a secure value, the resource may still log or record the value. If the resource has
+independent logging or recording that isn't handled by DSC, the value may be stored insecurely.
+
+Use secure strings for passwords and secrets.
+
+For more information about data types, see
+[DSC configuration parameter data type schema reference][02].
+
+```yaml
+Type:     string
+Required: true
+Valid Values:
+  - string
+  - securestring
+  - int
+  - bool
+  - object
+  - secureobject
+  - array
+```
+
+### defaultValue
+
+Parameters may define a default value with the `defaultValue` property. If the parameter isn't
+passed at runtime, DSC uses the default value for the parameter. If the parameter isn't passed at
+runtime and no default value is defined, DSC raises an error. The value must be valid for the
+parameter's `type`.
+
+```yaml
+Required: false
+Valid JSON Types:
+  - string
+  - integer
+  - object
+  - array
+  - boolean
+```
+
+### allowedValues
+
+Parameters may limit the set of valid values for the parameter by defining the `allowedValues`
+property. DSC validates parameters passed at runtime and defined as `defaultValue` against this
+list of values. If any of the values is invalid, DSC raises an error.
+
+This property is always an array. If this property is defined, it must include at least one item in
+the list of values.
+
+```yaml
+Type:     array
+Required: false
+Valid Item JSON Types:
+  - string
+  - integer
+  - object
+  - array
+  - boolean
+```
+
+### minLength
+
+The `minLength` property defines a validation option for array and string parameters. The length of
+a string is its character count. The length of an array is its item count.
+
+If the default value or runtime value for the parameter is shorter than this property, DSC raises
+an error. If this property is defined for parameters whose `type` isn't `array`, `string`, or
+`securestring`, DSC raises an error.
+
+If this property is defined with the `maxLength` property, this property must be less than
+`maxLength`. If it isn't, DSC raises an error.
+
+```yaml
+Type:          int
+Required:      false
+Minimum Value: 0
+```
+
+### maxLength
+
+The `maxLength` property defines a validation option for array and string parameters. The length of
+a string is its character count. The length of an array is its item count.
+
+If the default value or runtime value for the parameter is longer than this property, DSC raises an
+error. If this property is defined for parameters whose `type` isn't `array`, `string`, or
+`securestring`, DSC raises an error.
+
+If this property is defined with the `minLength` property, this property must be greater than
+`minLength`. If it isn't, DSC raises an error.
+
+```yaml
+Type:          int
+Required:      false
+Minimum Value: 0
+```
+
+### minValue
+
+The `minValue` property defines a validation option for integer parameters. If the default value or
+runtime value for the parameter is less than this property, DSC raises an error. If this property
+is defined for parameters whose `type` isn't `int`, DSC raises an error.
+
+If this property is defined with the `maxValue` property, this property must be less than
+`maxValue`. If it isn't, DSC raises an error.
+
+```yaml
+Type:     int
+Required: false
+```
+
+### maxValue
+
+The `maxValue` property defines a validation option for integer parameters. If the default value or
+runtime value for the parameter is greater than this property, DSC raises an error. If this
+property is defined for parameters whose `type` isn't `int`, DSC raises an error.
+
+If this property is defined with the `minValue` property, this property must be greater than
+`minValue`. If it isn't, DSC raises an error.
+
+```yaml
+Type:     int
+Required: false
+```
+
+[01]: resources.md
+[02]: ../definitions/parameters/dataTypes.md