From d57c82456483531f04fd09beb343afb65aa3ad4a Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Thu, 29 Jun 2023 16:48:44 -0500 Subject: [PATCH 01/11] (DOCS) Define decomposed schemas This change defines a set of JSON Schema documents for DSC. Instead of a few monolithic schema documents, this change defines the schemas as smaller, more manageable documents that can be bundled as needed. These schemas are hand-authored and more specific than the schemas generated with the `dsc schema` command. The schemas included here are implemented with loose validation, but we can support strict validation side-by-side. The schemas are organized into subfolders: - In the `bundled` folder, the schema documents include a synthetic example of the bundling process. For this change, they were generated by hand, but they could be composed with tooling instead. - In the `config` folder, the schema documents validate a DSC Configuration document. - In the `definitions` folder, the schema documents represent reused definitions for validation and/or documentation. The `title` and `description` keywords for instances in a JSON Schema are used by authoring tools to provide contextual documentation. - In the `outputs` folder, the schema documents represent the output users and integrating tools should expect from calling `dsc`. Tools may use these definitions to generate their own structs in their application code to more readily and accurately handle output from DSC. - In the `resource` folder, the `manifest*` schema documents validate a command-based DSC Resource manifest. - In the `resource/properties` folder, the schema documents represent standard DSC Resource properties that have well-defined usage. The schema URL and the ID names for the schemas is best-effort but should not be treated as canonical without further discussion. The documents include comments indicating ambiguities or questions that they raise. --- docs/schemas/bundled/config.document.yaml | 224 ++++++++++++ docs/schemas/bundled/resource.manifest.yaml | 320 ++++++++++++++++++ docs/schemas/config/document.parameters.yaml | 105 ++++++ docs/schemas/config/document.resources.yaml | 36 ++ docs/schemas/config/document.yaml | 43 +++ docs/schemas/definitions/commandArgs.yaml | 10 + .../definitions/commandExecutable.yaml | 8 + docs/schemas/definitions/dataType.yaml | 16 + docs/schemas/definitions/hadErrors.yaml | 8 + docs/schemas/definitions/inputKind.yaml | 13 + docs/schemas/definitions/instanceName.yaml | 9 + docs/schemas/definitions/message.yaml | 38 +++ docs/schemas/definitions/messages.yaml | 12 + docs/schemas/definitions/resourceType.yaml | 17 + docs/schemas/definitions/returnKind.yaml | 16 + docs/schemas/definitions/semver.yaml | 31 ++ docs/schemas/outputs/config/get.yaml | 38 +++ docs/schemas/outputs/config/set.yaml | 38 +++ docs/schemas/outputs/config/test.yaml | 38 +++ docs/schemas/outputs/config/validate.yaml | 13 + docs/schemas/outputs/resource/get.yaml | 20 ++ docs/schemas/outputs/resource/list.yaml | 89 +++++ docs/schemas/outputs/resource/schema.yaml | 10 + docs/schemas/outputs/resource/set.yaml | 40 +++ docs/schemas/outputs/resource/test.yaml | 39 +++ docs/schemas/outputs/schema.yaml | 10 + docs/schemas/resource/manifest.get.yaml | 27 ++ docs/schemas/resource/manifest.provider.yaml | 49 +++ docs/schemas/resource/manifest.schema.yaml | 79 +++++ docs/schemas/resource/manifest.set.yaml | 43 +++ docs/schemas/resource/manifest.test.yaml | 34 ++ docs/schemas/resource/manifest.validate.yaml | 23 ++ docs/schemas/resource/manifest.yaml | 83 +++++ docs/schemas/resource/properties/ensure.yaml | 12 + .../resource/properties/inDesiredState.yaml | 13 + docs/schemas/resource/properties/purge.yaml | 14 + .../resource/properties/rebootRequested.yaml | 12 + 37 files changed, 1630 insertions(+) create mode 100644 docs/schemas/bundled/config.document.yaml create mode 100644 docs/schemas/bundled/resource.manifest.yaml create mode 100644 docs/schemas/config/document.parameters.yaml create mode 100644 docs/schemas/config/document.resources.yaml create mode 100644 docs/schemas/config/document.yaml create mode 100644 docs/schemas/definitions/commandArgs.yaml create mode 100644 docs/schemas/definitions/commandExecutable.yaml create mode 100644 docs/schemas/definitions/dataType.yaml create mode 100644 docs/schemas/definitions/hadErrors.yaml create mode 100644 docs/schemas/definitions/inputKind.yaml create mode 100644 docs/schemas/definitions/instanceName.yaml create mode 100644 docs/schemas/definitions/message.yaml create mode 100644 docs/schemas/definitions/messages.yaml create mode 100644 docs/schemas/definitions/resourceType.yaml create mode 100644 docs/schemas/definitions/returnKind.yaml create mode 100644 docs/schemas/definitions/semver.yaml create mode 100644 docs/schemas/outputs/config/get.yaml create mode 100644 docs/schemas/outputs/config/set.yaml create mode 100644 docs/schemas/outputs/config/test.yaml create mode 100644 docs/schemas/outputs/config/validate.yaml create mode 100644 docs/schemas/outputs/resource/get.yaml create mode 100644 docs/schemas/outputs/resource/list.yaml create mode 100644 docs/schemas/outputs/resource/schema.yaml create mode 100644 docs/schemas/outputs/resource/set.yaml create mode 100644 docs/schemas/outputs/resource/test.yaml create mode 100644 docs/schemas/outputs/schema.yaml create mode 100644 docs/schemas/resource/manifest.get.yaml create mode 100644 docs/schemas/resource/manifest.provider.yaml create mode 100644 docs/schemas/resource/manifest.schema.yaml create mode 100644 docs/schemas/resource/manifest.set.yaml create mode 100644 docs/schemas/resource/manifest.test.yaml create mode 100644 docs/schemas/resource/manifest.validate.yaml create mode 100644 docs/schemas/resource/manifest.yaml create mode 100644 docs/schemas/resource/properties/ensure.yaml create mode 100644 docs/schemas/resource/properties/inDesiredState.yaml create mode 100644 docs/schemas/resource/properties/purge.yaml create mode 100644 docs/schemas/resource/properties/rebootRequested.yaml diff --git a/docs/schemas/bundled/config.document.yaml b/docs/schemas/bundled/config.document.yaml new file mode 100644 index 000000000..56a4d051b --- /dev/null +++ b/docs/schemas/bundled/config.document.yaml @@ -0,0 +1,224 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/bundled/config.document.yaml + +title: DSC Configuration Document schema +description: >- + Describes a valid DSC Configuration Document. + +type: object +required: + - $schema + - resources +properties: + $schema: + title: Schema + description: >- + This property must be the canonical URL of the DSC Configuration Document + schema that the document is implemented for. + type: string + format: uri + enum: + - https://schemas.microsoft.com/dsc/2023/07/config/document.yaml + + parameters: + $ref: /dsc/2023/07/config/document.parameters.yaml + + variables: + title: Configuration variables + description: >- + Defines a set of reusable values for the configuration document. The + names of this value's properties are the strings used to reference a + variable's value. + type: object + + resources: + $ref: /dsc/2023/07/config/document.resources.yaml + + metadata: + title: Configuration metadata + description: >- + Defines a set of key-value pairs for the configuration. This metadata + isn't validated. + type: object + +$defs: + https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.yaml + title: DSC Configuration document parameters + description: >- + Defines runtime options for the configuration. Users and integrating tools + can override use the defined parameters to pass alternate values to the + configuration. + type: object + patternProperties: + ".": + title: Parameter + description: >- + Defines a runtime option for a DSC Configuration Document. + type: object + required: + - type + properties: + type: + $ref: /dsc/2023/07/definitions/dataType.yaml + defaultValue: + title: Default value + description: >- + Defines the default value for the parameter. + $ref: "#/$defs/ValidValueTypes" + allowedValues: + title: Allowed values + description: >- + Defines a list of valid values for the parameter. If the + parameter is defined with any other values, it's invalid. + type: array + items: + $ref: "#/$defs/ValidValueTypes" + description: + title: Parameter description + description: >- + Defines a synopsis for the parameter explaining its purpose. + type: string + metadata: + title: Parameter metadata + description: >- + Defines a set of key-value pairs for the parameter. This metadata + isn't validated. + type: object + allOf: + - if: + properties: + type: + const: int + then: + $ref: "#/$defs/IntegerValidationProperties" + - if: + oneOf: + - properties: { type: { const: string } } + - properties: { type: { const: securestring } } + - properties: { type: { const: array } } + then: + $ref: "#/$defs/LengthValidationProperties" + $defs: + ValidValueTypes: + type: + - string + - integer + - object + - array + - boolean + IntegerValidationProperties: + properties: + minValue: + title: Minimum value + description: >- + The minimum valid value for an integer type. If defined with the + `maxValue` property, this value must be less than the value of + `maxValue`. + type: integer + minimum: 0 + maxValue: + title: Maximum value + description: >- + The maximum valid value for an integer type. If defined with the + `minValue` property, this value must be greater than the value of + `minValue`. + type: integer + minimum: 0 + LengthValidationProperties: + properties: + minLength: + title: Minimum length + description: >- + The minimum valid length for a `string`, `securestring`, or `array`. + If defined with the `maxLength` property, this value must be less + than the value of `maxLength`. + type: integer + minimum: 0 + maxLength: + title: Maximum length + description: >- + The maximum valid length for a `string`, `securestring`, or `array`. + If defined with the `minLength` property, this value must be less + than the value of `minLength`. + type: integer + minimum: 0 + + https://schemas.microsoft.com/dsc/2023/07/config/document.resources.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/config/document.resources.yaml + title: DSC Configuration document resources + description: >- + Defines a list of DSC Resource instances for the configuration to manage. + type: array + items: + title: DSC Resource instance + type: object + required: + - type + - name + properties: + type: + $ref: /dsc/2023/07/definitions/resourceType.yaml + name: + $ref: /dsc/2023/07/definitions/instanceName.yaml + dependsOn: + title: Instance depends on + description: >- + Defines a list of DSC Resource instances that DSC must successfully + process before processing this instance. Each value for this property + must be the value of another DSC Resource instance's `name` property. + type: array + items: + type: string + uniqueItems: true + properties: + title: Managed instance properties + description: >- + Defines the properties of the DSC Resource this instance manages. This + property's value must be an object. DSC validates the property's value + against the DSC Resource's schema. + type: object + + https://schemas.microsoft.com/dsc/2023/07/definitions/dataType.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/dataType.yaml + title: Data Type + description: >- + Defines the data type for the value. + type: string + enum: + - string + - securestring + - int + - bool + - object + - secureobject + - array + + https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.yaml + title: Instance name + description: >- + The short, human-readable name for a DSC Resource instance. Must be unique + within a DSC Configuration document. + type: string + + https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml + title: DSC Resource fully qualified type name + description: | + The namespaced name of the DSC Resource, using the syntax: + + [.][.]/ + + For example: + + - Microsoft.SqlServer/Database + - Microsoft.SqlServer.Database/User + type: string + pattern: ^\w+(\.\w+){0,2}\/\w+$ diff --git a/docs/schemas/bundled/resource.manifest.yaml b/docs/schemas/bundled/resource.manifest.yaml new file mode 100644 index 000000000..59705f227 --- /dev/null +++ b/docs/schemas/bundled/resource.manifest.yaml @@ -0,0 +1,320 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/bundled/resource.manifest.yaml + +title: Command-based DSC Resource Manifest +description: >- + Defines a valid command-based DSC Resource. + +type: object +required: + - manifestVersion + - type + - version + - get +properties: + manifestVersion: + title: Manifest Version + description: >- + The semver of the DSC Resource manifest schema to validate this manifest + with. + $ref: /dsc/2023/07/definitions/semver.yaml + enums: + - '1.0' + type: + $ref: /dsc/2023/07/definitions/resourceType.yaml + version: + title: Resource Semantic Version + description: >- + The semantic version (semver) of the DSC Resource. This version + identifies the DSC Resource, not the version of the application it + manages. + $ref: /dsc/2023/07/definitions/semver.yaml + description: + title: Resource Description + description: >- + A short synopsis of the DSC Resource's purpose. + # Should this include a maximum length or a pattern that forbids newlines? + type: string + tags: + title: Tags + description: >- + An array of short strings used to search for DSC Resources. + type: array + items: + type: string + pattern: ^\w+$ + get: + $ref: /dsc/2023/07/resource/manifest.get.yaml + set: + $ref: /dsc/2023/07/resource/manifest.set.yaml + test: + $ref: /dsc/2023/07/resource/manifest.test.yaml + validate: + $ref: /dsc/2023/07/resource/manifest.validate.yaml + provider: + # I'm not clear on how this works in practice + $ref: /dsc/2023/07/resource/manifest.provider.yaml + exitCodes: + # This setting in the root of the schema implies exit codes must have the + # same meaning across all executions. What about implementations that + # support multiple executables? Should exitCodes be a key that exists on + # command/method objects too? + title: Exit Codes + description: >- + This property defines a map of valid exit codes for the DSC Resource. + DSC always interprets exit code `0` as a successful operation and any + other exit code as an error. Use this property to indicate human-readable + semantic meanings for the DSC Resource's exit codes. + type: object + propertyNames: + pattern: "^[0-9]+$" + patternProperties: + "^[0-9]+$": + type: string + examples: + - exitCodes: + "0": Success + "1": Invalid parameter + "2": Invalid input + "3": Registry error + "4": JSON serialization failed + schema: + $ref: /dsc/2023/07/resource/manifest.schema.yaml + +$defs: + https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.yaml + title: Executable Command Arguments + description: >- + The list of arguments to pass to the command. + type: array + items: + type: string + + https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.yaml + title: Executable Command Name + description: >- + The name of the command to run. + type: string + + https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.yaml + title: Executable Command Input Type + description: >- + Defines how DSC should pass input to the command, either as arguments or + JSON over stdin. + type: string + enum: + - args + - stdin + default: args + + https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml + title: DSC Resource fully qualified type name + description: | + The namespaced name of the DSC Resource, using the syntax: + + [.][.]/ + + For example: + + - Microsoft.SqlServer/Database + - Microsoft.SqlServer.Database/User + type: string + pattern: ^\w+(\.\w+){0,2}\/\w+$ + + https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.yaml + title: Return Kind + type: string + enum: + - state + - stateAndDiff + default: state + + https://schemas.microsoft.com/dsc/2023/07/definitions/semver.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/semver.yaml + type: string + title: Semantic Version + description: >- + A valid semantic version (semver) string. For reference, see https://semver.org/ + pattern: >- + ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ + + https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.yaml + title: Get Method + description: >- + Defines how DSC must call the DSC Resource to get the current state of an + instance. + type: object + required: + - executable + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + input: + $ref: /dsc/2023/07/definitions/inputKind.yaml + + https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.yaml + title: Provider + description: >- + Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider + enables users to manage resources that don't have their own manifests with + DSC. + type: object + required: + - list + - config + properties: + list: + title: List Command + description: >- + Defines how DSC must call the DSC Resource Provider to list its supported + DSC Resources. + type: object + required: + - executable + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + config: + title: Expected Configuration + description: >- + Defines whether the provider expects to receive a full and unprocessed + configuration as a single JSON blob over stdin or a sequence of JSON + Lines for each child resource's configurations. + type: string + enum: + - full + - sequence + + https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.yaml + title: Instance Schema + description: >- + Defines how DSC must validate a JSON blob representing an instance of the + DSC Resource. + type: object + oneOf: + - required: [command] + - required: [embedded] + properties: + command: + title: Instance Schema Command + description: >- + Defines how DSC must call the DSC Resource to get the JSON Schema for + validating a JSON blob representing an instance of the DSC Resource. + type: object + required: + - executable + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + embedded: + title: Embedded Instance Schema + description: >- + Defines the JSON Schema DSC must use to validate a JSON blob + representing an instance of the DSC Resource. + type: object + minProperties: 1 + url: + title: Instance Schema URL + description: >- + Defines the URL to the DSC Resource's JSON schema for integrating tools. + type: string + format: uri + + https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.yaml + title: Set Method + description: >- + Defines how DSC must call the DSC Resource to set the desired state of + an instance and how to process the output from the DSC Resource. + type: object + required: + - executable + - input + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + input: + $ref: /dsc/2023/07/definitions/inputKind.yaml + preTest: + title: Resource Performs Pre-Test + description: >- + Defines whether the DSC Resource performs its own test to ensure + idempotency when calling the `set` command. Set this value to `true` + if the DSC Resource tests input before modifying system state. + type: boolean + default: false + return: + description: >- + Defines whether the command returns a JSON blob of the DSC Resource's + state after the set operation or the state and an array of the + properties the DSC Resource modified. + $ref: /dsc/2023/07/definitions/returnKind.yaml + + https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.yaml + title: Test Method + description: >- + Defines how DSC must call the DSC Resource to test if an instance is in + the desired state and how to process the output from the DSC Resource. + type: object + required: + - executable + - input + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + input: + $ref: /dsc/2023/07/definitions/inputKind.yaml + return: + title: Test Command Return Type + description: >- + Defines whether the command returns a JSON blob of the DSC Resource's current state or the + state and an array of the properties that are out of the desired state. + $ref: /dsc/2023/07/definitions/returnKind.yaml + + https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.yaml + title: Validate Method + description: >- + Defines how DSC must call the DSC Resource to validate the state of an + instance. This method is mandatory for DSC Group Resources. It's ignored for + all other DSC Resources. + type: object + required: + - executable + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml diff --git a/docs/schemas/config/document.parameters.yaml b/docs/schemas/config/document.parameters.yaml new file mode 100644 index 000000000..5027df48c --- /dev/null +++ b/docs/schemas/config/document.parameters.yaml @@ -0,0 +1,105 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.yaml + +title: DSC Configuration document parameters +description: >- + Defines runtime options for the configuration. Users and integrating tools + can override use the defined parameters to pass alternate values to the + configuration. +type: object + +patternProperties: + ".": + title: Parameter + description: >- + Defines a runtime option for a DSC Configuration Document. + type: object + required: + - type + properties: + type: + $ref: /dsc/2023/07/definitions/dataType.yaml + defaultValue: + title: Default value + description: >- + Defines the default value for the parameter. + $ref: "#/$defs/ValidValueTypes" + allowedValues: + title: Allowed values + description: >- + Defines a list of valid values for the parameter. If the + parameter is defined with any other values, it's invalid. + type: array + items: + $ref: "#/$defs/ValidValueTypes" + description: + title: Parameter description + description: >- + Defines a synopsis for the parameter explaining its purpose. + type: string + metadata: + title: Parameter metadata + description: >- + Defines a set of key-value pairs for the parameter. This metadata + isn't validated. + type: object + allOf: + - if: + properties: + type: + const: int + then: + $ref: "#/$defs/IntegerValidationProperties" + - if: + oneOf: + - properties: { type: { const: string } } + - properties: { type: { const: securestring } } + - properties: { type: { const: array } } + then: + $ref: "#/$defs/LengthValidationProperties" + +$defs: + ValidValueTypes: + type: + - string + - integer + - object + - array + - boolean + IntegerValidationProperties: + properties: + minValue: + title: Minimum value + description: >- + The minimum valid value for an integer type. If defined with the + `maxValue` property, this value must be less than the value of + `maxValue`. + type: integer + minimum: 0 + maxValue: + title: Maximum value + description: >- + The maximum valid value for an integer type. If defined with the + `minValue` property, this value must be greater than the value of + `minValue`. + type: integer + minimum: 0 + LengthValidationProperties: + properties: + minLength: + title: Minimum length + description: >- + The minimum valid length for a `string`, `securestring`, or `array`. + If defined with the `maxLength` property, this value must be less + than the value of `maxLength`. + type: integer + minimum: 0 + maxLength: + title: Maximum length + description: >- + The maximum valid length for a `string`, `securestring`, or `array`. + If defined with the `minLength` property, this value must be less + than the value of `minLength`. + type: integer + minimum: 0 \ No newline at end of file diff --git a/docs/schemas/config/document.resources.yaml b/docs/schemas/config/document.resources.yaml new file mode 100644 index 000000000..1af7f97a5 --- /dev/null +++ b/docs/schemas/config/document.resources.yaml @@ -0,0 +1,36 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/config/document.resources.yaml + +title: DSC Configuration document resources +description: >- + Defines a list of DSC Resource instances for the configuration to manage. +type: array +items: + title: DSC Resource instance + type: object + required: + - type + - name + properties: + type: + $ref: /dsc/2023/07/definitions/resourceType.yaml + name: + $ref: /dsc/2023/07/definitions/instanceName.yaml + dependsOn: + title: Instance depends on + description: >- + Defines a list of DSC Resource instances that DSC must successfully + process before processing this instance. Each value for this property + must be the value of another DSC Resource instance's `name` property. + type: array + items: + type: string + uniqueItems: true + properties: + title: Managed instance properties + description: >- + Defines the properties of the DSC Resource this instance manages. This + property's value must be an object. DSC validates the property's value + against the DSC Resource's schema. + type: object diff --git a/docs/schemas/config/document.yaml b/docs/schemas/config/document.yaml new file mode 100644 index 000000000..6d05ea3a7 --- /dev/null +++ b/docs/schemas/config/document.yaml @@ -0,0 +1,43 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/config/document.yaml + +title: DSC Configuration Document schema +description: >- + Describes a valid DSC Configuration Document. + +type: object +required: + - $schema + - resources +properties: + $schema: + title: Schema + description: >- + This property must be the canonical URL of the DSC Configuration Document + schema that the document is implemented for. + type: string + format: uri + enum: + - https://schemas.microsoft.com/dsc/2023/07/config/document.yaml + + parameters: + $ref: /dsc/2023/07/config/document.parameters.yaml + + variables: + title: Configuration variables + description: >- + Defines a set of reusable values for the configuration document. The + names of this value's properties are the strings used to reference a + variable's value. + type: object + + resources: + $ref: /dsc/2023/07/config/document.resources.yaml + + metadata: + title: Configuration metadata + description: >- + Defines a set of key-value pairs for the configuration. This metadata + isn't validated. + type: object diff --git a/docs/schemas/definitions/commandArgs.yaml b/docs/schemas/definitions/commandArgs.yaml new file mode 100644 index 000000000..4d8a6f170 --- /dev/null +++ b/docs/schemas/definitions/commandArgs.yaml @@ -0,0 +1,10 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.yaml + +title: Executable Command Arguments +description: >- + The list of arguments to pass to the command. +type: array +items: + type: string diff --git a/docs/schemas/definitions/commandExecutable.yaml b/docs/schemas/definitions/commandExecutable.yaml new file mode 100644 index 000000000..e6e1da717 --- /dev/null +++ b/docs/schemas/definitions/commandExecutable.yaml @@ -0,0 +1,8 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.yaml + +title: Executable Command Name +description: >- + The name of the command to run. +type: string diff --git a/docs/schemas/definitions/dataType.yaml b/docs/schemas/definitions/dataType.yaml new file mode 100644 index 000000000..4bf57f15d --- /dev/null +++ b/docs/schemas/definitions/dataType.yaml @@ -0,0 +1,16 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/definitions/dataType.yaml + +title: Data Type +description: >- + Defines the data type for the value. +type: string +enum: + - string + - securestring + - int + - bool + - object + - secureobject + - array diff --git a/docs/schemas/definitions/hadErrors.yaml b/docs/schemas/definitions/hadErrors.yaml new file mode 100644 index 000000000..02979d065 --- /dev/null +++ b/docs/schemas/definitions/hadErrors.yaml @@ -0,0 +1,8 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/definitions/hadErrors.yaml + +title: Had Errors +description: >- + Indicates whether any of the DSC Resources returned a non-zero exit code. +type: boolean \ No newline at end of file diff --git a/docs/schemas/definitions/inputKind.yaml b/docs/schemas/definitions/inputKind.yaml new file mode 100644 index 000000000..be7d7f6dd --- /dev/null +++ b/docs/schemas/definitions/inputKind.yaml @@ -0,0 +1,13 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.yaml + +title: Executable Command Input Type +description: >- + Defines how DSC should pass input to the command, either as arguments or + JSON over stdin. +type: string +enum: + - args + - stdin +default: args diff --git a/docs/schemas/definitions/instanceName.yaml b/docs/schemas/definitions/instanceName.yaml new file mode 100644 index 000000000..b99ec13a9 --- /dev/null +++ b/docs/schemas/definitions/instanceName.yaml @@ -0,0 +1,9 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.yaml + +title: Instance name +description: >- + The short, human-readable name for a DSC Resource instance. Must be unique + within a DSC Configuration document. +type: string diff --git a/docs/schemas/definitions/message.yaml b/docs/schemas/definitions/message.yaml new file mode 100644 index 000000000..ccb43e16d --- /dev/null +++ b/docs/schemas/definitions/message.yaml @@ -0,0 +1,38 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/definitions/message.yaml + +title: Message +description: >- + A message emitted by a DSC Resource with associated metadata. + +type: object +required: + - name + - type + - message + - level +properties: + name: + title: Message source instance name + description: >- + The short, human-readable name for the instance that emitted the message, + as defined in the DSC Configuration Document. + type: string + type: + $ref: /dsc/2023/07/definitions/resourceType.yaml + message: + title: Message content + description: >- + The actual content of the message as emitted by the DSC Resource. + type: string + minLength: 1 + level: + title: Message level + description: >- + Indicates the severity of the message. + type: string + enum: + - Error + - Warning + - Information diff --git a/docs/schemas/definitions/messages.yaml b/docs/schemas/definitions/messages.yaml new file mode 100644 index 000000000..7d14142a2 --- /dev/null +++ b/docs/schemas/definitions/messages.yaml @@ -0,0 +1,12 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/definitions/messages.yaml + +title: Messages +description: >- + A list of structured messages emitted by the DSC Resources during an + operation. + +type: array +items: + $ref: /dsc/2023/07/definitions/message.yaml diff --git a/docs/schemas/definitions/resourceType.yaml b/docs/schemas/definitions/resourceType.yaml new file mode 100644 index 000000000..930e5ab87 --- /dev/null +++ b/docs/schemas/definitions/resourceType.yaml @@ -0,0 +1,17 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml + +title: DSC Resource fully qualified type name +description: | + The namespaced name of the DSC Resource, using the syntax: + + [.][.]/ + + For example: + + - Microsoft.SqlServer/Database + - Microsoft.SqlServer.Database/User + +type: string +pattern: ^\w+(\.\w+){0,2}\/\w+$ diff --git a/docs/schemas/definitions/returnKind.yaml b/docs/schemas/definitions/returnKind.yaml new file mode 100644 index 000000000..98b5ca974 --- /dev/null +++ b/docs/schemas/definitions/returnKind.yaml @@ -0,0 +1,16 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.yaml + +title: Return Kind +type: string +enum: + - state + - stateAndDiff +default: state + +$comment: |- + While the enumeration for return kind is the same for the `set` and `test` + method, the way it changes the behavior of the command isn't. The description + keyword isn't included here because the respective schemas for those methods + document the behavior themselves. diff --git a/docs/schemas/definitions/semver.yaml b/docs/schemas/definitions/semver.yaml new file mode 100644 index 000000000..73f05f013 --- /dev/null +++ b/docs/schemas/definitions/semver.yaml @@ -0,0 +1,31 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/definitions/semver.yaml + +type: string +title: Semantic Version +description: >- + A valid semantic version (semver) string. For reference, see https://semver.org/ +pattern: >- + ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ + +$comment: | + This pattern comes from the semver website's FAQ: + + https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string + + It's the suggested regex pattern for JavaScript. + + This is the same pattern, made multi-line for easier readability. + + ``` + ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*) + (?:-( + (?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*) + (?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)) + *))? + (?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ + ``` + + The first line matches the `major.minor.patch` components of the version. The middle lines match + the pre-release components. The last line matches the build metadata component. diff --git a/docs/schemas/outputs/config/get.yaml b/docs/schemas/outputs/config/get.yaml new file mode 100644 index 000000000..ad3e7afc1 --- /dev/null +++ b/docs/schemas/outputs/config/get.yaml @@ -0,0 +1,38 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/results/config/get.yaml + +title: DSC Configuration get command result +description: >- + Represents the data structure returned by the `dsc config get` command. + +type: object +required: + - results + - messages + - hadErrors +properties: + results: + title: Results + description: >- + The results of the `get` method for every DSC Resource instance in the + DSC Configuration Document with the instance's name and type. + type: array + items: + title: Get Result + type: object + required: + - name + - type + - result + properties: + name: + $ref: /dsc/2023/07/definitions/instanceName.yaml + type: + $ref: /dsc/2023/07/definitions/resourceType.yaml + result: + $ref: /dsc/2023/07/results/resource/get.yaml + messages: + $ref: /dsc/2023/07/definitions/messages.yaml + hadErrors: + $ref: /dsc/2023/07/definitions/hadErrors.yaml diff --git a/docs/schemas/outputs/config/set.yaml b/docs/schemas/outputs/config/set.yaml new file mode 100644 index 000000000..53973ff44 --- /dev/null +++ b/docs/schemas/outputs/config/set.yaml @@ -0,0 +1,38 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/results/config/set.yaml + +title: DSC Configuration set command result +description: >- + Represents the data structure returned by the `dsc config set` command. + +type: object +required: + - results + - messages + - hadErrors +properties: + results: + title: Results + description: >- + The results of the `set` method for every DSC Resource instance in the + DSC Configuration Document with the instance's name and type. + type: array + items: + title: Set Result + type: object + required: + - name + - type + - result + properties: + name: + $ref: /dsc/2023/07/definitions/instanceName.yaml + type: + $ref: /dsc/2023/07/definitions/resourceType.yaml + result: + $ref: /dsc/2023/07/results/resource/set.yaml + messages: + $ref: /dsc/2023/07/definitions/messages.yaml + hadErrors: + $ref: /dsc/2023/07/definitions/hadErrors.yaml diff --git a/docs/schemas/outputs/config/test.yaml b/docs/schemas/outputs/config/test.yaml new file mode 100644 index 000000000..f8c4256dd --- /dev/null +++ b/docs/schemas/outputs/config/test.yaml @@ -0,0 +1,38 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/results/config/test.yaml + +title: DSC Configuration test command result +description: >- + Represents the data structure returned by the `dsc config test` command. + +type: object +required: + - results + - messages + - hadErrors +properties: + results: + title: Results + description: >- + The results of the `test` method for every DSC Resource instance in the + DSC Configuration Document with the instance's name and type. + type: array + items: + title: Test Result + type: object + required: + - name + - type + - result + properties: + name: + $ref: /dsc/2023/07/definitions/instanceName.yaml + type: + $ref: /dsc/2023/07/definitions/resourceType.yaml + result: + $ref: /dsc/2023/07/results/resource/test.yaml + messages: + $ref: /dsc/2023/07/definitions/messages.yaml + hadErrors: + $ref: /dsc/2023/07/definitions/hadErrors.yaml diff --git a/docs/schemas/outputs/config/validate.yaml b/docs/schemas/outputs/config/validate.yaml new file mode 100644 index 000000000..1e5108d35 --- /dev/null +++ b/docs/schemas/outputs/config/validate.yaml @@ -0,0 +1,13 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/results/config/validate.yaml + +$comment: | + Not implemented yet. + +title: DSC Resource schema result +description: >- + Describes the return data for a DSC Resource from the `dsc config validate` + command. + +type: object diff --git a/docs/schemas/outputs/resource/get.yaml b/docs/schemas/outputs/resource/get.yaml new file mode 100644 index 000000000..0930ef584 --- /dev/null +++ b/docs/schemas/outputs/resource/get.yaml @@ -0,0 +1,20 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/results/resource/get.yaml + +title: DSC Resource get result +description: >- + Describes the return data for a DSC Resource instance from the + `dsc resource get` command. + +type: object +required: + - actual_state +properties: + actual_state: + title: The DSC Resource instance's current state + description: >- + This property always represents the current state of the DSC Resource + instance as returned by its `get` method. DSC validates this return value + against the DSC Resource's schema. + type: object diff --git a/docs/schemas/outputs/resource/list.yaml b/docs/schemas/outputs/resource/list.yaml new file mode 100644 index 000000000..ebf63295a --- /dev/null +++ b/docs/schemas/outputs/resource/list.yaml @@ -0,0 +1,89 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/results/resource/list.yaml + +title: DSC Resource list result +description: >- + Describes the return data for a DSC Resource instance from the + `dsc resource list` command. + +type: object +properties: + type: + # Even though I used the defined type here, I noticed that the Test* + # resources don't follow that pattern - their type name is just a name, + # no prefix. Should we have a different schema for those, or should this + # be relaxed? + $ref: /dsc/2023/07/definitions/resourceType.yaml + version: + # Only the Test* resources seem to have this field populated. + $ref: /dsc/2023/07/definitions/semver.yaml + path: + # This value seems to mean something different for the Test* resources + title: Path + description: >- + Indicates the path to the DSC Resource on the file system. + type: string + directory: + # This value seems to mean something different for the Test* resources + title: Directory + description: >- + Indicates the path to the folder containing the DSC Resource on the file + system. + type: string + implementedAs: + title: Implemented as + description: >- + Indicates how the DSC Resource was implemented. To specify a custom + implementation, specify this value as an object with the `custom` + property. + oneOf: + - title: Standard implementation + description: >- + Indicates that the DSC Resource is implemented as one of the standard + implementations built into DSC. + type: string + enum: + - Command + + # Need to understand how this works to document it more usefully + - title: Custom implementation + description: >- + Indicates that the DSC Resource uses a custom implementation. + type: object + required: + - custom + properties: + custom: + title: Custom implementation name + description: >- + The name of the custom implementation. + type: string + author: + # Only the Test* resources seem to have this field populated. + title: Author + description: >- + Indicates the name of the person or organization that developed and + maintains the DSC Resource. + type: + - string + - 'null' + properties: + # Only the Test* resources seem to have this field populated. + title: Properties + description: >- + Defines the DSC Resource's property names. + type: array + items: + type: string + pattern: ^\w+$ + requires: + title: Required DSC Resource Provider + description: >- + Defines the fully qualified type name of the DSC Resource Provider the + DSC Resource depends on. + oneOf: + - $ref: /dsc/2023/07/definitions/resourceType.yaml + - type: 'null' + manifest: + $ref: /dsc/2023/07/resource/manifest.yaml \ No newline at end of file diff --git a/docs/schemas/outputs/resource/schema.yaml b/docs/schemas/outputs/resource/schema.yaml new file mode 100644 index 000000000..c37702908 --- /dev/null +++ b/docs/schemas/outputs/resource/schema.yaml @@ -0,0 +1,10 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/results/resource/schema.yaml + +title: DSC Resource schema result +description: >- + Describes the return data for a DSC Resource from the `dsc resource schema` + command. This command always returns the DSC Resource's JSON schema document. + +type: object diff --git a/docs/schemas/outputs/resource/set.yaml b/docs/schemas/outputs/resource/set.yaml new file mode 100644 index 000000000..088ec4d4c --- /dev/null +++ b/docs/schemas/outputs/resource/set.yaml @@ -0,0 +1,40 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/results/resource/set.yaml + +title: DSC Resource set result +description: >- + Describes the return data for a DSC Resource instance from the + `dsc resource set` command. + +type: object +required: + - before_state + - after_state + - changed_properties +properties: + before_state: + title: State before enforcing + description: >- + This property always represents the desired state of the DSC Resource + instance before the `set` method runs. DSC validates this return value + against the DSC Resource's schema. + type: object + after_state: + title: State after enforcing + description: >- + This property always represents the current state of the DSC Resource + instance as returned by its `set` method after enforcing the desired + state. DSC validates this return value against the DSC Resource's schema. + type: object + changed_properties: + title: Changed Properties + description: >- + This property always represents the list of property names for the DSC + Resource instance that the `set` method modified. When this value is an + empty array, the `set` method didn't enforce any properties for the + instance. + type: array + default: [] + items: + type: string diff --git a/docs/schemas/outputs/resource/test.yaml b/docs/schemas/outputs/resource/test.yaml new file mode 100644 index 000000000..17789f04d --- /dev/null +++ b/docs/schemas/outputs/resource/test.yaml @@ -0,0 +1,39 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/results/resource/test.yaml + +title: DSC Resource test result +description: >- + Describes the return data for a DSC Resource instance from the + `dsc resource test` command. + +type: object +required: + - expected_state + - actual_state + - diff_properties +properties: + expected_state: + title: Expected State + description: >- + This property always represents the desired state of the DSC Resource + instance as specified to DSC. + type: object + actual_state: + title: Actual State + description: >- + This property always represents the current state of the DSC Resource + instance as returned by its `test` method or, if the DSC Resource doesn't + define the `test` method, by its `get` method. DSC validates this return + value against the DSC Resource's schema. + type: object + diff_properties: + title: Differing Properties + description: >- + This property always represents the list of property names for the DSC + Resource instance that aren't in the desired state. When this property + is an empty array, the instance is in the desired state. + type: array + default: [] + items: + type: string diff --git a/docs/schemas/outputs/schema.yaml b/docs/schemas/outputs/schema.yaml new file mode 100644 index 000000000..a4260c636 --- /dev/null +++ b/docs/schemas/outputs/schema.yaml @@ -0,0 +1,10 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/results/schema.yaml + +title: DSC Resource schema result +description: >- + Describes the return data for a DSC Resource from the `dsc schema` + command. This command always returns a JSON schema document. + +type: object diff --git a/docs/schemas/resource/manifest.get.yaml b/docs/schemas/resource/manifest.get.yaml new file mode 100644 index 000000000..c0ad3be13 --- /dev/null +++ b/docs/schemas/resource/manifest.get.yaml @@ -0,0 +1,27 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.yaml + +title: Get Method +description: >- + Defines how DSC must call the DSC Resource to get the current state of an + instance. + +type: object +required: + - executable +properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + input: + $ref: /dsc/2023/07/definitions/inputKind.yaml + +examples: + - executable: registry + args: + - config + - get + input: stdin + - executable: osinfo \ No newline at end of file diff --git a/docs/schemas/resource/manifest.provider.yaml b/docs/schemas/resource/manifest.provider.yaml new file mode 100644 index 000000000..9c8b5fe1f --- /dev/null +++ b/docs/schemas/resource/manifest.provider.yaml @@ -0,0 +1,49 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.yaml + +title: Provider +description: >- + Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider + enables users to manage resources that don't have their own manifests with + DSC. + +type: object +required: + - list + - config +properties: + list: + title: List Command + description: >- + Defines how DSC must call the DSC Resource Provider to list its supported + DSC Resources. + type: object + required: + - executable + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + config: + title: Expected Configuration + description: >- + Defines whether the provider expects to receive a full and unprocessed + configuration as a single JSON blob over stdin or a sequence of JSON + Lines for each child resource's configurations. + type: string + enum: + - full + - sequence + +examples: + - config: full + list: + executable: pwsh + args: + - -NoLogo + - -NonInteractive + - -NoProfile + - -Command + - ./powershellgroup.resource.ps1 List diff --git a/docs/schemas/resource/manifest.schema.yaml b/docs/schemas/resource/manifest.schema.yaml new file mode 100644 index 000000000..5e0b6c589 --- /dev/null +++ b/docs/schemas/resource/manifest.schema.yaml @@ -0,0 +1,79 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.yaml + +title: Instance Schema +description: >- + Defines how DSC must validate a JSON blob representing an instance of the + DSC Resource. + +# While the current implementation is somewhat confusing in the schema, I +# think it's actually easier to document. Mainly, the complexity comes from +# the expected object having exactly one property with exclusive key names. +# If a DSC Resource could specify a combination of these values, the schema +# would be less complex. +type: object +oneOf: + - required: [command] + - required: [embedded] +properties: + command: + title: Instance Schema Command + description: >- + Defines how DSC must call the DSC Resource to get the JSON Schema for + validating a JSON blob representing an instance of the DSC Resource. + type: object + required: + - executable + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + embedded: + title: Embedded Instance Schema + description: >- + Defines the JSON Schema DSC must use to validate a JSON blob + representing an instance of the DSC Resource. + type: object + minProperties: 1 + url: + title: Instance Schema URL + description: >- + Defines the URL to the DSC Resource's JSON schema for integrating tools. + type: string + format: uri + +examples: + - command: + executable: registry + args: + - schema + - embedded: + $schema: http://json-schema.org/draft-07/schema# + title: OSInfo + type: object + required: [] + properties: + $id: + type: string + architecture: + type: [string, "null"] + bitness: + $ref: "#/definitions/Bitness" + codename: + type: [string, "null"] + edition: + type: [string, "null"] + family: + $ref: "#/definitions/Family" + version: + type: string + additionalProperties: false + definitions: + Bitness: + type: string + enum: ["32", "64", "unknown"] + Family: + type: string + enum: [Linux, macOS, Windows] diff --git a/docs/schemas/resource/manifest.set.yaml b/docs/schemas/resource/manifest.set.yaml new file mode 100644 index 000000000..8f8852b54 --- /dev/null +++ b/docs/schemas/resource/manifest.set.yaml @@ -0,0 +1,43 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.yaml + +title: Set Method +description: >- + Defines how DSC must call the DSC Resource to set the desired state of + an instance and how to process the output from the DSC Resource. + +type: object +required: + - executable + - input +properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + input: + $ref: /dsc/2023/07/definitions/inputKind.yaml + preTest: + title: Resource Performs Pre-Test + description: >- + Defines whether the DSC Resource performs its own test to ensure + idempotency when calling the `set` command. Set this value to `true` + if the DSC Resource tests input before modifying system state. + type: boolean + default: false + return: + description: >- + Defines whether the command returns a JSON blob of the DSC Resource's + state after the set operation or the state and an array of the + properties the DSC Resource modified. + $ref: /dsc/2023/07/definitions/returnKind.yaml + +examples: + - executable: registry + args: + - config + - set + input: stdin + preTest: true + return: state diff --git a/docs/schemas/resource/manifest.test.yaml b/docs/schemas/resource/manifest.test.yaml new file mode 100644 index 000000000..e26d22503 --- /dev/null +++ b/docs/schemas/resource/manifest.test.yaml @@ -0,0 +1,34 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.yaml + +title: Test Method +description: >- + Defines how DSC must call the DSC Resource to test if an instance is in + the desired state and how to process the output from the DSC Resource. + +type: object +required: + - executable + - input +properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + input: + $ref: /dsc/2023/07/definitions/inputKind.yaml + return: + title: Test Command Return Type + description: >- + Defines whether the command returns a JSON blob of the DSC Resource's current state or the + state and an array of the properties that are out of the desired state. + $ref: /dsc/2023/07/definitions/returnKind.yaml + +examples: + - executable: registry + args: + - config + - test + input: stdin + return: state diff --git a/docs/schemas/resource/manifest.validate.yaml b/docs/schemas/resource/manifest.validate.yaml new file mode 100644 index 000000000..c270b03d3 --- /dev/null +++ b/docs/schemas/resource/manifest.validate.yaml @@ -0,0 +1,23 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.yaml + +title: Validate Method +description: >- + Defines how DSC must call the DSC Resource to validate the state of an + instance. This method is mandatory for DSC Group Resources. It's ignored for + all other DSC Resources. +type: object +required: + - executable +properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + +examples: + - executable: dsc + args: + - config + - validate diff --git a/docs/schemas/resource/manifest.yaml b/docs/schemas/resource/manifest.yaml new file mode 100644 index 000000000..00c6ed686 --- /dev/null +++ b/docs/schemas/resource/manifest.yaml @@ -0,0 +1,83 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.yaml + +title: Command-based DSC Resource Manifest +description: >- + Defines a valid command-based DSC Resource. + +type: object +required: + - manifestVersion + - type + - version + - get +properties: + manifestVersion: + title: Manifest Version + description: >- + The semver of the DSC Resource manifest schema to validate this manifest + with. + $ref: /dsc/2023/07/definitions/semver.yaml + enums: + - '1.0' + type: + $ref: /dsc/2023/07/definitions/resourceType.yaml + version: + title: Resource Semantic Version + description: >- + The semantic version (semver) of the DSC Resource. This version + identifies the DSC Resource, not the version of the application it + manages. + $ref: /dsc/2023/07/definitions/semver.yaml + description: + title: Resource Description + description: >- + A short synopsis of the DSC Resource's purpose. + # Should this include a maximum length or a pattern that forbids newlines? + type: string + tags: + title: Tags + description: >- + An array of short strings used to search for DSC Resources. + type: array + items: + type: string + pattern: ^\w+$ + get: + $ref: /dsc/2023/07/resource/manifest.get.yaml + set: + $ref: /dsc/2023/07/resource/manifest.set.yaml + test: + $ref: /dsc/2023/07/resource/manifest.test.yaml + validate: + $ref: /dsc/2023/07/resource/manifest.validate.yaml + provider: + # I'm not clear on how this works in practice + $ref: /dsc/2023/07/resource/manifest.provider.yaml + exitCodes: + # This setting in the root of the schema implies exit codes must have the + # same meaning across all executions. What about implementations that + # support multiple executables? Should exitCodes be a key that exists on + # command/method objects too? + title: Exit Codes + description: >- + This property defines a map of valid exit codes for the DSC Resource. + DSC always interprets exit code `0` as a successful operation and any + other exit code as an error. Use this property to indicate human-readable + semantic meanings for the DSC Resource's exit codes. + type: object + propertyNames: + pattern: "^[0-9]+$" + patternProperties: + "^[0-9]+$": + type: string + examples: + - exitCodes: + "0": Success + "1": Invalid parameter + "2": Invalid input + "3": Registry error + "4": JSON serialization failed + schema: + $ref: /dsc/2023/07/resource/manifest.schema.yaml diff --git a/docs/schemas/resource/properties/ensure.yaml b/docs/schemas/resource/properties/ensure.yaml new file mode 100644 index 000000000..03667f7c7 --- /dev/null +++ b/docs/schemas/resource/properties/ensure.yaml @@ -0,0 +1,12 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.yaml + +title: Ensure Existence +description: >- + Indicates whether the DSC Resource instance should exist. + +type: string +enum: + - Absent + - Present \ No newline at end of file diff --git a/docs/schemas/resource/properties/inDesiredState.yaml b/docs/schemas/resource/properties/inDesiredState.yaml new file mode 100644 index 000000000..015c43ee3 --- /dev/null +++ b/docs/schemas/resource/properties/inDesiredState.yaml @@ -0,0 +1,13 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.yaml + +title: Instance is in the Desired State +description: >- + Indicates whether the instance is in the desired state. This property is only + returned by the `test` method. + +type: + - boolean + - 'null' +readOnly: true \ No newline at end of file diff --git a/docs/schemas/resource/properties/purge.yaml b/docs/schemas/resource/properties/purge.yaml new file mode 100644 index 000000000..9168461ee --- /dev/null +++ b/docs/schemas/resource/properties/purge.yaml @@ -0,0 +1,14 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.yaml + +title: Purge +description: >- + Indicates that only the components described in the DSC Resource should exist. + If other components exist, the DSC Resource is out of the desired state. When + enforcing desired state, the DSC Resource removes unmanaged components. + +type: + - boolean + - 'null' +writeOnly: true diff --git a/docs/schemas/resource/properties/rebootRequested.yaml b/docs/schemas/resource/properties/rebootRequested.yaml new file mode 100644 index 000000000..32b173111 --- /dev/null +++ b/docs/schemas/resource/properties/rebootRequested.yaml @@ -0,0 +1,12 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.yaml + +title: Reboot Requested +description: >- + Indicates that the set operation requires a reboot before it's fully complete. + +type: + - boolean + - 'null' +readOnly: true From 14ad5885b8186956c0d7ea1a1f1aa82bd683593f Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 30 Jun 2023 18:20:24 -0500 Subject: [PATCH 02/11] (MAINT) Improve embedded schema definition This change extends the JSON Schema definition for DSC Resource manifests that embed their schema. It: - makes the `$schema`, `type`, and `properties` keys mandatory - limits the `$schema` to known schemas and `type` to `object` - Requires at least one property defined on the object - Adds the standard properties to the list of available properties, so authors get intellisense for them. --- docs/schemas/resource/manifest.schema.yaml | 40 +++++++++++++++++++++- 1 file changed, 39 insertions(+), 1 deletion(-) diff --git a/docs/schemas/resource/manifest.schema.yaml b/docs/schemas/resource/manifest.schema.yaml index 5e0b6c589..849b78128 100644 --- a/docs/schemas/resource/manifest.schema.yaml +++ b/docs/schemas/resource/manifest.schema.yaml @@ -36,7 +36,45 @@ properties: Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource. type: object - minProperties: 1 + required: + - $schema + - type + - properties + properties: + type: + # Ensures the DSC Resource is always an object + const: object + $schema: + # Ensures the DSC Resource always uses a schema we can understand + type: string + format: uri-reference + enum: + - https://json-schema.org/draft/2020-12/schema + - http://json-schema.org/draft-07/schema# + $id: + # Currently optional - maybe we should require this? + type: string + format: uri-reference + properties: + # Defines the property validation - requires authors to specify at + # least one property, ensures all unevaluated properties are of a kind + # we can understand, and makes the standard properties available to + # manifest authors. + type: object + minProperties: 1 + unevaluatedProperties: + anyOf: + - $ref: https://json-schema.org/draft/2020-12/schema + - $ref: http://json-schema.org/draft-07/schema# + properties: + _ensure: + $ref: /dsc/2023/07/resource/properties/ensure.yaml + _inDesiredState: + $ref: /dsc/2023/07/resource/properties/inDesiredState.yaml + _purge: + $ref: /dsc/2023/07/resource/properties/purge.yaml + _rebootRequested: + $ref: /dsc/2023/07/resource/properties/rebootRequested.yaml url: title: Instance Schema URL description: >- From 3fb3209bae356742a69f07ac326269d3846dfe20 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 30 Jun 2023 18:22:30 -0500 Subject: [PATCH 03/11] (MAINT) Reorganize parameter definition schemas This change moves the parameter-block related JSON schemas together for clarity and shifts from in-document definitions to references. This was required for solving an issue with how VS Code resolves references without adding even more complex handling. --- docs/schemas/config/document.parameters.yaml | 55 ++----------------- .../{ => parameters}/dataType.yaml | 2 +- .../integerValidationProperties.yaml | 26 +++++++++ .../lengthValidationProperties.yaml | 26 +++++++++ .../parameters/validValueTypes.yaml | 16 ++++++ 5 files changed, 74 insertions(+), 51 deletions(-) rename docs/schemas/definitions/{ => parameters}/dataType.yaml (78%) create mode 100644 docs/schemas/definitions/parameters/integerValidationProperties.yaml create mode 100644 docs/schemas/definitions/parameters/lengthValidationProperties.yaml create mode 100644 docs/schemas/definitions/parameters/validValueTypes.yaml diff --git a/docs/schemas/config/document.parameters.yaml b/docs/schemas/config/document.parameters.yaml index 5027df48c..d6d781a16 100644 --- a/docs/schemas/config/document.parameters.yaml +++ b/docs/schemas/config/document.parameters.yaml @@ -19,12 +19,12 @@ patternProperties: - type properties: type: - $ref: /dsc/2023/07/definitions/dataType.yaml + $ref: /dsc/2023/07/definitions/parameters/dataType.yaml defaultValue: title: Default value description: >- Defines the default value for the parameter. - $ref: "#/$defs/ValidValueTypes" + $ref: /dsc/2023/07/definitions/parameters/validValueTypes.yaml allowedValues: title: Allowed values description: >- @@ -32,7 +32,7 @@ patternProperties: parameter is defined with any other values, it's invalid. type: array items: - $ref: "#/$defs/ValidValueTypes" + $ref: /dsc/2023/07/definitions/parameters/validValueTypes.yaml description: title: Parameter description description: >- @@ -50,56 +50,11 @@ patternProperties: type: const: int then: - $ref: "#/$defs/IntegerValidationProperties" + $ref: /dsc/2023/07/definitions/parameters/integerValidationProperties.yaml - if: oneOf: - properties: { type: { const: string } } - properties: { type: { const: securestring } } - properties: { type: { const: array } } then: - $ref: "#/$defs/LengthValidationProperties" - -$defs: - ValidValueTypes: - type: - - string - - integer - - object - - array - - boolean - IntegerValidationProperties: - properties: - minValue: - title: Minimum value - description: >- - The minimum valid value for an integer type. If defined with the - `maxValue` property, this value must be less than the value of - `maxValue`. - type: integer - minimum: 0 - maxValue: - title: Maximum value - description: >- - The maximum valid value for an integer type. If defined with the - `minValue` property, this value must be greater than the value of - `minValue`. - type: integer - minimum: 0 - LengthValidationProperties: - properties: - minLength: - title: Minimum length - description: >- - The minimum valid length for a `string`, `securestring`, or `array`. - If defined with the `maxLength` property, this value must be less - than the value of `maxLength`. - type: integer - minimum: 0 - maxLength: - title: Maximum length - description: >- - The maximum valid length for a `string`, `securestring`, or `array`. - If defined with the `minLength` property, this value must be less - than the value of `minLength`. - type: integer - minimum: 0 \ No newline at end of file + $ref: /dsc/2023/07/definitions/parameters/lengthValidationProperties.yaml diff --git a/docs/schemas/definitions/dataType.yaml b/docs/schemas/definitions/parameters/dataType.yaml similarity index 78% rename from docs/schemas/definitions/dataType.yaml rename to docs/schemas/definitions/parameters/dataType.yaml index 4bf57f15d..1cfa893d6 100644 --- a/docs/schemas/definitions/dataType.yaml +++ b/docs/schemas/definitions/parameters/dataType.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/definitions/dataType.yaml +$id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataType.yaml title: Data Type description: >- diff --git a/docs/schemas/definitions/parameters/integerValidationProperties.yaml b/docs/schemas/definitions/parameters/integerValidationProperties.yaml new file mode 100644 index 000000000..66479a82f --- /dev/null +++ b/docs/schemas/definitions/parameters/integerValidationProperties.yaml @@ -0,0 +1,26 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/integerValidationProperties.yaml + +$comment: | + This schema fragment makes it a little easier to compose the valid properties + for DSC Configuration document parameters. These only apply to `int` type + parameters. + +properties: + minValue: + title: Minimum value + description: >- + The minimum valid value for an integer type. If defined with the + `maxValue` property, this value must be less than the value of + `maxValue`. + type: integer + minimum: 0 + maxValue: + title: Maximum value + description: >- + The maximum valid value for an integer type. If defined with the + `minValue` property, this value must be greater than the value of + `minValue`. + type: integer + minimum: 0 diff --git a/docs/schemas/definitions/parameters/lengthValidationProperties.yaml b/docs/schemas/definitions/parameters/lengthValidationProperties.yaml new file mode 100644 index 000000000..c2aa560eb --- /dev/null +++ b/docs/schemas/definitions/parameters/lengthValidationProperties.yaml @@ -0,0 +1,26 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/lengthValidationProperties.yaml + +$comment: | + This schema fragment makes it a little easier to compose the valid properties + for DSC Configuration document parameters. These only apply to `string`, + `securestring`, and `array` type parameters. + +properties: + minLength: + title: Minimum length + description: >- + The minimum valid length for a `string`, `securestring`, or `array`. If + defined with the `maxLength` property, this value must be less than the + value of `maxLength`. + type: integer + minimum: 0 + maxLength: + title: Maximum length + description: >- + The maximum valid length for a `string`, `securestring`, or `array`. If + defined with the `minLength` property, this value must be less than the + value of `minLength`. + type: integer + minimum: 0 diff --git a/docs/schemas/definitions/parameters/validValueTypes.yaml b/docs/schemas/definitions/parameters/validValueTypes.yaml new file mode 100644 index 000000000..e56f91ede --- /dev/null +++ b/docs/schemas/definitions/parameters/validValueTypes.yaml @@ -0,0 +1,16 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/validValueTypes.yaml + +$comment: | + This schema fragment makes it a little easier to compose the valid properties + for DSC Configuration document parameters. As-written, values must be one of + those on this list - the schema definition for dataType excludes `null` and + numbers with fractional parts, like `3.5`. + +type: + - string + - integer + - object + - array + - boolean \ No newline at end of file From d7d109a36970d49b56e79b70237317862fe181f4 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 30 Jun 2023 18:27:21 -0500 Subject: [PATCH 04/11] (MAINT) Add build script for bundling schemas This change adds a new build script to the schema folder. By default, it generated bundled schema files for the configuration document and resource manifest schemas. It can bundle schemas in four formats: - JSON - YAML - JSON (VS Code) - YAML (VS Code) The VS Code bundles have their definitions organized differently - VS Code has not yet fully implemented 2020-12 support, so it can not resolve non-local (ie not starting with `#/`) references correctly. The non-VS Code bundles were validated with [HyperJump][01]. [01]: https://json-schema.hyperjump.io/ This change also temporarily includes the gotstoy schema in the bundled output folder so you can review how the schema affects the authoring DevX. This change includes a bundle config file for determining which schemas should be bundled and how they should be named. While the outputs are committed here for convenience and reviewability, they should instead be generated with the build script and published as needed. They're build artifacts generated from the decomposed schema definitions. The build step doesn't support injecting links to the documentation, but we should add that functionality in the future. This would make it easier for authors and editors of configuration documents and resource manifests to look up the documentation without having to search for it. --- docs/schemas/build.ps1 | 558 +++++++++++++ docs/schemas/bundle.config.yaml | 42 + docs/schemas/bundled/config.document.json | 247 ++++++ .../bundled/config.document.vscode.json | 259 ++++++ .../bundled/config.document.vscode.yaml | 211 +++++ docs/schemas/bundled/config.document.yaml | 429 +++++----- .../bundled/example.gotstoy.resource.json | 65 ++ .../bundled/example.gotstoy.resource.yaml | 55 ++ .../bundled/manual.config.document.yaml | 224 +++++ .../bundled/manual.resource.manifest.yaml | 337 ++++++++ docs/schemas/bundled/outputs.config.get.json | 135 +++ docs/schemas/bundled/outputs.config.set.json | 151 ++++ docs/schemas/bundled/outputs.config.test.json | 151 ++++ .../bundled/outputs.config.validate.json | 9 + .../schemas/bundled/outputs.resource.get.json | 18 + .../bundled/outputs.resource.list.json | 668 +++++++++++++++ .../bundled/outputs.resource.schema.json | 8 + .../schemas/bundled/outputs.resource.set.json | 34 + .../bundled/outputs.resource.test.json | 34 + docs/schemas/bundled/outputs.schema.json | 8 + docs/schemas/bundled/resource.manifest.json | 582 +++++++++++++ .../bundled/resource.manifest.vscode.json | 548 ++++++++++++ .../bundled/resource.manifest.vscode.yaml | 431 ++++++++++ docs/schemas/bundled/resource.manifest.yaml | 782 +++++++++++------- docs/schemas/definitions/resourceType.yaml | 2 +- docs/schemas/resource/manifest.schema.yaml | 45 +- 26 files changed, 5484 insertions(+), 549 deletions(-) create mode 100644 docs/schemas/build.ps1 create mode 100644 docs/schemas/bundle.config.yaml create mode 100644 docs/schemas/bundled/config.document.json create mode 100644 docs/schemas/bundled/config.document.vscode.json create mode 100644 docs/schemas/bundled/config.document.vscode.yaml create mode 100644 docs/schemas/bundled/example.gotstoy.resource.json create mode 100644 docs/schemas/bundled/example.gotstoy.resource.yaml create mode 100644 docs/schemas/bundled/manual.config.document.yaml create mode 100644 docs/schemas/bundled/manual.resource.manifest.yaml create mode 100644 docs/schemas/bundled/outputs.config.get.json create mode 100644 docs/schemas/bundled/outputs.config.set.json create mode 100644 docs/schemas/bundled/outputs.config.test.json create mode 100644 docs/schemas/bundled/outputs.config.validate.json create mode 100644 docs/schemas/bundled/outputs.resource.get.json create mode 100644 docs/schemas/bundled/outputs.resource.list.json create mode 100644 docs/schemas/bundled/outputs.resource.schema.json create mode 100644 docs/schemas/bundled/outputs.resource.set.json create mode 100644 docs/schemas/bundled/outputs.resource.test.json create mode 100644 docs/schemas/bundled/outputs.schema.json create mode 100644 docs/schemas/bundled/resource.manifest.json create mode 100644 docs/schemas/bundled/resource.manifest.vscode.json create mode 100644 docs/schemas/bundled/resource.manifest.vscode.yaml diff --git a/docs/schemas/build.ps1 b/docs/schemas/build.ps1 new file mode 100644 index 000000000..709feaca1 --- /dev/null +++ b/docs/schemas/build.ps1 @@ -0,0 +1,558 @@ +#requires -Modules yayaml +using namespace System.Collections + +<# + .SYNOPSIS +#> + +[cmdletbinding(DefaultParameterSetName='ByConfig')] +param( + [string] + $OutputDirectory = "$PSScriptRoot/bundled", + + [Parameter(ParameterSetName='ByPath')] + [string[]] + $ConfigFilePath, + + [string[]] + [ValidateSet('Json', 'JsonVSCode', 'Yaml', 'YamlVSCode')] + $OutputFormat = @( + 'Json' + 'JsonVSCode' + 'Yaml' + 'YamlVSCode' + ) +) + +begin { + class LocalJsonSchemaRegistry { + [Specialized.OrderedDictionary] + $Map + + [Generic.List[Specialized.OrderedDictionary]] + $List + + LocalJsonSchemaRegistry() { + $this.Map = [Specialized.OrderedDictionary]::new() + $this.List = [Generic.List[Specialized.OrderedDictionary]]::new() + } + } + + function Remove-JsonSchemaKey { + [cmdletbinding(DefaultParameterSetName='SchemaObject')] + [OutputType([Specialized.OrderedDictionary])] + [OutputType([Object[]])] + param( + [parameter(ParameterSetName='SchemaObject')] + [Specialized.OrderedDictionary] + $Schema, + + [parameter(ParameterSetName='SchemaList', DontShow)] + [Object[]] + $SchemaList, + + [string]$KeyName + ) + + process { + if ($PSCmdlet.ParameterSetName -eq 'SchemaObject') { + $MungedSchema = [Specialized.OrderedDictionary]::new() + + $Schema.GetEnumerator().Where({$_.Key -ne $KeyName}).ForEach({ + if ($_.Value -is [Object[]]) { + $MungedKeyValue = Remove-JsonSchemaKey -KeyName $KeyName -SchemaList $_.Value + $MungedSchema.Add($_.Key, $MungedKeyValue) + } elseif ($_.Value -is [Specialized.OrderedDictionary]) { + $MungedKeyValue = Remove-JsonSchemaKey -KeyName $KeyName -Schema $_.Value + $MungedSchema.Add($_.Key, $MungedKeyValue) + } else { + $MungedSchema.Add($_.Key, $_.Value) + } + }) + + return $MungedSchema + } + + if ($PSCmdlet.ParameterSetName -eq 'SchemaList') { + [Object[]]$MungedArrayValue = @() + + $SchemaList.ForEach({ + if ($_ -is [Object[]]) { + $MungedArrayValue += Remove-JsonSchemaKey -KeyName $KeyName -SchemaList $_ + } elseif ($_ -is [Specialized.OrderedDictionary]) { + $MungedArrayValue += Remove-JsonSchemaKey -KeyName $KeyName -Schema $_ + } else { + $MungedArrayValue += $_ + } + }) + + return $MungedArrayValue + } + } + } + + function Get-LocalJsonSchemaRegistry { + [CmdletBinding()] + [OutputType([LocalJsonSchemaRegistry])] + param( + [switch]$WithoutExamples, + [switch]$WithoutComments, + [string[]]$SchemaDirectories = @( + "$PSScriptRoot/config" + "$PSScriptRoot/definitions" + "$PSScriptRoot/outputs" + "$PSScriptRoot/resource" + ) + ) + + begin { + $Info = [LocalJsonSchemaRegistry]::new() + } + + process { + Get-ChildItem -Path $SchemaDirectories -Recurse -File -Filter *.yaml + | ForEach-Object -process { + $Schema = Get-Content $_ -Raw | yayaml\ConvertFrom-Yaml + if ($AddDocsUrl) { + Write-Warning 'Not implemented yet' + } + if ($MakeStrict) { + Write-Warning 'Not implemented yet' + } + if ($WithoutComments) { + $Schema = Remove-JsonSchemaKey -Schema $Schema -KeyName '$comment' + } + if ($WithoutExamples) { + $Schema = Remove-JsonSchemaKey -Schema $Schema -KeyName 'examples' + } + if ($SchemaID = $Schema.'$id') { + $SchemaRefID = $SchemaID -replace 'https://schemas.microsoft.com', '' + $Info.List.Add($Schema) + $Info.Map.Add($SchemaID, $Schema) + $Info.Map.Add($SchemaRefID, $Schema) + } + } + + $Info + } + } + + function Get-JsonSchemaReference { + <# + #> + [cmdletbinding(DefaultParameterSetName='SchemaObject')] + [OutputType([Generic.List[string]])] + param( + [parameter(ParameterSetName='SchemaObject')] + [Specialized.OrderedDictionary] + $Schema, + + [parameter(ParameterSetName='SchemaList', DontShow)] + [Object[]] + $SchemaList, + + [LocalJsonSchemaRegistry] $SchemaRegistry + ) + + begin { + $References = [Generic.List[string]]::new() + $AddNestedReference = { + if ($_ -notin $References) { + $References.Add($_) + } + } + } + + process { + if ($PSCmdlet.ParameterSetName -eq 'SchemaObject') { + $Schema.GetEnumerator().ForEach({ + if ($_.Key -eq '$ref' -and $_.Value -notin $References) { + $References.Add($_.Value) + } elseif ($_.Value -is [Object[]]) { + $NestedReferences = Get-JsonSchemaReference -SchemaList $_.Value + $NestedReferences.ForEach($AddNestedReference) + } elseif ($_.Value -is [Specialized.OrderedDictionary]) { + $NestedReferences = Get-JsonSchemaReference -Schema $_.Value + $NestedReferences.ForEach($AddNestedReference) + } + }) + } + + if ($PSCmdlet.ParameterSetName -eq 'SchemaList') { + $SchemaList.ForEach({ + if ($_ -is [Object[]]) { + $NestedReferences = Get-JsonSchemaReference -SchemaList $_ + $NestedReferences.ForEach($AddNestedReference) + } elseif ($_ -is [Specialized.OrderedDictionary]) { + $NestedReferences = Get-JsonSchemaReference -Schema $_ + $NestedReferences.ForEach($AddNestedReference) + } + }) + } + + if ($null -ne $SchemaRegistry -and $References.Count -gt 0) { + foreach ($Reference in $References.Clone()) { + if ($Reference -in $SchemaRegistry.Map.Keys) { + $Resolving = @{ + Schema = $SchemaRegistry.Map.$Reference + SchemaRegistry = $SchemaRegistry + } + $NestedReferences = Get-JsonSchemaReference @Resolving + $NestedReferences.ForEach($AddNestedReference) + } + } + } + + $References + } + } + + function Merge-JsonSchema { + <# + #> + [cmdletbinding(DefaultParameterSetName='FromPreset')] + [OutputType([Specialized.OrderedDictionary])] + param( + [Parameter(ParameterSetName='FromPath', Mandatory)] + [string] + $Path, + + [Parameter(ParameterSetName='FromSchema', Mandatory)] + [Specialized.OrderedDictionary] + $Schema, + + [Parameter(ParameterSetName='FromPreset', Mandatory)] + [ValidateSet('ConfigDocument', 'ResourceManifest')] + [string] + $Preset, + + [LocalJsonSchemaRegistry] $SchemaRegistry, + + [switch]$ForVSCode, + [switch]$WithoutComments, + [switch]$WithoutExamples + ) + + begin { + if ($null -eq $SchemaRegistry) { + $SchemaRegistry = Get-LocalJsonSchemaRegistry + } + + $Schema = [Specialized.OrderedDictionary]::new() + $References = [Generic.List[string]]::new() + $RelativeUriReferencePattern = @( + '(?m)' + '^' + '(?\s+\$ref:\s+)' + '(?/.+)' + '$' + ) -join '' + } + + process { + if ($PSCmdlet.ParameterSetName -eq 'FromPath') { + $Schema = Get-Content -Path $Path -Raw | yayaml\ConvertFrom-Yaml + } + if ($PSCmdlet.ParameterSetName -eq 'FromPreset') { + switch ($Preset) { + 'ConfigDocument' { + $Schema = $SchemaRegistry.Map.'/dsc/2023/07/config/document.yaml' + } + 'ResourceManifest' { + $Schema = $SchemaRegistry.Map.'/dsc/2023/07/resource/manifest.yaml' + } + } + } + + $MergedSchema = $Schema | yayaml\ConvertTo-Yaml -Depth 99 | yayaml\ConvertFrom-Yaml + + $References = Get-JsonSchemaReference -Schema $Schema -SchemaRegistry $SchemaRegistry + + if ($ForVSCode) { + if ('$defs' -notin $MergedSchema.Keys) { + $MergedSchema.Add('$defs', [Specialized.OrderedDictionary]::new()) + } + + foreach ($Reference in $References) { + $ReferenceSchema = $SchemaRegistry.Map.$Reference + if ($null -eq $ReferenceSchema -and $Reference -match '#\/') { + Write-Verbose "Skipping local reference '$Reference'" + continue + } + + if ($null -eq $ReferenceSchema -or $Reference -match '^https?:\/\/') { + Write-Verbose "Skipping apparent remote reference '$Reference'" + continue + } + + $ReferenceSegments = $Reference.Trim('/') -split '/' + $Working = $MergedSchema.'$defs' + + for ($i = 0; $i -lt $ReferenceSegments.Count; $i++) { + $Segment = $ReferenceSegments[$i] + + # Segment dictionary already exists + if ($Segment -in $Working.Keys) { + $Working = $Working.$Segment + continue + } + + # Add an empty dictionary for non-final segments + if ($i -ne ($ReferenceSegments.Count - 1)) { + $Working.Add($Segment, [Specialized.OrderedDictionary]::new()) + $Working = $Working.$Segment + continue + } + + # Add the referenced schema + $Working.Add($Segment, $ReferenceSchema) + } + + } + + $MungingSchema = $MergedSchema | yayaml\ConvertTo-Yaml -Depth 99 + $MungingSchema + | Select-String -Pattern $RelativeUriReferencePattern -AllMatches + | Select-Object -ExpandProperty Matches + | ForEach-Object -Process { + $Whole = $_.Groups + | Where-Object { $_.Name -eq '0' } + | Select-Object -ExpandProperty Value + $Prefix = $_.Groups + | Where-Object { $_.Name -eq 'Prefix' } + | Select-Object -ExpandProperty Value + $RefUri = $_.Groups + | Where-Object { $_.Name -eq 'Reference' } + | Select-Object -ExpandProperty Value + $NewValue = @( + $Prefix + "'" + '#/$defs' + $RefUri.Trim() + "'" + ) -join '' + $MungingSchema = $MungingSchema -replace [regex]::Escape($Whole), $NewValue + } + $MergedSchema = $MungingSchema | yayaml\ConvertFrom-Yaml + } else { + if ('$defs' -notin $MergedSchema.Keys) { + $MergedSchema.Add('$defs', [Specialized.OrderedDictionary]::new()) + } + + foreach ($Reference in $References) { + $ReferenceSchema = $SchemaRegistry.Map.$Reference + if ($null -eq $ReferenceSchema -and $Reference -match '^#\/') { + Write-Verbose "Skipping local reference '$Reference'" + continue + } + + if ($null -eq $ReferenceSchema) { + Write-Verbose "Skipping apparent remote reference '$Reference'" + continue + } + + if ($Reference -notin $Schema.'$defs'.Keys) { + Write-Verbose "Adding reference '$Reference' to `$defs" + $MergedSchema.'$defs'.Add($ReferenceSchema.'$id', $ReferenceSchema) + } + } + } + + if ($WithoutComments) { + $MergedSchema = Remove-JsonSchemaKey -Schema $MergedSchema -KeyName '$comment' + } + if ($WithoutExamples) { + $MergedSchema = Remove-JsonSchemaKey -Schema $MergedSchema -KeyName 'examples' + } + + $MergedSchema + } + } + + function ConvertTo-MergedAndMungedJson { + [CmdletBinding()] + [OutputType([string])] + param( + [Parameter(Mandatory, ValueFromPipeline)] + [Specialized.OrderedDictionary] + $InputObject + ) + + process { + ($InputObject | ConvertTo-Json -Depth 99) -replace '\b(\w+\.)yaml', '$1json' + } + } + + function Set-BundledSchemaID { + [CmdletBinding()] + [OutputType([Specialized.OrderedDictionary])] + param( + [Parameter(Mandatory, ValueFromPipeline)] + [Specialized.OrderedDictionary] + $InputObject, + [Parameter(Mandatory)] + [string] + $BundledName + ) + + begin { + $ReplaceIDPattern = @( + '^' + '(' + [regex]::Escape('https://schemas.microsoft.com/dsc/') + '\d+\/\d+\/' + ')' + '.+\.yaml' + '$' + ) -join '' + $ReplaceIDValue = "`$1bundled/$BundledName.yaml" + } + process { + $ID = $InputObject.'$id' -replace $ReplaceIDPattern, $ReplaceIDValue + $InputObject.'$id' = $ID + $InputObject + } + } + + function Export-MergedJsonSchema { + param ( + [Parameter(Mandatory)] + [string] + $ConfigFilePath, + + [string] + $Name, + + [string] + $OutputDirectory = $PWD, + + [string[]] + [ValidateSet('Json', 'JsonVSCode', 'Yaml', 'YamlVSCode')] + $OutputFormat = @( + 'Json' + 'JsonVSCode' + 'Yaml' + 'YamlVSCode' + ) + ) + + begin { + $MergeForNormal = $OutputFormat.Where({$_ -notmatch 'VSCode'}).Count -gt 0 + $MergeForVSCode = $OutputFormat.Where({$_ -match 'VSCode'}).Count -gt 0 + } + + process { + if ([string]::IsNullOrEmpty($Name)) { + $ConfigFileInfo = Get-Item -Path $ConfigFilePath + $Name = $ConfigFileInfo.BaseName + } + + $OutputPathPrefix = "$OutputDirectory/$Name" + + if ($MergeForNormal) { + $Bundled = Merge-JsonSchema -Path $ConfigFilePath + | Set-BundledSchemaID -BundledName $Name + + if ($OutputFormat -contains 'json') { + $Bundled + | ConvertTo-MergedAndMungedJson + | Out-File -FilePath "$OutputPathPrefix.json" + } + + if ($OutputFormat -contains 'yaml') { + $Bundled + | yayaml\ConvertTo-Yaml -Depth 99 + | Out-File -FilePath "$OutputPathPrefix.yaml" + } + } + if ($MergeForVSCode) { + $Bundled = Merge-JsonSchema -Path $ConfigFilePath -ForVSCode + | Set-BundledSchemaID -BundledName $Name + + if ($OutputFormat -contains 'jsonVSCode') { + $Bundled + | ConvertTo-MergedAndMungedJson + | Out-File -FilePath "$OutputPathPrefix.vscode.json" + } + + if ($OutputFormat -contains 'yamlVSCode') { + $Bundled + | yayaml\ConvertTo-Yaml -Depth 99 + | Out-File -FilePath "$OutputPathPrefix.vscode.yaml" -Force:$Force + } + } + } + } +} + +process { + + $Bundles = Get-Content -Path $PSScriptRoot/bundle.config.yaml + | yayaml\ConvertFrom-Yaml + | ForEach-Object -Process { $_.bundle_schemas } + | ForEach-Object -Process { + [hashtable]$Bundle = $_ + $Bundle.ConfigFilePath = "$PSScriptRoot/$($Bundle.ConfigFilePath)" + $Bundle + } + + if ($ConfigFilePath.Count -ne 0) { + $Bundles = @( + { ConfigFilePath = "$PSScriptRoot/config/document.yaml" } + { ConfigFilePath = "$PSScriptRoot/resource/manifest.yaml" } + ) + } + + foreach ($BundleToExport in $Bundles) { + if ($null -eq $BundleToExport.OutputDirectory) { + $BundleToExport.OutputDirectory = $OutputDirectory + } + if ($null -eq $BundleToExport.OutputFormat) { + $BundleToExport.OutputFormat = $OutputFormat + } + + # $ExportParameters = @{ + # ConfigFilePath = $ConfigFile + # OutputDirectory = $OutputDirectory + # OutputFormat = $OutputFormat + # } + Write-Verbose "Exporting: $($BundleToExport | ConvertTo-Json)" + Export-MergedJsonSchema @BundleToExport -ErrorAction Stop + + # $ConfigFileInfo = Get-Item -Path $ConfigFile + # $OutputPathPrefix = "$OutputDirectory/$($ConfigFileInfo.BaseName)" + + # if ($MergeForNormal) { + # $Bundled = Merge-JsonSchema -Path $ConfigFile + + # if ($OutputFormat -contains 'json') { + # ($Bundled | ConvertTo-Json -Depth 99) -replace '\b(\w+\.)yaml', '$1json' + # | Out-File -FilePath "$OutputPathPrefix.json" + # } + + # if ($OutputFormat -contains 'yaml') { + # $Bundled + # | yayaml\ConvertTo-Yaml -Depth 99 + # | Out-File -FilePath "$OutputPathPrefix.yaml" + # } + # } + # if ($MergeForVSCode) { + # $Bundled = Merge-JsonSchema -Path $ConfigFile -ForVSCode + + # if ($OutputFormat -contains 'jsonVSCode') { + # ($Bundled | ConvertTo-Json -Depth 99) -replace '\b(\w+\.)yaml', '$1json' + # | Out-File -FilePath "$OutputPathPrefix.vscode.json" + # } + + # if ($OutputFormat -contains 'yamlVSCode') { + # $Bundled + # | yayaml\ConvertTo-Yaml -Depth 99 + # | Out-File -FilePath "$OutputPathPrefix.vscode.yaml" -Force:$Force + # } + # } + } +} + +end { + +} \ No newline at end of file diff --git a/docs/schemas/bundle.config.yaml b/docs/schemas/bundle.config.yaml new file mode 100644 index 000000000..0ea0c40b8 --- /dev/null +++ b/docs/schemas/bundle.config.yaml @@ -0,0 +1,42 @@ +bundle_schemas: + # Resource manifest bundle + - ConfigFilePath: resource/manifest.yaml + Name: resource.manifest + OutputFormat: ['Json', 'JsonVSCode', 'Yaml', 'YamlVSCode'] + + # Configuration document bundle + - ConfigFilePath: config/document.yaml + Name: config.document + OutputFormat: ['Json', 'JsonVSCode', 'Yaml', 'YamlVSCode'] + + # Output schema bundles + - ConfigFilePath: outputs/schema.yaml + Name: outputs.schema + OutputFormat: ['Json'] + - ConfigFilePath: outputs/config/get.yaml + Name: outputs.config.get + OutputFormat: ['Json'] + - ConfigFilePath: outputs/config/set.yaml + Name: outputs.config.set + OutputFormat: ['Json'] + - ConfigFilePath: outputs/config/test.yaml + Name: outputs.config.test + OutputFormat: ['Json'] + - ConfigFilePath: outputs/config/validate.yaml + Name: outputs.config.validate + OutputFormat: ['Json'] + - ConfigFilePath: outputs/resource/get.yaml + Name: outputs.resource.get + OutputFormat: ['Json'] + - ConfigFilePath: outputs/resource/list.yaml + Name: outputs.resource.list + OutputFormat: ['Json'] + - ConfigFilePath: outputs/resource/schema.yaml + Name: outputs.resource.schema + OutputFormat: ['Json'] + - ConfigFilePath: outputs/resource/set.yaml + Name: outputs.resource.set + OutputFormat: ['Json'] + - ConfigFilePath: outputs/resource/test.yaml + Name: outputs.resource.test + OutputFormat: ['Json'] diff --git a/docs/schemas/bundled/config.document.json b/docs/schemas/bundled/config.document.json new file mode 100644 index 000000000..bc86c8adf --- /dev/null +++ b/docs/schemas/bundled/config.document.json @@ -0,0 +1,247 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/config.document.json", + "title": "DSC Configuration Document schema", + "description": "Describes a valid DSC Configuration Document.", + "type": "object", + "required": [ + "$schema", + "resources" + ], + "properties": { + "$schema": { + "title": "Schema", + "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://schemas.microsoft.com/dsc/2023/07/config/document.json" + ] + }, + "parameters": { + "$ref": "/dsc/2023/07/config/document.parameters.json" + }, + "variables": { + "title": "Configuration variables", + "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", + "type": "object" + }, + "resources": { + "$ref": "/dsc/2023/07/config/document.resources.json" + }, + "metadata": { + "title": "Configuration metadata", + "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", + "type": "object" + } + }, + "$defs": { + "https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.json", + "title": "DSC Configuration document parameters", + "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "type": "object", + "patternProperties": { + ".": { + "title": "Parameter", + "description": "Defines a runtime option for a DSC Configuration Document.", + "type": "object", + "required": [ + "type" + ], + "properties": { + "type": { + "$ref": "/dsc/2023/07/definitions/parameters/dataType.json" + }, + "defaultValue": { + "title": "Default value", + "description": "Defines the default value for the parameter.", + "$ref": "/dsc/2023/07/definitions/parameters/validValueTypes.json" + }, + "allowedValues": { + "title": "Allowed values", + "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", + "type": "array", + "items": { + "$ref": "/dsc/2023/07/definitions/parameters/validValueTypes.json" + } + }, + "description": { + "title": "Parameter description", + "description": "Defines a synopsis for the parameter explaining its purpose.", + "type": "string" + }, + "metadata": { + "title": "Parameter metadata", + "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", + "type": "object" + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "$ref": "/dsc/2023/07/definitions/parameters/integerValidationProperties.json" + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + }, + { + "properties": { + "type": { + "const": "array" + } + } + } + ] + }, + "then": { + "$ref": "/dsc/2023/07/definitions/parameters/lengthValidationProperties.json" + } + } + ] + } + } + }, + "https://schemas.microsoft.com/dsc/2023/07/config/document.resources.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/config/document.resources.json", + "title": "DSC Configuration document resources", + "description": "Defines a list of DSC Resource instances for the configuration to manage.", + "type": "array", + "items": { + "title": "DSC Resource instance", + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "$ref": "/dsc/2023/07/definitions/resourceType.json" + }, + "name": { + "$ref": "/dsc/2023/07/definitions/instanceName.json" + }, + "dependsOn": { + "title": "Instance depends on", + "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", + "type": "array", + "items": { + "type": "string", + "uniqueItems": true + } + }, + "properties": { + "title": "Managed instance properties", + "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", + "type": "object" + } + } + } + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataType.json", + "title": "Data Type", + "description": "Defines the data type for the value.", + "type": "string", + "enum": [ + "string", + "securestring", + "int", + "bool", + "object", + "secureobject", + "array" + ] + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/validValueTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/validValueTypes.json", + "$comment": "This schema fragment makes it a little easier to compose the valid properties\nfor DSC Configuration document parameters. As-written, values must be one of\nthose on this list - the schema definition for dataType excludes `null` and\nnumbers with fractional parts, like `3.5`.\n", + "type": [ + "string", + "integer", + "object", + "array", + "boolean" + ] + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/integerValidationProperties.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/integerValidationProperties.json", + "$comment": "This schema fragment makes it a little easier to compose the valid properties\nfor DSC Configuration document parameters. These only apply to `int` type\nparameters.\n", + "properties": { + "minValue": { + "title": "Minimum value", + "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", + "type": "integer", + "minimum": 0 + }, + "maxValue": { + "title": "Maximum value", + "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", + "type": "integer", + "minimum": 0 + } + } + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/lengthValidationProperties.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/lengthValidationProperties.json", + "$comment": "This schema fragment makes it a little easier to compose the valid properties\nfor DSC Configuration document parameters. These only apply to `string`,\n`securestring`, and `array` type parameters.\n", + "properties": { + "minLength": { + "title": "Minimum length", + "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", + "type": "integer", + "minimum": 0 + }, + "maxLength": { + "title": "Maximum length", + "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", + "type": "integer", + "minimum": 0 + } + } + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" + } + } +} diff --git a/docs/schemas/bundled/config.document.vscode.json b/docs/schemas/bundled/config.document.vscode.json new file mode 100644 index 000000000..86fc9159c --- /dev/null +++ b/docs/schemas/bundled/config.document.vscode.json @@ -0,0 +1,259 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/config.document.json", + "title": "DSC Configuration Document schema", + "description": "Describes a valid DSC Configuration Document.", + "type": "object", + "required": [ + "$schema", + "resources" + ], + "properties": { + "$schema": { + "title": "Schema", + "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://schemas.microsoft.com/dsc/2023/07/config/document.json" + ] + }, + "parameters": { + "$ref": "#/$defs/dsc/2023/07/config/document.parameters.json" + }, + "variables": { + "title": "Configuration variables", + "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", + "type": "object" + }, + "resources": { + "$ref": "#/$defs/dsc/2023/07/config/document.resources.json" + }, + "metadata": { + "title": "Configuration metadata", + "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", + "type": "object" + } + }, + "$defs": { + "dsc": { + "2023": { + "07": { + "config": { + "document.parameters.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.json", + "title": "DSC Configuration document parameters", + "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "type": "object", + "patternProperties": { + ".": { + "title": "Parameter", + "description": "Defines a runtime option for a DSC Configuration Document.", + "type": "object", + "required": [ + "type" + ], + "properties": { + "type": { + "$ref": "#/$defs/dsc/2023/07/definitions/parameters/dataType.json" + }, + "defaultValue": { + "title": "Default value", + "description": "Defines the default value for the parameter.", + "$ref": "#/$defs/dsc/2023/07/definitions/parameters/validValueTypes.json" + }, + "allowedValues": { + "title": "Allowed values", + "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", + "type": "array", + "items": { + "$ref": "#/$defs/dsc/2023/07/definitions/parameters/validValueTypes.json" + } + }, + "description": { + "title": "Parameter description", + "description": "Defines a synopsis for the parameter explaining its purpose.", + "type": "string" + }, + "metadata": { + "title": "Parameter metadata", + "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", + "type": "object" + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "$ref": "#/$defs/dsc/2023/07/definitions/parameters/integerValidationProperties.json" + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + }, + { + "properties": { + "type": { + "const": "array" + } + } + } + ] + }, + "then": { + "$ref": "#/$defs/dsc/2023/07/definitions/parameters/lengthValidationProperties.json" + } + } + ] + } + } + }, + "document.resources.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/config/document.resources.json", + "title": "DSC Configuration document resources", + "description": "Defines a list of DSC Resource instances for the configuration to manage.", + "type": "array", + "items": { + "title": "DSC Resource instance", + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "$ref": "#/$defs/dsc/2023/07/definitions/resourceType.json" + }, + "name": { + "$ref": "#/$defs/dsc/2023/07/definitions/instanceName.json" + }, + "dependsOn": { + "title": "Instance depends on", + "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", + "type": "array", + "items": { + "type": "string", + "uniqueItems": true + } + }, + "properties": { + "title": "Managed instance properties", + "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", + "type": "object" + } + } + } + } + }, + "definitions": { + "parameters": { + "dataType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataType.json", + "title": "Data Type", + "description": "Defines the data type for the value.", + "type": "string", + "enum": [ + "string", + "securestring", + "int", + "bool", + "object", + "secureobject", + "array" + ] + }, + "validValueTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/validValueTypes.json", + "$comment": "This schema fragment makes it a little easier to compose the valid properties\nfor DSC Configuration document parameters. As-written, values must be one of\nthose on this list - the schema definition for dataType excludes `null` and\nnumbers with fractional parts, like `3.5`.\n", + "type": [ + "string", + "integer", + "object", + "array", + "boolean" + ] + }, + "integerValidationProperties.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/integerValidationProperties.json", + "$comment": "This schema fragment makes it a little easier to compose the valid properties\nfor DSC Configuration document parameters. These only apply to `int` type\nparameters.\n", + "properties": { + "minValue": { + "title": "Minimum value", + "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", + "type": "integer", + "minimum": 0 + }, + "maxValue": { + "title": "Maximum value", + "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", + "type": "integer", + "minimum": 0 + } + } + }, + "lengthValidationProperties.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/lengthValidationProperties.json", + "$comment": "This schema fragment makes it a little easier to compose the valid properties\nfor DSC Configuration document parameters. These only apply to `string`,\n`securestring`, and `array` type parameters.\n", + "properties": { + "minLength": { + "title": "Minimum length", + "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", + "type": "integer", + "minimum": 0 + }, + "maxLength": { + "title": "Maximum length", + "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", + "type": "integer", + "minimum": 0 + } + } + } + }, + "resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" + } + } + } + } + } + } +} diff --git a/docs/schemas/bundled/config.document.vscode.yaml b/docs/schemas/bundled/config.document.vscode.yaml new file mode 100644 index 000000000..9316a0dda --- /dev/null +++ b/docs/schemas/bundled/config.document.vscode.yaml @@ -0,0 +1,211 @@ +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/bundled/config.document.yaml +title: DSC Configuration Document schema +description: Describes a valid DSC Configuration Document. +type: object +required: +- $schema +- resources +properties: + $schema: + title: Schema + description: This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for. + type: string + format: uri + enum: + - https://schemas.microsoft.com/dsc/2023/07/config/document.yaml + parameters: + $ref: '#/$defs/dsc/2023/07/config/document.parameters.yaml' + variables: + title: Configuration variables + description: Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value. + type: object + resources: + $ref: '#/$defs/dsc/2023/07/config/document.resources.yaml' + metadata: + title: Configuration metadata + description: Defines a set of key-value pairs for the configuration. This metadata isn't validated. + type: object +$defs: + dsc: + "2023": + "07": + config: + document.parameters.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.yaml + title: DSC Configuration document parameters + description: Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration. + type: object + patternProperties: + .: + title: Parameter + description: Defines a runtime option for a DSC Configuration Document. + type: object + required: + - type + properties: + type: + $ref: '#/$defs/dsc/2023/07/definitions/parameters/dataType.yaml' + defaultValue: + title: Default value + description: Defines the default value for the parameter. + $ref: '#/$defs/dsc/2023/07/definitions/parameters/validValueTypes.yaml' + allowedValues: + title: Allowed values + description: Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid. + type: array + items: + $ref: '#/$defs/dsc/2023/07/definitions/parameters/validValueTypes.yaml' + description: + title: Parameter description + description: Defines a synopsis for the parameter explaining its purpose. + type: string + metadata: + title: Parameter metadata + description: Defines a set of key-value pairs for the parameter. This metadata isn't validated. + type: object + allOf: + - if: + properties: + type: + const: int + then: + $ref: '#/$defs/dsc/2023/07/definitions/parameters/integerValidationProperties.yaml' + - if: + oneOf: + - properties: + type: + const: string + - properties: + type: + const: securestring + - properties: + type: + const: array + then: + $ref: '#/$defs/dsc/2023/07/definitions/parameters/lengthValidationProperties.yaml' + document.resources.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/config/document.resources.yaml + title: DSC Configuration document resources + description: Defines a list of DSC Resource instances for the configuration to manage. + type: array + items: + title: DSC Resource instance + type: object + required: + - type + - name + properties: + type: + $ref: '#/$defs/dsc/2023/07/definitions/resourceType.yaml' + name: + $ref: '#/$defs/dsc/2023/07/definitions/instanceName.yaml' + dependsOn: + title: Instance depends on + description: Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property. + type: array + items: + type: string + uniqueItems: true + properties: + title: Managed instance properties + description: Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema. + type: object + definitions: + parameters: + dataType.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataType.yaml + title: Data Type + description: Defines the data type for the value. + type: string + enum: + - string + - securestring + - int + - bool + - object + - secureobject + - array + validValueTypes.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/validValueTypes.yaml + $comment: > + This schema fragment makes it a little easier to compose the valid properties + + for DSC Configuration document parameters. As-written, values must be one of + + those on this list - the schema definition for dataType excludes `null` and + + numbers with fractional parts, like `3.5`. + type: + - string + - integer + - object + - array + - boolean + integerValidationProperties.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/integerValidationProperties.yaml + $comment: > + This schema fragment makes it a little easier to compose the valid properties + + for DSC Configuration document parameters. These only apply to `int` type + + parameters. + properties: + minValue: + title: Minimum value + description: The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`. + type: integer + minimum: 0 + maxValue: + title: Maximum value + description: The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`. + type: integer + minimum: 0 + lengthValidationProperties.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/lengthValidationProperties.yaml + $comment: > + This schema fragment makes it a little easier to compose the valid properties + + for DSC Configuration document parameters. These only apply to `string`, + + `securestring`, and `array` type parameters. + properties: + minLength: + title: Minimum length + description: The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`. + type: integer + minimum: 0 + maxLength: + title: Maximum length + description: The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`. + type: integer + minimum: 0 + resourceType.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml + title: DSC Resource fully qualified type name + description: > + The namespaced name of the DSC Resource, using the syntax: + + + owner[.group][.area]/name + + + For example: + + - Microsoft.SqlServer/Database + - Microsoft.SqlServer.Database/User + type: string + pattern: ^\w+(\.\w+){0,2}\/\w+$ + instanceName.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.yaml + title: Instance name + description: The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. + type: string diff --git a/docs/schemas/bundled/config.document.yaml b/docs/schemas/bundled/config.document.yaml index 56a4d051b..1b3c83161 100644 --- a/docs/schemas/bundled/config.document.yaml +++ b/docs/schemas/bundled/config.document.yaml @@ -1,224 +1,205 @@ -# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema -$schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/bundled/config.document.yaml - -title: DSC Configuration Document schema -description: >- - Describes a valid DSC Configuration Document. - -type: object -required: - - $schema - - resources -properties: - $schema: - title: Schema - description: >- - This property must be the canonical URL of the DSC Configuration Document - schema that the document is implemented for. - type: string - format: uri - enum: - - https://schemas.microsoft.com/dsc/2023/07/config/document.yaml - - parameters: - $ref: /dsc/2023/07/config/document.parameters.yaml - - variables: - title: Configuration variables - description: >- - Defines a set of reusable values for the configuration document. The - names of this value's properties are the strings used to reference a - variable's value. - type: object - - resources: - $ref: /dsc/2023/07/config/document.resources.yaml - - metadata: - title: Configuration metadata - description: >- - Defines a set of key-value pairs for the configuration. This metadata - isn't validated. - type: object - -$defs: - https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.yaml - title: DSC Configuration document parameters - description: >- - Defines runtime options for the configuration. Users and integrating tools - can override use the defined parameters to pass alternate values to the - configuration. - type: object - patternProperties: - ".": - title: Parameter - description: >- - Defines a runtime option for a DSC Configuration Document. - type: object - required: - - type - properties: - type: - $ref: /dsc/2023/07/definitions/dataType.yaml - defaultValue: - title: Default value - description: >- - Defines the default value for the parameter. - $ref: "#/$defs/ValidValueTypes" - allowedValues: - title: Allowed values - description: >- - Defines a list of valid values for the parameter. If the - parameter is defined with any other values, it's invalid. - type: array - items: - $ref: "#/$defs/ValidValueTypes" - description: - title: Parameter description - description: >- - Defines a synopsis for the parameter explaining its purpose. - type: string - metadata: - title: Parameter metadata - description: >- - Defines a set of key-value pairs for the parameter. This metadata - isn't validated. - type: object - allOf: - - if: - properties: - type: - const: int - then: - $ref: "#/$defs/IntegerValidationProperties" - - if: - oneOf: - - properties: { type: { const: string } } - - properties: { type: { const: securestring } } - - properties: { type: { const: array } } - then: - $ref: "#/$defs/LengthValidationProperties" - $defs: - ValidValueTypes: - type: - - string - - integer - - object - - array - - boolean - IntegerValidationProperties: - properties: - minValue: - title: Minimum value - description: >- - The minimum valid value for an integer type. If defined with the - `maxValue` property, this value must be less than the value of - `maxValue`. - type: integer - minimum: 0 - maxValue: - title: Maximum value - description: >- - The maximum valid value for an integer type. If defined with the - `minValue` property, this value must be greater than the value of - `minValue`. - type: integer - minimum: 0 - LengthValidationProperties: - properties: - minLength: - title: Minimum length - description: >- - The minimum valid length for a `string`, `securestring`, or `array`. - If defined with the `maxLength` property, this value must be less - than the value of `maxLength`. - type: integer - minimum: 0 - maxLength: - title: Maximum length - description: >- - The maximum valid length for a `string`, `securestring`, or `array`. - If defined with the `minLength` property, this value must be less - than the value of `minLength`. - type: integer - minimum: 0 - - https://schemas.microsoft.com/dsc/2023/07/config/document.resources.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/config/document.resources.yaml - title: DSC Configuration document resources - description: >- - Defines a list of DSC Resource instances for the configuration to manage. - type: array - items: - title: DSC Resource instance - type: object - required: - - type - - name - properties: - type: - $ref: /dsc/2023/07/definitions/resourceType.yaml - name: - $ref: /dsc/2023/07/definitions/instanceName.yaml - dependsOn: - title: Instance depends on - description: >- - Defines a list of DSC Resource instances that DSC must successfully - process before processing this instance. Each value for this property - must be the value of another DSC Resource instance's `name` property. - type: array - items: - type: string - uniqueItems: true - properties: - title: Managed instance properties - description: >- - Defines the properties of the DSC Resource this instance manages. This - property's value must be an object. DSC validates the property's value - against the DSC Resource's schema. - type: object - - https://schemas.microsoft.com/dsc/2023/07/definitions/dataType.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/dataType.yaml - title: Data Type - description: >- - Defines the data type for the value. - type: string - enum: - - string - - securestring - - int - - bool - - object - - secureobject - - array - - https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.yaml - title: Instance name - description: >- - The short, human-readable name for a DSC Resource instance. Must be unique - within a DSC Configuration document. - type: string - - https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml - title: DSC Resource fully qualified type name - description: | - The namespaced name of the DSC Resource, using the syntax: - - [.][.]/ - - For example: - - - Microsoft.SqlServer/Database - - Microsoft.SqlServer.Database/User - type: string - pattern: ^\w+(\.\w+){0,2}\/\w+$ +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/bundled/config.document.yaml +title: DSC Configuration Document schema +description: Describes a valid DSC Configuration Document. +type: object +required: +- $schema +- resources +properties: + $schema: + title: Schema + description: This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for. + type: string + format: uri + enum: + - https://schemas.microsoft.com/dsc/2023/07/config/document.yaml + parameters: + $ref: /dsc/2023/07/config/document.parameters.yaml + variables: + title: Configuration variables + description: Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value. + type: object + resources: + $ref: /dsc/2023/07/config/document.resources.yaml + metadata: + title: Configuration metadata + description: Defines a set of key-value pairs for the configuration. This metadata isn't validated. + type: object +$defs: + https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.yaml + title: DSC Configuration document parameters + description: Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration. + type: object + patternProperties: + .: + title: Parameter + description: Defines a runtime option for a DSC Configuration Document. + type: object + required: + - type + properties: + type: + $ref: /dsc/2023/07/definitions/parameters/dataType.yaml + defaultValue: + title: Default value + description: Defines the default value for the parameter. + $ref: /dsc/2023/07/definitions/parameters/validValueTypes.yaml + allowedValues: + title: Allowed values + description: Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid. + type: array + items: + $ref: /dsc/2023/07/definitions/parameters/validValueTypes.yaml + description: + title: Parameter description + description: Defines a synopsis for the parameter explaining its purpose. + type: string + metadata: + title: Parameter metadata + description: Defines a set of key-value pairs for the parameter. This metadata isn't validated. + type: object + allOf: + - if: + properties: + type: + const: int + then: + $ref: /dsc/2023/07/definitions/parameters/integerValidationProperties.yaml + - if: + oneOf: + - properties: + type: + const: string + - properties: + type: + const: securestring + - properties: + type: + const: array + then: + $ref: /dsc/2023/07/definitions/parameters/lengthValidationProperties.yaml + https://schemas.microsoft.com/dsc/2023/07/config/document.resources.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/config/document.resources.yaml + title: DSC Configuration document resources + description: Defines a list of DSC Resource instances for the configuration to manage. + type: array + items: + title: DSC Resource instance + type: object + required: + - type + - name + properties: + type: + $ref: /dsc/2023/07/definitions/resourceType.yaml + name: + $ref: /dsc/2023/07/definitions/instanceName.yaml + dependsOn: + title: Instance depends on + description: Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property. + type: array + items: + type: string + uniqueItems: true + properties: + title: Managed instance properties + description: Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema. + type: object + https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataType.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataType.yaml + title: Data Type + description: Defines the data type for the value. + type: string + enum: + - string + - securestring + - int + - bool + - object + - secureobject + - array + https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/validValueTypes.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/validValueTypes.yaml + $comment: > + This schema fragment makes it a little easier to compose the valid properties + + for DSC Configuration document parameters. As-written, values must be one of + + those on this list - the schema definition for dataType excludes `null` and + + numbers with fractional parts, like `3.5`. + type: + - string + - integer + - object + - array + - boolean + https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/integerValidationProperties.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/integerValidationProperties.yaml + $comment: > + This schema fragment makes it a little easier to compose the valid properties + + for DSC Configuration document parameters. These only apply to `int` type + + parameters. + properties: + minValue: + title: Minimum value + description: The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`. + type: integer + minimum: 0 + maxValue: + title: Maximum value + description: The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`. + type: integer + minimum: 0 + https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/lengthValidationProperties.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/lengthValidationProperties.yaml + $comment: > + This schema fragment makes it a little easier to compose the valid properties + + for DSC Configuration document parameters. These only apply to `string`, + + `securestring`, and `array` type parameters. + properties: + minLength: + title: Minimum length + description: The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`. + type: integer + minimum: 0 + maxLength: + title: Maximum length + description: The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`. + type: integer + minimum: 0 + https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml + title: DSC Resource fully qualified type name + description: > + The namespaced name of the DSC Resource, using the syntax: + + + owner[.group][.area]/name + + + For example: + + - Microsoft.SqlServer/Database + - Microsoft.SqlServer.Database/User + type: string + pattern: ^\w+(\.\w+){0,2}\/\w+$ + https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.yaml + title: Instance name + description: The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. + type: string diff --git a/docs/schemas/bundled/example.gotstoy.resource.json b/docs/schemas/bundled/example.gotstoy.resource.json new file mode 100644 index 000000000..37eae0e85 --- /dev/null +++ b/docs/schemas/bundled/example.gotstoy.resource.json @@ -0,0 +1,65 @@ +{ + "$schema": "resource.manifest.vscode.json", + "manifestVersion": "1.0", + "type": "TSToy.Example/gotstoy", + "version": "0.1.0", + "description": "The go implementation of a DSC Resource for the fictional TSToy application.", + "get": { + "executable": "gotstoy", + "args": ["get"], + "input": "stdin" + }, + "set": { + "executable": "gotstoy", + "args": ["set"], + "input": "stdin", + "preTest": false, + "return": "state" + }, + "schema": { + "embedded": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "title": "Golang TSToy Resource", + "type": "object", + "required": [ + "scope" + ], + "properties": { + "ensure": { + "title": "Ensure configuration file existence", + "description": "Defines whether the application's configuration file for this scope should exist or not.", + "type": "string", + "enum": [ + "present", + "absent" + ], + "default": "present" + }, + "scope": { + "title": "Target configuration scope", + "description": "Defines which of the application's configuration files the resource should manage.", + "type": "string", + "enum": [ + "machine", + "user" + ] + }, + "updateAutomatically": { + "title": "Should update automatically", + "description": "Indicates whether the application should check for updates when it starts.", + "type": "boolean" + }, + "updateFrequency": { + "title": "Update check frequency", + "description": "Indicates how many days the application should wait before checking for updates.", + "type": "integer", + "minimum": 1, + "maximum": 90 + }, + "_ensure": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json" + } + } + } + } +} diff --git a/docs/schemas/bundled/example.gotstoy.resource.yaml b/docs/schemas/bundled/example.gotstoy.resource.yaml new file mode 100644 index 000000000..da575f64a --- /dev/null +++ b/docs/schemas/bundled/example.gotstoy.resource.yaml @@ -0,0 +1,55 @@ +# yaml-language-server: $schema=resource.manifest.vscode.yaml +manifestVersion: '1.0.0' +type: TSToy.Example/gotstoy +version: 0.1.0 +description: The go implementation of a DSC Resource for the fictional TSToy application. +get: + executable: gotstoy + args: + - get + input: stdin +set: + executable: gotstoy + args: + - set + input: stdin + preTest: false + return: state +schema: + embedded: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://tailspintoys.com/schemas/gotstoy + title: Golang TSToy Resource + type: object + required: + - scope + properties: + ensure: + title: Ensure configuration file existence + description: Defines whether the application's configuration file for this + scope should exist or not. + type: string + enum: + - present + - absent + default: present + scope: + title: Target configuration scope + description: Defines which of the application's configuration files the resource + should manage. + type: string + enum: + - machine + - user + updateAutomatically: + title: Should update automatically + description: Indicates whether the application should check for updates when + it starts. + type: boolean + updateFrequency: + title: Update check frequency + description: Indicates how many days the application should wait before checking + for updates. + type: integer + minimum: 1 + maximum: 90 diff --git a/docs/schemas/bundled/manual.config.document.yaml b/docs/schemas/bundled/manual.config.document.yaml new file mode 100644 index 000000000..3de84cbd0 --- /dev/null +++ b/docs/schemas/bundled/manual.config.document.yaml @@ -0,0 +1,224 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/bundled/config.document.yaml + +title: DSC Configuration Document schema +description: >- + Describes a valid DSC Configuration Document. + +type: object +required: + - $schema + - resources +properties: + $schema: + title: Schema + description: >- + This property must be the canonical URL of the DSC Configuration Document + schema that the document is implemented for. + type: string + format: uri + enum: + - https://schemas.microsoft.com/dsc/2023/07/config/document.yaml + + parameters: + $ref: /dsc/2023/07/config/document.parameters.yaml + + variables: + title: Configuration variables + description: >- + Defines a set of reusable values for the configuration document. The + names of this value's properties are the strings used to reference a + variable's value. + type: object + + resources: + $ref: /dsc/2023/07/config/document.resources.yaml + + metadata: + title: Configuration metadata + description: >- + Defines a set of key-value pairs for the configuration. This metadata + isn't validated. + type: object + +$defs: + https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.yaml + title: DSC Configuration document parameters + description: >- + Defines runtime options for the configuration. Users and integrating tools + can override use the defined parameters to pass alternate values to the + configuration. + type: object + patternProperties: + ".": + title: Parameter + description: >- + Defines a runtime option for a DSC Configuration Document. + type: object + required: + - type + properties: + type: + $ref: /dsc/2023/07/definitions/parameters/dataType.yaml + defaultValue: + title: Default value + description: >- + Defines the default value for the parameter. + $ref: "#/$defs/ValidValueTypes" + allowedValues: + title: Allowed values + description: >- + Defines a list of valid values for the parameter. If the + parameter is defined with any other values, it's invalid. + type: array + items: + $ref: "#/$defs/ValidValueTypes" + description: + title: Parameter description + description: >- + Defines a synopsis for the parameter explaining its purpose. + type: string + metadata: + title: Parameter metadata + description: >- + Defines a set of key-value pairs for the parameter. This metadata + isn't validated. + type: object + allOf: + - if: + properties: + type: + const: int + then: + $ref: "#/$defs/IntegerValidationProperties" + - if: + oneOf: + - properties: { type: { const: string } } + - properties: { type: { const: securestring } } + - properties: { type: { const: array } } + then: + $ref: "#/$defs/LengthValidationProperties" + $defs: + ValidValueTypes: + type: + - string + - integer + - object + - array + - boolean + IntegerValidationProperties: + properties: + minValue: + title: Minimum value + description: >- + The minimum valid value for an integer type. If defined with the + `maxValue` property, this value must be less than the value of + `maxValue`. + type: integer + minimum: 0 + maxValue: + title: Maximum value + description: >- + The maximum valid value for an integer type. If defined with the + `minValue` property, this value must be greater than the value of + `minValue`. + type: integer + minimum: 0 + LengthValidationProperties: + properties: + minLength: + title: Minimum length + description: >- + The minimum valid length for a `string`, `securestring`, or `array`. + If defined with the `maxLength` property, this value must be less + than the value of `maxLength`. + type: integer + minimum: 0 + maxLength: + title: Maximum length + description: >- + The maximum valid length for a `string`, `securestring`, or `array`. + If defined with the `minLength` property, this value must be less + than the value of `minLength`. + type: integer + minimum: 0 + + https://schemas.microsoft.com/dsc/2023/07/config/document.resources.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/config/document.resources.yaml + title: DSC Configuration document resources + description: >- + Defines a list of DSC Resource instances for the configuration to manage. + type: array + items: + title: DSC Resource instance + type: object + required: + - type + - name + properties: + type: + $ref: /dsc/2023/07/definitions/resourceType.yaml + name: + $ref: /dsc/2023/07/definitions/instanceName.yaml + dependsOn: + title: Instance depends on + description: >- + Defines a list of DSC Resource instances that DSC must successfully + process before processing this instance. Each value for this property + must be the value of another DSC Resource instance's `name` property. + type: array + items: + type: string + uniqueItems: true + properties: + title: Managed instance properties + description: >- + Defines the properties of the DSC Resource this instance manages. This + property's value must be an object. DSC validates the property's value + against the DSC Resource's schema. + type: object + + https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataType.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataType.yaml + title: Data Type + description: >- + Defines the data type for the value. + type: string + enum: + - string + - securestring + - int + - bool + - object + - secureobject + - array + + https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.yaml + title: Instance name + description: >- + The short, human-readable name for a DSC Resource instance. Must be unique + within a DSC Configuration document. + type: string + + https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml + title: DSC Resource fully qualified type name + description: | + The namespaced name of the DSC Resource, using the syntax: + + [.][.]/ + + For example: + + - Microsoft.SqlServer/Database + - Microsoft.SqlServer.Database/User + type: string + pattern: ^\w+(\.\w+){0,2}\/\w+$ diff --git a/docs/schemas/bundled/manual.resource.manifest.yaml b/docs/schemas/bundled/manual.resource.manifest.yaml new file mode 100644 index 000000000..e345c5f9e --- /dev/null +++ b/docs/schemas/bundled/manual.resource.manifest.yaml @@ -0,0 +1,337 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/bundled/resource.manifest.yaml + +title: Command-based DSC Resource Manifest +description: >- + Defines a valid command-based DSC Resource. + +type: object +required: + - manifestVersion + - type + - version + - get +properties: + manifestVersion: + title: Manifest Version + description: >- + The semver of the DSC Resource manifest schema to validate this manifest + with. + $ref: /dsc/2023/07/definitions/semver.yaml + enums: + - '1.0' + type: + $ref: /dsc/2023/07/definitions/resourceType.yaml + version: + title: Resource Semantic Version + description: >- + The semantic version (semver) of the DSC Resource. This version + identifies the DSC Resource, not the version of the application it + manages. + $ref: /dsc/2023/07/definitions/semver.yaml + description: + title: Resource Description + description: >- + A short synopsis of the DSC Resource's purpose. + # Should this include a maximum length or a pattern that forbids newlines? + type: string + tags: + title: Tags + description: >- + An array of short strings used to search for DSC Resources. + type: array + items: + type: string + pattern: ^\w+$ + get: + $ref: "$defs/dsc/2023/07/resource/manifest.get.yaml" + # $ref: /dsc/2023/07/resource/manifest.get.yaml + set: + $ref: /dsc/2023/07/resource/manifest.set.yaml + test: + $ref: /dsc/2023/07/resource/manifest.test.yaml + validate: + $ref: /dsc/2023/07/resource/manifest.validate.yaml + provider: + # I'm not clear on how this works in practice + $ref: /dsc/2023/07/resource/manifest.provider.yaml + exitCodes: + # This setting in the root of the schema implies exit codes must have the + # same meaning across all executions. What about implementations that + # support multiple executables? Should exitCodes be a key that exists on + # command/method objects too? + title: Exit Codes + description: >- + This property defines a map of valid exit codes for the DSC Resource. + DSC always interprets exit code `0` as a successful operation and any + other exit code as an error. Use this property to indicate human-readable + semantic meanings for the DSC Resource's exit codes. + type: object + propertyNames: + pattern: "^[0-9]+$" + patternProperties: + "^[0-9]+$": + type: string + examples: + - exitCodes: + "0": Success + "1": Invalid parameter + "2": Invalid input + "3": Registry error + "4": JSON serialization failed + schema: + $ref: /dsc/2023/07/resource/manifest.schema.yaml + +$defs: + https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.yaml + title: Executable Command Arguments + description: >- + The list of arguments to pass to the command. + type: array + items: + type: string + + https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.yaml + title: Executable Command Name + description: >- + The name of the command to run. + type: string + + https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.yaml + title: Executable Command Input Type + description: >- + Defines how DSC should pass input to the command, either as arguments or + JSON over stdin. + type: string + enum: + - args + - stdin + default: args + + https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml + title: DSC Resource fully qualified type name + description: | + The namespaced name of the DSC Resource, using the syntax: + + [.][.]/ + + For example: + + - Microsoft.SqlServer/Database + - Microsoft.SqlServer.Database/User + type: string + pattern: ^\w+(\.\w+){0,2}\/\w+$ + + https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.yaml + title: Return Kind + type: string + enum: + - state + - stateAndDiff + default: state + + https://schemas.microsoft.com/dsc/2023/07/definitions/semver.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/semver.yaml + type: string + title: Semantic Version + description: >- + A valid semantic version (semver) string. For reference, see https://semver.org/ + pattern: >- + ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ + + /dsc/2023/07/resource/manifest.get.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.yaml + title: Get Method + description: >- + Defines how DSC must call the DSC Resource to get the current state of an + instance. + type: object + required: + - executable + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + input: + $ref: /dsc/2023/07/definitions/inputKind.yaml + + https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.yaml + title: Provider + description: >- + Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider + enables users to manage resources that don't have their own manifests with + DSC. + type: object + required: + - list + - config + properties: + list: + title: List Command + description: >- + Defines how DSC must call the DSC Resource Provider to list its supported + DSC Resources. + type: object + required: + - executable + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + config: + title: Expected Configuration + description: >- + Defines whether the provider expects to receive a full and unprocessed + configuration as a single JSON blob over stdin or a sequence of JSON + Lines for each child resource's configurations. + type: string + enum: + - full + - sequence + + https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.yaml + title: Instance Schema + description: >- + Defines how DSC must validate a JSON blob representing an instance of the + DSC Resource. + type: object + oneOf: + - required: [command] + - required: [embedded] + properties: + command: + title: Instance Schema Command + description: >- + Defines how DSC must call the DSC Resource to get the JSON Schema for + validating a JSON blob representing an instance of the DSC Resource. + type: object + required: + - executable + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + embedded: + title: Embedded Instance Schema + description: >- + Defines the JSON Schema DSC must use to validate a JSON blob + representing an instance of the DSC Resource. + type: object + required: + - $schema + - $id + - properties + properties: + type: + const: object + $schema: + type: string + enum: + - https://json-schema.org/draft/2020-12/schema + - http://json-schema.org/draft-07/schema# + properties: + type: object + minProperties: 1 + unevaluatedProperties: + $ref: https://json-schema.org/draft/2020-12/schema + url: + title: Instance Schema URL + description: >- + Defines the URL to the DSC Resource's JSON schema for integrating tools. + type: string + format: uri + + https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.yaml + title: Set Method + description: >- + Defines how DSC must call the DSC Resource to set the desired state of + an instance and how to process the output from the DSC Resource. + type: object + required: + - executable + - input + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + input: + $ref: /dsc/2023/07/definitions/inputKind.yaml + preTest: + title: Resource Performs Pre-Test + description: >- + Defines whether the DSC Resource performs its own test to ensure + idempotency when calling the `set` command. Set this value to `true` + if the DSC Resource tests input before modifying system state. + type: boolean + default: false + return: + description: >- + Defines whether the command returns a JSON blob of the DSC Resource's + state after the set operation or the state and an array of the + properties the DSC Resource modified. + $ref: /dsc/2023/07/definitions/returnKind.yaml + + https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.yaml + title: Test Method + description: >- + Defines how DSC must call the DSC Resource to test if an instance is in + the desired state and how to process the output from the DSC Resource. + type: object + required: + - executable + - input + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + input: + $ref: /dsc/2023/07/definitions/inputKind.yaml + return: + title: Test Command Return Type + description: >- + Defines whether the command returns a JSON blob of the DSC Resource's current state or the + state and an array of the properties that are out of the desired state. + $ref: /dsc/2023/07/definitions/returnKind.yaml + + https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.yaml + title: Validate Method + description: >- + Defines how DSC must call the DSC Resource to validate the state of an + instance. This method is mandatory for DSC Group Resources. It's ignored for + all other DSC Resources. + type: object + required: + - executable + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml diff --git a/docs/schemas/bundled/outputs.config.get.json b/docs/schemas/bundled/outputs.config.get.json new file mode 100644 index 000000000..9e76e6a42 --- /dev/null +++ b/docs/schemas/bundled/outputs.config.get.json @@ -0,0 +1,135 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.config.get.json", + "title": "DSC Configuration get command result", + "description": "Represents the data structure returned by the `dsc config get` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `get` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "title": "Get Result", + "type": "object", + "required": [ + "name", + "type", + "result" + ], + "properties": { + "name": { + "$ref": "/dsc/2023/07/definitions/instanceName.json" + }, + "type": { + "$ref": "/dsc/2023/07/definitions/resourceType.json" + }, + "result": { + "$ref": "/dsc/2023/07/results/resource/get.json" + } + } + } + }, + "messages": { + "$ref": "/dsc/2023/07/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/dsc/2023/07/definitions/hadErrors.json" + } + }, + "$defs": { + "https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://schemas.microsoft.com/dsc/2023/07/results/resource/get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/results/resource/get.json", + "title": "DSC Resource get result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command.", + "type": "object", + "required": [ + "actual_state" + ], + "properties": { + "actual_state": { + "title": "The DSC Resource instance's current state", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + } + } + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/messages.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "/dsc/2023/07/definitions/message.json" + } + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/hadErrors.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/message.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/message.json", + "title": "Message", + "description": "A message emitted by a DSC Resource with associated metadata.", + "type": "object", + "required": [ + "name", + "type", + "message", + "level" + ], + "properties": { + "name": { + "title": "Message source instance name", + "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", + "type": "string" + }, + "type": { + "$ref": "/dsc/2023/07/definitions/resourceType.json" + }, + "message": { + "title": "Message content", + "description": "The actual content of the message as emitted by the DSC Resource.", + "type": "string", + "minLength": 1 + }, + "level": { + "title": "Message level", + "description": "Indicates the severity of the message.", + "type": "string", + "enum": [ + "Error", + "Warning", + "Information" + ] + } + } + } + } +} diff --git a/docs/schemas/bundled/outputs.config.set.json b/docs/schemas/bundled/outputs.config.set.json new file mode 100644 index 000000000..58d14c8e1 --- /dev/null +++ b/docs/schemas/bundled/outputs.config.set.json @@ -0,0 +1,151 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.config.set.json", + "title": "DSC Configuration set command result", + "description": "Represents the data structure returned by the `dsc config set` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `set` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "title": "Set Result", + "type": "object", + "required": [ + "name", + "type", + "result" + ], + "properties": { + "name": { + "$ref": "/dsc/2023/07/definitions/instanceName.json" + }, + "type": { + "$ref": "/dsc/2023/07/definitions/resourceType.json" + }, + "result": { + "$ref": "/dsc/2023/07/results/resource/set.json" + } + } + } + }, + "messages": { + "$ref": "/dsc/2023/07/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/dsc/2023/07/definitions/hadErrors.json" + } + }, + "$defs": { + "https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://schemas.microsoft.com/dsc/2023/07/results/resource/set.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/results/resource/set.json", + "title": "DSC Resource set result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command.", + "type": "object", + "required": [ + "before_state", + "after_state", + "changed_properties" + ], + "properties": { + "before_state": { + "title": "State before enforcing", + "description": "This property always represents the desired state of the DSC Resource instance before the `set` method runs. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "after_state": { + "title": "State after enforcing", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `set` method after enforcing the desired state. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "changed_properties": { + "title": "Changed Properties", + "description": "This property always represents the list of property names for the DSC Resource instance that the `set` method modified. When this value is an empty array, the `set` method didn't enforce any properties for the instance.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } + } + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/messages.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "/dsc/2023/07/definitions/message.json" + } + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/hadErrors.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/message.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/message.json", + "title": "Message", + "description": "A message emitted by a DSC Resource with associated metadata.", + "type": "object", + "required": [ + "name", + "type", + "message", + "level" + ], + "properties": { + "name": { + "title": "Message source instance name", + "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", + "type": "string" + }, + "type": { + "$ref": "/dsc/2023/07/definitions/resourceType.json" + }, + "message": { + "title": "Message content", + "description": "The actual content of the message as emitted by the DSC Resource.", + "type": "string", + "minLength": 1 + }, + "level": { + "title": "Message level", + "description": "Indicates the severity of the message.", + "type": "string", + "enum": [ + "Error", + "Warning", + "Information" + ] + } + } + } + } +} diff --git a/docs/schemas/bundled/outputs.config.test.json b/docs/schemas/bundled/outputs.config.test.json new file mode 100644 index 000000000..cc14bdf98 --- /dev/null +++ b/docs/schemas/bundled/outputs.config.test.json @@ -0,0 +1,151 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.config.test.json", + "title": "DSC Configuration test command result", + "description": "Represents the data structure returned by the `dsc config test` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `test` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "title": "Test Result", + "type": "object", + "required": [ + "name", + "type", + "result" + ], + "properties": { + "name": { + "$ref": "/dsc/2023/07/definitions/instanceName.json" + }, + "type": { + "$ref": "/dsc/2023/07/definitions/resourceType.json" + }, + "result": { + "$ref": "/dsc/2023/07/results/resource/test.json" + } + } + } + }, + "messages": { + "$ref": "/dsc/2023/07/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/dsc/2023/07/definitions/hadErrors.json" + } + }, + "$defs": { + "https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://schemas.microsoft.com/dsc/2023/07/results/resource/test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/results/resource/test.json", + "title": "DSC Resource test result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource test` command.", + "type": "object", + "required": [ + "expected_state", + "actual_state", + "diff_properties" + ], + "properties": { + "expected_state": { + "title": "Expected State", + "description": "This property always represents the desired state of the DSC Resource instance as specified to DSC.", + "type": "object" + }, + "actual_state": { + "title": "Actual State", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `test` method or, if the DSC Resource doesn't define the `test` method, by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "diff_properties": { + "title": "Differing Properties", + "description": "This property always represents the list of property names for the DSC Resource instance that aren't in the desired state. When this property is an empty array, the instance is in the desired state.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } + } + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/messages.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "/dsc/2023/07/definitions/message.json" + } + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/hadErrors.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/message.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/message.json", + "title": "Message", + "description": "A message emitted by a DSC Resource with associated metadata.", + "type": "object", + "required": [ + "name", + "type", + "message", + "level" + ], + "properties": { + "name": { + "title": "Message source instance name", + "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", + "type": "string" + }, + "type": { + "$ref": "/dsc/2023/07/definitions/resourceType.json" + }, + "message": { + "title": "Message content", + "description": "The actual content of the message as emitted by the DSC Resource.", + "type": "string", + "minLength": 1 + }, + "level": { + "title": "Message level", + "description": "Indicates the severity of the message.", + "type": "string", + "enum": [ + "Error", + "Warning", + "Information" + ] + } + } + } + } +} diff --git a/docs/schemas/bundled/outputs.config.validate.json b/docs/schemas/bundled/outputs.config.validate.json new file mode 100644 index 000000000..b31375e5c --- /dev/null +++ b/docs/schemas/bundled/outputs.config.validate.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.config.validate.json", + "$comment": "Not implemented yet.\n", + "title": "DSC Resource schema result", + "description": "Describes the return data for a DSC Resource from the `dsc config validate` command.", + "type": "object", + "$defs": {} +} diff --git a/docs/schemas/bundled/outputs.resource.get.json b/docs/schemas/bundled/outputs.resource.get.json new file mode 100644 index 000000000..48f452a8a --- /dev/null +++ b/docs/schemas/bundled/outputs.resource.get.json @@ -0,0 +1,18 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.resource.get.json", + "title": "DSC Resource get result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command.", + "type": "object", + "required": [ + "actual_state" + ], + "properties": { + "actual_state": { + "title": "The DSC Resource instance's current state", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + } + }, + "$defs": {} +} diff --git a/docs/schemas/bundled/outputs.resource.list.json b/docs/schemas/bundled/outputs.resource.list.json new file mode 100644 index 000000000..aa5eba629 --- /dev/null +++ b/docs/schemas/bundled/outputs.resource.list.json @@ -0,0 +1,668 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.resource.list.json", + "title": "DSC Resource list result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource list` command.", + "type": "object", + "properties": { + "type": { + "$ref": "/dsc/2023/07/definitions/resourceType.json" + }, + "version": { + "$ref": "/dsc/2023/07/definitions/semver.json" + }, + "path": { + "title": "Path", + "description": "Indicates the path to the DSC Resource on the file system.", + "type": "string" + }, + "directory": { + "title": "Directory", + "description": "Indicates the path to the folder containing the DSC Resource on the file system.", + "type": "string" + }, + "implementedAs": { + "title": "Implemented as", + "description": "Indicates how the DSC Resource was implemented. To specify a custom implementation, specify this value as an object with the `custom` property.", + "oneOf": [ + { + "title": "Standard implementation", + "description": "Indicates that the DSC Resource is implemented as one of the standard implementations built into DSC.", + "type": "string", + "enum": [ + "Command" + ] + }, + { + "title": "Custom implementation", + "description": "Indicates that the DSC Resource uses a custom implementation.", + "type": "object", + "required": [ + "custom" + ], + "properties": { + "custom": { + "title": "Custom implementation name", + "description": "The name of the custom implementation.", + "type": "string" + } + } + } + ] + }, + "author": { + "title": "Author", + "description": "Indicates the name of the person or organization that developed and maintains the DSC Resource.", + "type": [ + "string", + "null" + ] + }, + "properties": { + "title": "Properties", + "description": "Defines the DSC Resource's property names.", + "type": "array", + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "requires": { + "title": "Required DSC Resource Provider", + "description": "Defines the fully qualified type name of the DSC Resource Provider the DSC Resource depends on.", + "oneOf": [ + { + "$ref": "/dsc/2023/07/definitions/resourceType.json" + }, + { + "type": "null" + } + ] + }, + "manifest": { + "$ref": "/dsc/2023/07/resource/manifest.json" + } + }, + "$defs": { + "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/semver.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/semver.json", + "type": "string", + "title": "Semantic Version", + "description": "A valid semantic version (semver) string. For reference, see https://semver.org/", + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", + "$comment": "This pattern comes from the semver website's FAQ:\n\nhttps://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n\nIt's the suggested regex pattern for JavaScript.\n\nThis is the same pattern, made multi-line for easier readability.\n\n```\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n" + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.json", + "title": "Command-based DSC Resource Manifest", + "description": "Defines a valid command-based DSC Resource.", + "type": "object", + "required": [ + "manifestVersion", + "type", + "version", + "get" + ], + "properties": { + "manifestVersion": { + "title": "Manifest Version", + "description": "The semver of the DSC Resource manifest schema to validate this manifest with.", + "$ref": "/dsc/2023/07/definitions/semver.json", + "enums": [ + "1.0" + ] + }, + "type": { + "$ref": "/dsc/2023/07/definitions/resourceType.json" + }, + "version": { + "title": "Resource Semantic Version", + "description": "The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages.", + "$ref": "/dsc/2023/07/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "tags": { + "title": "Tags", + "description": "An array of short strings used to search for DSC Resources.", + "type": "array", + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "get": { + "$ref": "/dsc/2023/07/resource/manifest.get.json" + }, + "set": { + "$ref": "/dsc/2023/07/resource/manifest.set.json" + }, + "test": { + "$ref": "/dsc/2023/07/resource/manifest.test.json" + }, + "validate": { + "$ref": "/dsc/2023/07/resource/manifest.validate.json" + }, + "provider": { + "$ref": "/dsc/2023/07/resource/manifest.provider.json" + }, + "exitCodes": { + "title": "Exit Codes", + "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", + "type": "object", + "propertyNames": { + "pattern": "^[0-9]+$" + }, + "patternProperties": { + "^[0-9]+$": { + "type": "string" + } + }, + "examples": [ + { + "exitCodes": { + "0": "Success", + "1": "Invalid parameter", + "2": "Invalid input", + "3": "Registry error", + "4": "JSON serialization failed" + } + } + ] + }, + "schema": { + "$ref": "/dsc/2023/07/resource/manifest.schema.json" + } + } + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.json", + "title": "Get Method", + "description": "Defines how DSC must call the DSC Resource to get the current state of an instance.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/dsc/2023/07/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/dsc/2023/07/definitions/commandArgs.json" + }, + "input": { + "$ref": "/dsc/2023/07/definitions/inputKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "get" + ], + "input": "stdin" + }, + { + "executable": "osinfo" + } + ] + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.json", + "title": "Set Method", + "description": "Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "/dsc/2023/07/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/dsc/2023/07/definitions/commandArgs.json" + }, + "input": { + "$ref": "/dsc/2023/07/definitions/inputKind.json" + }, + "preTest": { + "title": "Resource Performs Pre-Test", + "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", + "type": "boolean", + "default": false + }, + "return": { + "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", + "$ref": "/dsc/2023/07/definitions/returnKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "preTest": true, + "return": "state" + } + ] + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.json", + "title": "Test Method", + "description": "Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "/dsc/2023/07/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/dsc/2023/07/definitions/commandArgs.json" + }, + "input": { + "$ref": "/dsc/2023/07/definitions/inputKind.json" + }, + "return": { + "title": "Test Command Return Type", + "description": "Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state.", + "$ref": "/dsc/2023/07/definitions/returnKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "test" + ], + "input": "stdin", + "return": "state" + } + ] + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.json", + "title": "Validate Method", + "description": "Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/dsc/2023/07/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/dsc/2023/07/definitions/commandArgs.json" + } + }, + "examples": [ + { + "executable": "dsc", + "args": [ + "config", + "validate" + ] + } + ] + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.json", + "title": "Provider", + "description": "Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to manage resources that don't have their own manifests with DSC.", + "type": "object", + "required": [ + "list", + "config" + ], + "properties": { + "list": { + "title": "List Command", + "description": "Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/dsc/2023/07/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/dsc/2023/07/definitions/commandArgs.json" + } + } + }, + "config": { + "title": "Expected Configuration", + "description": "Defines whether the provider expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations.", + "type": "string", + "enum": [ + "full", + "sequence" + ] + } + }, + "examples": [ + { + "config": "full", + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "./powershellgroup.resource.ps1 List" + ] + } + } + ] + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.json", + "title": "Instance Schema", + "description": "Defines how DSC must validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "oneOf": [ + { + "required": [ + "command" + ] + }, + { + "required": [ + "embedded" + ] + } + ], + "properties": { + "command": { + "title": "Instance Schema Command", + "description": "Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/dsc/2023/07/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/dsc/2023/07/definitions/commandArgs.json" + } + } + }, + "embedded": { + "title": "Embedded Instance Schema", + "description": "Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": [ + "$schema", + "type", + "properties" + ], + "properties": { + "type": { + "title": "Instance Type", + "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", + "const": "object" + }, + "$schema": { + "title": "DSC Resource instance schema dialect", + "description": "Defines which dialect of JSON Schema the DSC Resource is using to validate instances.", + "type": "string", + "format": "uri-reference", + "enum": [ + "https://json-schema.org/draft/2020-12/schema", + "https://json-schema.org/draft/2019-09/schema", + "http://json-schema.org/draft-07/schema#" + ] + }, + "$id": { + "title": "DSC Resource instance schema ID", + "description": "Defines the unique ID for the DSC Resource's instance schema.", + "type": "string", + "format": "uri-reference" + }, + "properties": { + "title": "Instance Properties", + "description": "Defines the schema for the DSC Resource's properties. Must define at least one property.", + "type": "object", + "minProperties": 1, + "unevaluatedProperties": { + "anyOf": [ + { + "$ref": "https://json-schema.org/draft/2020-12/schema" + }, + { + "$ref": "https://json-schema.org/draft/2019-09/schema" + }, + { + "$ref": "http://json-schema.org/draft-07/schema#" + } + ] + }, + "properties": { + "_ensure": { + "title": "Standard Property: _ensure", + "description": "Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums.", + "const": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json" + } + }, + "_inDesiredState": { + "title": "Standard Property: _inDesiredState", + "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", + "const": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json" + } + }, + "_purge": { + "title": "Standard Property: _purge", + "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", + "const": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json" + } + }, + "_rebootRequested": { + "title": "Standard property: _rebootRequested", + "description": "Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes.", + "const": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json" + } + } + } + } + } + }, + "url": { + "title": "Instance Schema URL", + "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", + "type": "string", + "format": "uri" + } + }, + "examples": [ + { + "command": { + "executable": "registry", + "args": [ + "schema" + ] + } + }, + { + "embedded": { + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "OSInfo", + "type": "object", + "required": [], + "properties": { + "$id": { + "type": "string" + }, + "architecture": { + "type": [ + "string", + "null" + ] + }, + "bitness": { + "$ref": "#/definitions/Bitness" + }, + "codename": { + "type": [ + "string", + "null" + ] + }, + "edition": { + "type": [ + "string", + "null" + ] + }, + "family": { + "$ref": "#/definitions/Family" + }, + "version": { + "type": "string" + } + }, + "additionalProperties": false, + "definitions": { + "Bitness": { + "type": "string", + "enum": [ + "32", + "64", + "unknown" + ] + }, + "Family": { + "type": "string", + "enum": [ + "Linux", + "macOS", + "Windows" + ] + } + } + } + } + ] + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.json", + "title": "Executable Command Name", + "description": "The name of the command to run.", + "type": "string" + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.json", + "title": "Executable Command Arguments", + "description": "The list of arguments to pass to the command.", + "type": "array", + "items": { + "type": "string" + } + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.json", + "title": "Executable Command Input Type", + "description": "Defines how DSC should pass input to the command, either as arguments or JSON over stdin.", + "type": "string", + "enum": [ + "args", + "stdin" + ], + "default": "args" + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.json", + "title": "Return Kind", + "type": "string", + "enum": [ + "state", + "stateAndDiff" + ], + "default": "state", + "$comment": "While the enumeration for return kind is the same for the `set` and `test`\nmethod, the way it changes the behavior of the command isn't. The description\nkeyword isn't included here because the respective schemas for those methods\ndocument the behavior themselves." + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json", + "title": "Ensure Existence", + "description": "Indicates whether the DSC Resource instance should exist.", + "type": "string", + "enum": [ + "Absent", + "Present" + ] + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json", + "title": "Instance is in the Desired State", + "description": "Indicates whether the instance is in the desired state. This property is only returned by the `test` method.", + "type": [ + "boolean", + "null" + ], + "readOnly": true + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json", + "title": "Purge", + "description": "Indicates that only the components described in the DSC Resource should exist. If other components exist, the DSC Resource is out of the desired state. When enforcing desired state, the DSC Resource removes unmanaged components.", + "type": [ + "boolean", + "null" + ], + "writeOnly": true + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json", + "title": "Reboot Requested", + "description": "Indicates that the set operation requires a reboot before it's fully complete.", + "type": [ + "boolean", + "null" + ], + "readOnly": true + } + } +} diff --git a/docs/schemas/bundled/outputs.resource.schema.json b/docs/schemas/bundled/outputs.resource.schema.json new file mode 100644 index 000000000..0978bbf4d --- /dev/null +++ b/docs/schemas/bundled/outputs.resource.schema.json @@ -0,0 +1,8 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.resource.schema.json", + "title": "DSC Resource schema result", + "description": "Describes the return data for a DSC Resource from the `dsc resource schema` command. This command always returns the DSC Resource's JSON schema document.", + "type": "object", + "$defs": {} +} diff --git a/docs/schemas/bundled/outputs.resource.set.json b/docs/schemas/bundled/outputs.resource.set.json new file mode 100644 index 000000000..f816305e7 --- /dev/null +++ b/docs/schemas/bundled/outputs.resource.set.json @@ -0,0 +1,34 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.resource.set.json", + "title": "DSC Resource set result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command.", + "type": "object", + "required": [ + "before_state", + "after_state", + "changed_properties" + ], + "properties": { + "before_state": { + "title": "State before enforcing", + "description": "This property always represents the desired state of the DSC Resource instance before the `set` method runs. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "after_state": { + "title": "State after enforcing", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `set` method after enforcing the desired state. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "changed_properties": { + "title": "Changed Properties", + "description": "This property always represents the list of property names for the DSC Resource instance that the `set` method modified. When this value is an empty array, the `set` method didn't enforce any properties for the instance.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } + }, + "$defs": {} +} diff --git a/docs/schemas/bundled/outputs.resource.test.json b/docs/schemas/bundled/outputs.resource.test.json new file mode 100644 index 000000000..346ce4944 --- /dev/null +++ b/docs/schemas/bundled/outputs.resource.test.json @@ -0,0 +1,34 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.resource.test.json", + "title": "DSC Resource test result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource test` command.", + "type": "object", + "required": [ + "expected_state", + "actual_state", + "diff_properties" + ], + "properties": { + "expected_state": { + "title": "Expected State", + "description": "This property always represents the desired state of the DSC Resource instance as specified to DSC.", + "type": "object" + }, + "actual_state": { + "title": "Actual State", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `test` method or, if the DSC Resource doesn't define the `test` method, by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "diff_properties": { + "title": "Differing Properties", + "description": "This property always represents the list of property names for the DSC Resource instance that aren't in the desired state. When this property is an empty array, the instance is in the desired state.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } + }, + "$defs": {} +} diff --git a/docs/schemas/bundled/outputs.schema.json b/docs/schemas/bundled/outputs.schema.json new file mode 100644 index 000000000..8188f79f5 --- /dev/null +++ b/docs/schemas/bundled/outputs.schema.json @@ -0,0 +1,8 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.schema.json", + "title": "DSC Resource schema result", + "description": "Describes the return data for a DSC Resource from the `dsc schema` command. This command always returns a JSON schema document.", + "type": "object", + "$defs": {} +} diff --git a/docs/schemas/bundled/resource.manifest.json b/docs/schemas/bundled/resource.manifest.json new file mode 100644 index 000000000..7863612b9 --- /dev/null +++ b/docs/schemas/bundled/resource.manifest.json @@ -0,0 +1,582 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/resource.manifest.json", + "title": "Command-based DSC Resource Manifest", + "description": "Defines a valid command-based DSC Resource.", + "type": "object", + "required": [ + "manifestVersion", + "type", + "version", + "get" + ], + "properties": { + "manifestVersion": { + "title": "Manifest Version", + "description": "The semver of the DSC Resource manifest schema to validate this manifest with.", + "$ref": "/dsc/2023/07/definitions/semver.json", + "enums": [ + "1.0" + ] + }, + "type": { + "$ref": "/dsc/2023/07/definitions/resourceType.json" + }, + "version": { + "title": "Resource Semantic Version", + "description": "The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages.", + "$ref": "/dsc/2023/07/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "tags": { + "title": "Tags", + "description": "An array of short strings used to search for DSC Resources.", + "type": "array", + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "get": { + "$ref": "/dsc/2023/07/resource/manifest.get.json" + }, + "set": { + "$ref": "/dsc/2023/07/resource/manifest.set.json" + }, + "test": { + "$ref": "/dsc/2023/07/resource/manifest.test.json" + }, + "validate": { + "$ref": "/dsc/2023/07/resource/manifest.validate.json" + }, + "provider": { + "$ref": "/dsc/2023/07/resource/manifest.provider.json" + }, + "exitCodes": { + "title": "Exit Codes", + "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", + "type": "object", + "propertyNames": { + "pattern": "^[0-9]+$" + }, + "patternProperties": { + "^[0-9]+$": { + "type": "string" + } + }, + "examples": [ + { + "exitCodes": { + "0": "Success", + "1": "Invalid parameter", + "2": "Invalid input", + "3": "Registry error", + "4": "JSON serialization failed" + } + } + ] + }, + "schema": { + "$ref": "/dsc/2023/07/resource/manifest.schema.json" + } + }, + "$defs": { + "https://schemas.microsoft.com/dsc/2023/07/definitions/semver.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/semver.json", + "type": "string", + "title": "Semantic Version", + "description": "A valid semantic version (semver) string. For reference, see https://semver.org/", + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", + "$comment": "This pattern comes from the semver website's FAQ:\n\nhttps://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n\nIt's the suggested regex pattern for JavaScript.\n\nThis is the same pattern, made multi-line for easier readability.\n\n```\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n" + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.json", + "title": "Get Method", + "description": "Defines how DSC must call the DSC Resource to get the current state of an instance.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/dsc/2023/07/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/dsc/2023/07/definitions/commandArgs.json" + }, + "input": { + "$ref": "/dsc/2023/07/definitions/inputKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "get" + ], + "input": "stdin" + }, + { + "executable": "osinfo" + } + ] + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.json", + "title": "Set Method", + "description": "Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "/dsc/2023/07/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/dsc/2023/07/definitions/commandArgs.json" + }, + "input": { + "$ref": "/dsc/2023/07/definitions/inputKind.json" + }, + "preTest": { + "title": "Resource Performs Pre-Test", + "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", + "type": "boolean", + "default": false + }, + "return": { + "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", + "$ref": "/dsc/2023/07/definitions/returnKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "preTest": true, + "return": "state" + } + ] + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.json", + "title": "Test Method", + "description": "Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "/dsc/2023/07/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/dsc/2023/07/definitions/commandArgs.json" + }, + "input": { + "$ref": "/dsc/2023/07/definitions/inputKind.json" + }, + "return": { + "title": "Test Command Return Type", + "description": "Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state.", + "$ref": "/dsc/2023/07/definitions/returnKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "test" + ], + "input": "stdin", + "return": "state" + } + ] + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.json", + "title": "Validate Method", + "description": "Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/dsc/2023/07/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/dsc/2023/07/definitions/commandArgs.json" + } + }, + "examples": [ + { + "executable": "dsc", + "args": [ + "config", + "validate" + ] + } + ] + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.json", + "title": "Provider", + "description": "Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to manage resources that don't have their own manifests with DSC.", + "type": "object", + "required": [ + "list", + "config" + ], + "properties": { + "list": { + "title": "List Command", + "description": "Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/dsc/2023/07/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/dsc/2023/07/definitions/commandArgs.json" + } + } + }, + "config": { + "title": "Expected Configuration", + "description": "Defines whether the provider expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations.", + "type": "string", + "enum": [ + "full", + "sequence" + ] + } + }, + "examples": [ + { + "config": "full", + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "./powershellgroup.resource.ps1 List" + ] + } + } + ] + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.json", + "title": "Instance Schema", + "description": "Defines how DSC must validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "oneOf": [ + { + "required": [ + "command" + ] + }, + { + "required": [ + "embedded" + ] + } + ], + "properties": { + "command": { + "title": "Instance Schema Command", + "description": "Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/dsc/2023/07/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/dsc/2023/07/definitions/commandArgs.json" + } + } + }, + "embedded": { + "title": "Embedded Instance Schema", + "description": "Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": [ + "$schema", + "type", + "properties" + ], + "properties": { + "type": { + "title": "Instance Type", + "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", + "const": "object" + }, + "$schema": { + "title": "DSC Resource instance schema dialect", + "description": "Defines which dialect of JSON Schema the DSC Resource is using to validate instances.", + "type": "string", + "format": "uri-reference", + "enum": [ + "https://json-schema.org/draft/2020-12/schema", + "https://json-schema.org/draft/2019-09/schema", + "http://json-schema.org/draft-07/schema#" + ] + }, + "$id": { + "title": "DSC Resource instance schema ID", + "description": "Defines the unique ID for the DSC Resource's instance schema.", + "type": "string", + "format": "uri-reference" + }, + "properties": { + "title": "Instance Properties", + "description": "Defines the schema for the DSC Resource's properties. Must define at least one property.", + "type": "object", + "minProperties": 1, + "unevaluatedProperties": { + "anyOf": [ + { + "$ref": "https://json-schema.org/draft/2020-12/schema" + }, + { + "$ref": "https://json-schema.org/draft/2019-09/schema" + }, + { + "$ref": "http://json-schema.org/draft-07/schema#" + } + ] + }, + "properties": { + "_ensure": { + "title": "Standard Property: _ensure", + "description": "Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums.", + "const": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json" + } + }, + "_inDesiredState": { + "title": "Standard Property: _inDesiredState", + "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", + "const": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json" + } + }, + "_purge": { + "title": "Standard Property: _purge", + "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", + "const": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json" + } + }, + "_rebootRequested": { + "title": "Standard property: _rebootRequested", + "description": "Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes.", + "const": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json" + } + } + } + } + } + }, + "url": { + "title": "Instance Schema URL", + "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", + "type": "string", + "format": "uri" + } + }, + "examples": [ + { + "command": { + "executable": "registry", + "args": [ + "schema" + ] + } + }, + { + "embedded": { + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "OSInfo", + "type": "object", + "required": [], + "properties": { + "$id": { + "type": "string" + }, + "architecture": { + "type": [ + "string", + "null" + ] + }, + "bitness": { + "$ref": "#/definitions/Bitness" + }, + "codename": { + "type": [ + "string", + "null" + ] + }, + "edition": { + "type": [ + "string", + "null" + ] + }, + "family": { + "$ref": "#/definitions/Family" + }, + "version": { + "type": "string" + } + }, + "additionalProperties": false, + "definitions": { + "Bitness": { + "type": "string", + "enum": [ + "32", + "64", + "unknown" + ] + }, + "Family": { + "type": "string", + "enum": [ + "Linux", + "macOS", + "Windows" + ] + } + } + } + } + ] + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.json", + "title": "Executable Command Name", + "description": "The name of the command to run.", + "type": "string" + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.json", + "title": "Executable Command Arguments", + "description": "The list of arguments to pass to the command.", + "type": "array", + "items": { + "type": "string" + } + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.json", + "title": "Executable Command Input Type", + "description": "Defines how DSC should pass input to the command, either as arguments or JSON over stdin.", + "type": "string", + "enum": [ + "args", + "stdin" + ], + "default": "args" + }, + "https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.json", + "title": "Return Kind", + "type": "string", + "enum": [ + "state", + "stateAndDiff" + ], + "default": "state", + "$comment": "While the enumeration for return kind is the same for the `set` and `test`\nmethod, the way it changes the behavior of the command isn't. The description\nkeyword isn't included here because the respective schemas for those methods\ndocument the behavior themselves." + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json", + "title": "Ensure Existence", + "description": "Indicates whether the DSC Resource instance should exist.", + "type": "string", + "enum": [ + "Absent", + "Present" + ] + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json", + "title": "Instance is in the Desired State", + "description": "Indicates whether the instance is in the desired state. This property is only returned by the `test` method.", + "type": [ + "boolean", + "null" + ], + "readOnly": true + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json", + "title": "Purge", + "description": "Indicates that only the components described in the DSC Resource should exist. If other components exist, the DSC Resource is out of the desired state. When enforcing desired state, the DSC Resource removes unmanaged components.", + "type": [ + "boolean", + "null" + ], + "writeOnly": true + }, + "https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json", + "title": "Reboot Requested", + "description": "Indicates that the set operation requires a reboot before it's fully complete.", + "type": [ + "boolean", + "null" + ], + "readOnly": true + } + } +} diff --git a/docs/schemas/bundled/resource.manifest.vscode.json b/docs/schemas/bundled/resource.manifest.vscode.json new file mode 100644 index 000000000..fdead63ad --- /dev/null +++ b/docs/schemas/bundled/resource.manifest.vscode.json @@ -0,0 +1,548 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/resource.manifest.json", + "title": "Command-based DSC Resource Manifest", + "description": "Defines a valid command-based DSC Resource.", + "type": "object", + "required": [ + "manifestVersion", + "type", + "version", + "get" + ], + "properties": { + "manifestVersion": { + "title": "Manifest Version", + "description": "The semver of the DSC Resource manifest schema to validate this manifest with.", + "$ref": "#/$defs/dsc/2023/07/definitions/semver.json", + "enums": [ + "1.0" + ] + }, + "type": { + "$ref": "#/$defs/dsc/2023/07/definitions/resourceType.json" + }, + "version": { + "title": "Resource Semantic Version", + "description": "The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages.", + "$ref": "#/$defs/dsc/2023/07/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "tags": { + "title": "Tags", + "description": "An array of short strings used to search for DSC Resources.", + "type": "array", + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "get": { + "$ref": "#/$defs/dsc/2023/07/resource/manifest.get.json" + }, + "set": { + "$ref": "#/$defs/dsc/2023/07/resource/manifest.set.json" + }, + "test": { + "$ref": "#/$defs/dsc/2023/07/resource/manifest.test.json" + }, + "validate": { + "$ref": "#/$defs/dsc/2023/07/resource/manifest.validate.json" + }, + "provider": { + "$ref": "#/$defs/dsc/2023/07/resource/manifest.provider.json" + }, + "exitCodes": { + "title": "Exit Codes", + "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", + "type": "object", + "propertyNames": { + "pattern": "^[0-9]+$" + }, + "patternProperties": { + "^[0-9]+$": { + "type": "string" + } + }, + "examples": [ + { + "exitCodes": { + "0": "Success", + "1": "Invalid parameter", + "2": "Invalid input", + "3": "Registry error", + "4": "JSON serialization failed" + } + } + ] + }, + "schema": { + "$ref": "#/$defs/dsc/2023/07/resource/manifest.schema.json" + } + }, + "$defs": { + "dsc": { + "2023": { + "07": { + "definitions": { + "semver.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/semver.json", + "type": "string", + "title": "Semantic Version", + "description": "A valid semantic version (semver) string. For reference, see https://semver.org/", + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", + "$comment": "This pattern comes from the semver website's FAQ:\n\nhttps://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n\nIt's the suggested regex pattern for JavaScript.\n\nThis is the same pattern, made multi-line for easier readability.\n\n```\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n" + }, + "resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "commandExecutable.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.json", + "title": "Executable Command Name", + "description": "The name of the command to run.", + "type": "string" + }, + "commandArgs.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.json", + "title": "Executable Command Arguments", + "description": "The list of arguments to pass to the command.", + "type": "array", + "items": { + "type": "string" + } + }, + "inputKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.json", + "title": "Executable Command Input Type", + "description": "Defines how DSC should pass input to the command, either as arguments or JSON over stdin.", + "type": "string", + "enum": [ + "args", + "stdin" + ], + "default": "args" + }, + "returnKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.json", + "title": "Return Kind", + "type": "string", + "enum": [ + "state", + "stateAndDiff" + ], + "default": "state", + "$comment": "While the enumeration for return kind is the same for the `set` and `test`\nmethod, the way it changes the behavior of the command isn't. The description\nkeyword isn't included here because the respective schemas for those methods\ndocument the behavior themselves." + } + }, + "resource": { + "manifest.get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.json", + "title": "Get Method", + "description": "Defines how DSC must call the DSC Resource to get the current state of an instance.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "#/$defs/dsc/2023/07/definitions/commandExecutable.json" + }, + "args": { + "$ref": "#/$defs/dsc/2023/07/definitions/commandArgs.json" + }, + "input": { + "$ref": "#/$defs/dsc/2023/07/definitions/inputKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "get" + ], + "input": "stdin" + }, + { + "executable": "osinfo" + } + ] + }, + "manifest.set.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.json", + "title": "Set Method", + "description": "Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "#/$defs/dsc/2023/07/definitions/commandExecutable.json" + }, + "args": { + "$ref": "#/$defs/dsc/2023/07/definitions/commandArgs.json" + }, + "input": { + "$ref": "#/$defs/dsc/2023/07/definitions/inputKind.json" + }, + "preTest": { + "title": "Resource Performs Pre-Test", + "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", + "type": "boolean", + "default": false + }, + "return": { + "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", + "$ref": "#/$defs/dsc/2023/07/definitions/returnKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "preTest": true, + "return": "state" + } + ] + }, + "manifest.test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.json", + "title": "Test Method", + "description": "Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "#/$defs/dsc/2023/07/definitions/commandExecutable.json" + }, + "args": { + "$ref": "#/$defs/dsc/2023/07/definitions/commandArgs.json" + }, + "input": { + "$ref": "#/$defs/dsc/2023/07/definitions/inputKind.json" + }, + "return": { + "title": "Test Command Return Type", + "description": "Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state.", + "$ref": "#/$defs/dsc/2023/07/definitions/returnKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "test" + ], + "input": "stdin", + "return": "state" + } + ] + }, + "manifest.validate.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.json", + "title": "Validate Method", + "description": "Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "#/$defs/dsc/2023/07/definitions/commandExecutable.json" + }, + "args": { + "$ref": "#/$defs/dsc/2023/07/definitions/commandArgs.json" + } + }, + "examples": [ + { + "executable": "dsc", + "args": [ + "config", + "validate" + ] + } + ] + }, + "manifest.provider.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.json", + "title": "Provider", + "description": "Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to manage resources that don't have their own manifests with DSC.", + "type": "object", + "required": [ + "list", + "config" + ], + "properties": { + "list": { + "title": "List Command", + "description": "Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "#/$defs/dsc/2023/07/definitions/commandExecutable.json" + }, + "args": { + "$ref": "#/$defs/dsc/2023/07/definitions/commandArgs.json" + } + } + }, + "config": { + "title": "Expected Configuration", + "description": "Defines whether the provider expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations.", + "type": "string", + "enum": [ + "full", + "sequence" + ] + } + }, + "examples": [ + { + "config": "full", + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "./powershellgroup.resource.ps1 List" + ] + } + } + ] + }, + "manifest.schema.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.json", + "title": "Instance Schema", + "description": "Defines how DSC must validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "oneOf": [ + { + "required": [ + "command" + ] + }, + { + "required": [ + "embedded" + ] + } + ], + "properties": { + "command": { + "title": "Instance Schema Command", + "description": "Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "#/$defs/dsc/2023/07/definitions/commandExecutable.json" + }, + "args": { + "$ref": "#/$defs/dsc/2023/07/definitions/commandArgs.json" + } + } + }, + "embedded": { + "title": "Embedded Instance Schema", + "description": "Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": [ + "$schema", + "type", + "properties" + ], + "properties": { + "type": { + "title": "Instance Type", + "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", + "const": "object" + }, + "$schema": { + "title": "DSC Resource instance schema dialect", + "description": "Defines which dialect of JSON Schema the DSC Resource is using to validate instances.", + "type": "string", + "format": "uri-reference", + "enum": [ + "https://json-schema.org/draft/2020-12/schema", + "https://json-schema.org/draft/2019-09/schema", + "http://json-schema.org/draft-07/schema#" + ] + }, + "$id": { + "title": "DSC Resource instance schema ID", + "description": "Defines the unique ID for the DSC Resource's instance schema.", + "type": "string", + "format": "uri-reference" + }, + "properties": { + "title": "Instance Properties", + "description": "Defines the schema for the DSC Resource's properties. Must define at least one property.", + "type": "object", + "minProperties": 1, + "unevaluatedProperties": { + "anyOf": [ + { + "$ref": "https://json-schema.org/draft/2020-12/schema" + }, + { + "$ref": "https://json-schema.org/draft/2019-09/schema" + }, + { + "$ref": "http://json-schema.org/draft-07/schema#" + } + ] + }, + "properties": { + "_ensure": { + "title": "Standard Property: _ensure", + "description": "Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums.", + "const": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json" + } + }, + "_inDesiredState": { + "title": "Standard Property: _inDesiredState", + "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", + "const": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json" + } + }, + "_purge": { + "title": "Standard Property: _purge", + "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", + "const": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json" + } + }, + "_rebootRequested": { + "title": "Standard property: _rebootRequested", + "description": "Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes.", + "const": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json" + } + } + } + } + } + }, + "url": { + "title": "Instance Schema URL", + "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", + "type": "string", + "format": "uri" + } + }, + "examples": [ + { + "command": { + "executable": "registry", + "args": [ + "schema" + ] + } + }, + { + "embedded": { + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "OSInfo", + "type": "object", + "required": [], + "properties": { + "$id": { + "type": "string" + }, + "architecture": { + "type": [ + "string", + "null" + ] + }, + "bitness": { + "$ref": "#/definitions/Bitness" + }, + "codename": { + "type": [ + "string", + "null" + ] + }, + "edition": { + "type": [ + "string", + "null" + ] + }, + "family": { + "$ref": "#/definitions/Family" + }, + "version": { + "type": "string" + } + }, + "additionalProperties": false, + "definitions": { + "Bitness": { + "type": "string", + "enum": [ + "32", + "64", + "unknown" + ] + }, + "Family": { + "type": "string", + "enum": [ + "Linux", + "macOS", + "Windows" + ] + } + } + } + } + ] + } + } + } + } + } + } +} diff --git a/docs/schemas/bundled/resource.manifest.vscode.yaml b/docs/schemas/bundled/resource.manifest.vscode.yaml new file mode 100644 index 000000000..26eca8df2 --- /dev/null +++ b/docs/schemas/bundled/resource.manifest.vscode.yaml @@ -0,0 +1,431 @@ +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/bundled/resource.manifest.yaml +title: Command-based DSC Resource Manifest +description: Defines a valid command-based DSC Resource. +type: object +required: +- manifestVersion +- type +- version +- get +properties: + manifestVersion: + title: Manifest Version + description: The semver of the DSC Resource manifest schema to validate this manifest with. + $ref: '#/$defs/dsc/2023/07/definitions/semver.yaml' + enums: + - "1.0" + type: + $ref: '#/$defs/dsc/2023/07/definitions/resourceType.yaml' + version: + title: Resource Semantic Version + description: The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages. + $ref: '#/$defs/dsc/2023/07/definitions/semver.yaml' + description: + title: Resource Description + description: A short synopsis of the DSC Resource's purpose. + type: string + tags: + title: Tags + description: An array of short strings used to search for DSC Resources. + type: array + items: + type: string + pattern: ^\w+$ + get: + $ref: '#/$defs/dsc/2023/07/resource/manifest.get.yaml' + set: + $ref: '#/$defs/dsc/2023/07/resource/manifest.set.yaml' + test: + $ref: '#/$defs/dsc/2023/07/resource/manifest.test.yaml' + validate: + $ref: '#/$defs/dsc/2023/07/resource/manifest.validate.yaml' + provider: + $ref: '#/$defs/dsc/2023/07/resource/manifest.provider.yaml' + exitCodes: + title: Exit Codes + description: This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes. + type: object + propertyNames: + pattern: ^[0-9]+$ + patternProperties: + ^[0-9]+$: + type: string + examples: + - exitCodes: + "0": Success + "1": Invalid parameter + "2": Invalid input + "3": Registry error + "4": JSON serialization failed + schema: + $ref: '#/$defs/dsc/2023/07/resource/manifest.schema.yaml' +$defs: + dsc: + "2023": + "07": + definitions: + semver.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/semver.yaml + type: string + title: Semantic Version + description: A valid semantic version (semver) string. For reference, see https://semver.org/ + pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ + $comment: > + This pattern comes from the semver website's FAQ: + + + https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string + + + It's the suggested regex pattern for JavaScript. + + + This is the same pattern, made multi-line for easier readability. + + + ``` + + ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*) + + (?:-( + (?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*) + (?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)) + *))? + + (?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ + + ``` + + + The first line matches the `major.minor.patch` components of the version. The middle lines match + + the pre-release components. The last line matches the build metadata component. + resourceType.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml + title: DSC Resource fully qualified type name + description: > + The namespaced name of the DSC Resource, using the syntax: + + + owner[.group][.area]/name + + + For example: + + - Microsoft.SqlServer/Database + - Microsoft.SqlServer.Database/User + type: string + pattern: ^\w+(\.\w+){0,2}\/\w+$ + commandExecutable.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.yaml + title: Executable Command Name + description: The name of the command to run. + type: string + commandArgs.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.yaml + title: Executable Command Arguments + description: The list of arguments to pass to the command. + type: array + items: + type: string + inputKind.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.yaml + title: Executable Command Input Type + description: Defines how DSC should pass input to the command, either as arguments or JSON over stdin. + type: string + enum: + - args + - stdin + default: args + returnKind.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.yaml + title: Return Kind + type: string + enum: + - state + - stateAndDiff + default: state + $comment: >- + While the enumeration for return kind is the same for the `set` and `test` + + method, the way it changes the behavior of the command isn't. The description + + keyword isn't included here because the respective schemas for those methods + + document the behavior themselves. + resource: + manifest.get.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.yaml + title: Get Method + description: Defines how DSC must call the DSC Resource to get the current state of an instance. + type: object + required: + - executable + properties: + executable: + $ref: '#/$defs/dsc/2023/07/definitions/commandExecutable.yaml' + args: + $ref: '#/$defs/dsc/2023/07/definitions/commandArgs.yaml' + input: + $ref: '#/$defs/dsc/2023/07/definitions/inputKind.yaml' + examples: + - executable: registry + args: + - config + - get + input: stdin + - executable: osinfo + manifest.set.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.yaml + title: Set Method + description: Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource. + type: object + required: + - executable + - input + properties: + executable: + $ref: '#/$defs/dsc/2023/07/definitions/commandExecutable.yaml' + args: + $ref: '#/$defs/dsc/2023/07/definitions/commandArgs.yaml' + input: + $ref: '#/$defs/dsc/2023/07/definitions/inputKind.yaml' + preTest: + title: Resource Performs Pre-Test + description: Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state. + type: boolean + default: false + return: + description: Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified. + $ref: '#/$defs/dsc/2023/07/definitions/returnKind.yaml' + examples: + - executable: registry + args: + - config + - set + input: stdin + preTest: true + return: state + manifest.test.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.yaml + title: Test Method + description: Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource. + type: object + required: + - executable + - input + properties: + executable: + $ref: '#/$defs/dsc/2023/07/definitions/commandExecutable.yaml' + args: + $ref: '#/$defs/dsc/2023/07/definitions/commandArgs.yaml' + input: + $ref: '#/$defs/dsc/2023/07/definitions/inputKind.yaml' + return: + title: Test Command Return Type + description: Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state. + $ref: '#/$defs/dsc/2023/07/definitions/returnKind.yaml' + examples: + - executable: registry + args: + - config + - test + input: stdin + return: state + manifest.validate.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.yaml + title: Validate Method + description: Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources. + type: object + required: + - executable + properties: + executable: + $ref: '#/$defs/dsc/2023/07/definitions/commandExecutable.yaml' + args: + $ref: '#/$defs/dsc/2023/07/definitions/commandArgs.yaml' + examples: + - executable: dsc + args: + - config + - validate + manifest.provider.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.yaml + title: Provider + description: Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to manage resources that don't have their own manifests with DSC. + type: object + required: + - list + - config + properties: + list: + title: List Command + description: Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources. + type: object + required: + - executable + properties: + executable: + $ref: '#/$defs/dsc/2023/07/definitions/commandExecutable.yaml' + args: + $ref: '#/$defs/dsc/2023/07/definitions/commandArgs.yaml' + config: + title: Expected Configuration + description: Defines whether the provider expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations. + type: string + enum: + - full + - sequence + examples: + - config: full + list: + executable: pwsh + args: + - -NoLogo + - -NonInteractive + - -NoProfile + - -Command + - ./powershellgroup.resource.ps1 List + manifest.schema.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.yaml + title: Instance Schema + description: Defines how DSC must validate a JSON blob representing an instance of the DSC Resource. + type: object + oneOf: + - required: + - command + - required: + - embedded + properties: + command: + title: Instance Schema Command + description: Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource. + type: object + required: + - executable + properties: + executable: + $ref: '#/$defs/dsc/2023/07/definitions/commandExecutable.yaml' + args: + $ref: '#/$defs/dsc/2023/07/definitions/commandArgs.yaml' + embedded: + title: Embedded Instance Schema + description: Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource. + type: object + required: + - $schema + - type + - properties + properties: + type: + title: Instance Type + description: Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type. + const: object + $schema: + title: DSC Resource instance schema dialect + description: Defines which dialect of JSON Schema the DSC Resource is using to validate instances. + type: string + format: uri-reference + enum: + - https://json-schema.org/draft/2020-12/schema + - https://json-schema.org/draft/2019-09/schema + - http://json-schema.org/draft-07/schema# + $id: + title: DSC Resource instance schema ID + description: Defines the unique ID for the DSC Resource's instance schema. + type: string + format: uri-reference + properties: + title: Instance Properties + description: Defines the schema for the DSC Resource's properties. Must define at least one property. + type: object + minProperties: 1 + unevaluatedProperties: + anyOf: + - $ref: https://json-schema.org/draft/2020-12/schema + - $ref: https://json-schema.org/draft/2019-09/schema + - $ref: http://json-schema.org/draft-07/schema# + properties: + _ensure: + title: 'Standard Property: _ensure' + description: Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums. + const: + $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.yaml + _inDesiredState: + title: 'Standard Property: _inDesiredState' + description: Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing. + const: + $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.yaml + _purge: + title: 'Standard Property: _purge' + description: Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values. + const: + $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.yaml + _rebootRequested: + title: 'Standard property: _rebootRequested' + description: Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes. + const: + $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.yaml + url: + title: Instance Schema URL + description: Defines the URL to the DSC Resource's JSON schema for integrating tools. + type: string + format: uri + examples: + - command: + executable: registry + args: + - schema + - embedded: + $schema: http://json-schema.org/draft-07/schema# + title: OSInfo + type: object + required: [] + properties: + $id: + type: string + architecture: + type: + - string + - "null" + bitness: + $ref: '#/definitions/Bitness' + codename: + type: + - string + - "null" + edition: + type: + - string + - "null" + family: + $ref: '#/definitions/Family' + version: + type: string + additionalProperties: false + definitions: + Bitness: + type: string + enum: + - "32" + - "64" + - unknown + Family: + type: string + enum: + - Linux + - macOS + - Windows diff --git a/docs/schemas/bundled/resource.manifest.yaml b/docs/schemas/bundled/resource.manifest.yaml index 59705f227..8fbe2614a 100644 --- a/docs/schemas/bundled/resource.manifest.yaml +++ b/docs/schemas/bundled/resource.manifest.yaml @@ -1,320 +1,462 @@ -# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema -$schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/bundled/resource.manifest.yaml - -title: Command-based DSC Resource Manifest -description: >- - Defines a valid command-based DSC Resource. - -type: object -required: - - manifestVersion - - type - - version - - get -properties: - manifestVersion: - title: Manifest Version - description: >- - The semver of the DSC Resource manifest schema to validate this manifest - with. - $ref: /dsc/2023/07/definitions/semver.yaml - enums: - - '1.0' - type: - $ref: /dsc/2023/07/definitions/resourceType.yaml - version: - title: Resource Semantic Version - description: >- - The semantic version (semver) of the DSC Resource. This version - identifies the DSC Resource, not the version of the application it - manages. - $ref: /dsc/2023/07/definitions/semver.yaml - description: - title: Resource Description - description: >- - A short synopsis of the DSC Resource's purpose. - # Should this include a maximum length or a pattern that forbids newlines? - type: string - tags: - title: Tags - description: >- - An array of short strings used to search for DSC Resources. - type: array - items: - type: string - pattern: ^\w+$ - get: - $ref: /dsc/2023/07/resource/manifest.get.yaml - set: - $ref: /dsc/2023/07/resource/manifest.set.yaml - test: - $ref: /dsc/2023/07/resource/manifest.test.yaml - validate: - $ref: /dsc/2023/07/resource/manifest.validate.yaml - provider: - # I'm not clear on how this works in practice - $ref: /dsc/2023/07/resource/manifest.provider.yaml - exitCodes: - # This setting in the root of the schema implies exit codes must have the - # same meaning across all executions. What about implementations that - # support multiple executables? Should exitCodes be a key that exists on - # command/method objects too? - title: Exit Codes - description: >- - This property defines a map of valid exit codes for the DSC Resource. - DSC always interprets exit code `0` as a successful operation and any - other exit code as an error. Use this property to indicate human-readable - semantic meanings for the DSC Resource's exit codes. - type: object - propertyNames: - pattern: "^[0-9]+$" - patternProperties: - "^[0-9]+$": - type: string - examples: - - exitCodes: - "0": Success - "1": Invalid parameter - "2": Invalid input - "3": Registry error - "4": JSON serialization failed - schema: - $ref: /dsc/2023/07/resource/manifest.schema.yaml - -$defs: - https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.yaml - title: Executable Command Arguments - description: >- - The list of arguments to pass to the command. - type: array - items: - type: string - - https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.yaml - title: Executable Command Name - description: >- - The name of the command to run. - type: string - - https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.yaml - title: Executable Command Input Type - description: >- - Defines how DSC should pass input to the command, either as arguments or - JSON over stdin. - type: string - enum: - - args - - stdin - default: args - - https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml - title: DSC Resource fully qualified type name - description: | - The namespaced name of the DSC Resource, using the syntax: - - [.][.]/ - - For example: - - - Microsoft.SqlServer/Database - - Microsoft.SqlServer.Database/User - type: string - pattern: ^\w+(\.\w+){0,2}\/\w+$ - - https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.yaml - title: Return Kind - type: string - enum: - - state - - stateAndDiff - default: state - - https://schemas.microsoft.com/dsc/2023/07/definitions/semver.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/semver.yaml - type: string - title: Semantic Version - description: >- - A valid semantic version (semver) string. For reference, see https://semver.org/ - pattern: >- - ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ - - https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.yaml - title: Get Method - description: >- - Defines how DSC must call the DSC Resource to get the current state of an - instance. - type: object - required: - - executable - properties: - executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml - args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml - input: - $ref: /dsc/2023/07/definitions/inputKind.yaml - - https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.yaml - title: Provider - description: >- - Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider - enables users to manage resources that don't have their own manifests with - DSC. - type: object - required: - - list - - config - properties: - list: - title: List Command - description: >- - Defines how DSC must call the DSC Resource Provider to list its supported - DSC Resources. - type: object - required: - - executable - properties: - executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml - args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml - config: - title: Expected Configuration - description: >- - Defines whether the provider expects to receive a full and unprocessed - configuration as a single JSON blob over stdin or a sequence of JSON - Lines for each child resource's configurations. - type: string - enum: - - full - - sequence - - https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.yaml - title: Instance Schema - description: >- - Defines how DSC must validate a JSON blob representing an instance of the - DSC Resource. - type: object - oneOf: - - required: [command] - - required: [embedded] - properties: - command: - title: Instance Schema Command - description: >- - Defines how DSC must call the DSC Resource to get the JSON Schema for - validating a JSON blob representing an instance of the DSC Resource. - type: object - required: - - executable - properties: - executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml - args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml - embedded: - title: Embedded Instance Schema - description: >- - Defines the JSON Schema DSC must use to validate a JSON blob - representing an instance of the DSC Resource. - type: object - minProperties: 1 - url: - title: Instance Schema URL - description: >- - Defines the URL to the DSC Resource's JSON schema for integrating tools. - type: string - format: uri - - https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.yaml - title: Set Method - description: >- - Defines how DSC must call the DSC Resource to set the desired state of - an instance and how to process the output from the DSC Resource. - type: object - required: - - executable - - input - properties: - executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml - args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml - input: - $ref: /dsc/2023/07/definitions/inputKind.yaml - preTest: - title: Resource Performs Pre-Test - description: >- - Defines whether the DSC Resource performs its own test to ensure - idempotency when calling the `set` command. Set this value to `true` - if the DSC Resource tests input before modifying system state. - type: boolean - default: false - return: - description: >- - Defines whether the command returns a JSON blob of the DSC Resource's - state after the set operation or the state and an array of the - properties the DSC Resource modified. - $ref: /dsc/2023/07/definitions/returnKind.yaml - - https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.yaml - title: Test Method - description: >- - Defines how DSC must call the DSC Resource to test if an instance is in - the desired state and how to process the output from the DSC Resource. - type: object - required: - - executable - - input - properties: - executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml - args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml - input: - $ref: /dsc/2023/07/definitions/inputKind.yaml - return: - title: Test Command Return Type - description: >- - Defines whether the command returns a JSON blob of the DSC Resource's current state or the - state and an array of the properties that are out of the desired state. - $ref: /dsc/2023/07/definitions/returnKind.yaml - - https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.yaml - title: Validate Method - description: >- - Defines how DSC must call the DSC Resource to validate the state of an - instance. This method is mandatory for DSC Group Resources. It's ignored for - all other DSC Resources. - type: object - required: - - executable - properties: - executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml - args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/bundled/resource.manifest.yaml +title: Command-based DSC Resource Manifest +description: Defines a valid command-based DSC Resource. +type: object +required: +- manifestVersion +- type +- version +- get +properties: + manifestVersion: + title: Manifest Version + description: The semver of the DSC Resource manifest schema to validate this manifest with. + $ref: /dsc/2023/07/definitions/semver.yaml + enums: + - "1.0" + type: + $ref: /dsc/2023/07/definitions/resourceType.yaml + version: + title: Resource Semantic Version + description: The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages. + $ref: /dsc/2023/07/definitions/semver.yaml + description: + title: Resource Description + description: A short synopsis of the DSC Resource's purpose. + type: string + tags: + title: Tags + description: An array of short strings used to search for DSC Resources. + type: array + items: + type: string + pattern: ^\w+$ + get: + $ref: /dsc/2023/07/resource/manifest.get.yaml + set: + $ref: /dsc/2023/07/resource/manifest.set.yaml + test: + $ref: /dsc/2023/07/resource/manifest.test.yaml + validate: + $ref: /dsc/2023/07/resource/manifest.validate.yaml + provider: + $ref: /dsc/2023/07/resource/manifest.provider.yaml + exitCodes: + title: Exit Codes + description: This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes. + type: object + propertyNames: + pattern: ^[0-9]+$ + patternProperties: + ^[0-9]+$: + type: string + examples: + - exitCodes: + "0": Success + "1": Invalid parameter + "2": Invalid input + "3": Registry error + "4": JSON serialization failed + schema: + $ref: /dsc/2023/07/resource/manifest.schema.yaml +$defs: + https://schemas.microsoft.com/dsc/2023/07/definitions/semver.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/semver.yaml + type: string + title: Semantic Version + description: A valid semantic version (semver) string. For reference, see https://semver.org/ + pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ + $comment: > + This pattern comes from the semver website's FAQ: + + + https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string + + + It's the suggested regex pattern for JavaScript. + + + This is the same pattern, made multi-line for easier readability. + + + ``` + + ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*) + + (?:-( + (?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*) + (?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)) + *))? + + (?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ + + ``` + + + The first line matches the `major.minor.patch` components of the version. The middle lines match + + the pre-release components. The last line matches the build metadata component. + https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml + title: DSC Resource fully qualified type name + description: > + The namespaced name of the DSC Resource, using the syntax: + + + owner[.group][.area]/name + + + For example: + + - Microsoft.SqlServer/Database + - Microsoft.SqlServer.Database/User + type: string + pattern: ^\w+(\.\w+){0,2}\/\w+$ + https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.yaml + title: Get Method + description: Defines how DSC must call the DSC Resource to get the current state of an instance. + type: object + required: + - executable + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + input: + $ref: /dsc/2023/07/definitions/inputKind.yaml + examples: + - executable: registry + args: + - config + - get + input: stdin + - executable: osinfo + https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.yaml + title: Set Method + description: Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource. + type: object + required: + - executable + - input + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + input: + $ref: /dsc/2023/07/definitions/inputKind.yaml + preTest: + title: Resource Performs Pre-Test + description: Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state. + type: boolean + default: false + return: + description: Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified. + $ref: /dsc/2023/07/definitions/returnKind.yaml + examples: + - executable: registry + args: + - config + - set + input: stdin + preTest: true + return: state + https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.yaml + title: Test Method + description: Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource. + type: object + required: + - executable + - input + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + input: + $ref: /dsc/2023/07/definitions/inputKind.yaml + return: + title: Test Command Return Type + description: Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state. + $ref: /dsc/2023/07/definitions/returnKind.yaml + examples: + - executable: registry + args: + - config + - test + input: stdin + return: state + https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.yaml + title: Validate Method + description: Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources. + type: object + required: + - executable + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + examples: + - executable: dsc + args: + - config + - validate + https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.yaml + title: Provider + description: Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to manage resources that don't have their own manifests with DSC. + type: object + required: + - list + - config + properties: + list: + title: List Command + description: Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources. + type: object + required: + - executable + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + config: + title: Expected Configuration + description: Defines whether the provider expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations. + type: string + enum: + - full + - sequence + examples: + - config: full + list: + executable: pwsh + args: + - -NoLogo + - -NonInteractive + - -NoProfile + - -Command + - ./powershellgroup.resource.ps1 List + https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.yaml + title: Instance Schema + description: Defines how DSC must validate a JSON blob representing an instance of the DSC Resource. + type: object + oneOf: + - required: + - command + - required: + - embedded + properties: + command: + title: Instance Schema Command + description: Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource. + type: object + required: + - executable + properties: + executable: + $ref: /dsc/2023/07/definitions/commandExecutable.yaml + args: + $ref: /dsc/2023/07/definitions/commandArgs.yaml + embedded: + title: Embedded Instance Schema + description: Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource. + type: object + required: + - $schema + - type + - properties + properties: + type: + title: Instance Type + description: Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type. + const: object + $schema: + title: DSC Resource instance schema dialect + description: Defines which dialect of JSON Schema the DSC Resource is using to validate instances. + type: string + format: uri-reference + enum: + - https://json-schema.org/draft/2020-12/schema + - https://json-schema.org/draft/2019-09/schema + - http://json-schema.org/draft-07/schema# + $id: + title: DSC Resource instance schema ID + description: Defines the unique ID for the DSC Resource's instance schema. + type: string + format: uri-reference + properties: + title: Instance Properties + description: Defines the schema for the DSC Resource's properties. Must define at least one property. + type: object + minProperties: 1 + unevaluatedProperties: + anyOf: + - $ref: https://json-schema.org/draft/2020-12/schema + - $ref: https://json-schema.org/draft/2019-09/schema + - $ref: http://json-schema.org/draft-07/schema# + properties: + _ensure: + title: 'Standard Property: _ensure' + description: Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums. + const: + $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.yaml + _inDesiredState: + title: 'Standard Property: _inDesiredState' + description: Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing. + const: + $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.yaml + _purge: + title: 'Standard Property: _purge' + description: Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values. + const: + $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.yaml + _rebootRequested: + title: 'Standard property: _rebootRequested' + description: Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes. + const: + $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.yaml + url: + title: Instance Schema URL + description: Defines the URL to the DSC Resource's JSON schema for integrating tools. + type: string + format: uri + examples: + - command: + executable: registry + args: + - schema + - embedded: + $schema: http://json-schema.org/draft-07/schema# + title: OSInfo + type: object + required: [] + properties: + $id: + type: string + architecture: + type: + - string + - "null" + bitness: + $ref: '#/definitions/Bitness' + codename: + type: + - string + - "null" + edition: + type: + - string + - "null" + family: + $ref: '#/definitions/Family' + version: + type: string + additionalProperties: false + definitions: + Bitness: + type: string + enum: + - "32" + - "64" + - unknown + Family: + type: string + enum: + - Linux + - macOS + - Windows + https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.yaml + title: Executable Command Name + description: The name of the command to run. + type: string + https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.yaml + title: Executable Command Arguments + description: The list of arguments to pass to the command. + type: array + items: + type: string + https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.yaml + title: Executable Command Input Type + description: Defines how DSC should pass input to the command, either as arguments or JSON over stdin. + type: string + enum: + - args + - stdin + default: args + https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.yaml + title: Return Kind + type: string + enum: + - state + - stateAndDiff + default: state + $comment: >- + While the enumeration for return kind is the same for the `set` and `test` + + method, the way it changes the behavior of the command isn't. The description + + keyword isn't included here because the respective schemas for those methods + + document the behavior themselves. + https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.yaml + title: Ensure Existence + description: Indicates whether the DSC Resource instance should exist. + type: string + enum: + - Absent + - Present + https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.yaml + title: Instance is in the Desired State + description: Indicates whether the instance is in the desired state. This property is only returned by the `test` method. + type: + - boolean + - "null" + readOnly: true + https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.yaml + title: Purge + description: Indicates that only the components described in the DSC Resource should exist. If other components exist, the DSC Resource is out of the desired state. When enforcing desired state, the DSC Resource removes unmanaged components. + type: + - boolean + - "null" + writeOnly: true + https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.yaml: + $schema: https://json-schema.org/draft/2020-12/schema + $id: https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.yaml + title: Reboot Requested + description: Indicates that the set operation requires a reboot before it's fully complete. + type: + - boolean + - "null" + readOnly: true diff --git a/docs/schemas/definitions/resourceType.yaml b/docs/schemas/definitions/resourceType.yaml index 930e5ab87..5f39f0f00 100644 --- a/docs/schemas/definitions/resourceType.yaml +++ b/docs/schemas/definitions/resourceType.yaml @@ -6,7 +6,7 @@ title: DSC Resource fully qualified type name description: | The namespaced name of the DSC Resource, using the syntax: - [.][.]/ + owner[.group][.area]/name For example: diff --git a/docs/schemas/resource/manifest.schema.yaml b/docs/schemas/resource/manifest.schema.yaml index 849b78128..784cfaf41 100644 --- a/docs/schemas/resource/manifest.schema.yaml +++ b/docs/schemas/resource/manifest.schema.yaml @@ -42,16 +42,27 @@ properties: - properties properties: type: + title: Instance Type + description: >- + Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always + have the `object` type. # Ensures the DSC Resource is always an object const: object $schema: # Ensures the DSC Resource always uses a schema we can understand + title: DSC Resource instance schema dialect + description: >- + Defines which dialect of JSON Schema the DSC Resource is using to validate instances. type: string format: uri-reference enum: - https://json-schema.org/draft/2020-12/schema + - https://json-schema.org/draft/2019-09/schema - http://json-schema.org/draft-07/schema# $id: + title: DSC Resource instance schema ID + description: >- + Defines the unique ID for the DSC Resource's instance schema. # Currently optional - maybe we should require this? type: string format: uri-reference @@ -60,21 +71,47 @@ properties: # least one property, ensures all unevaluated properties are of a kind # we can understand, and makes the standard properties available to # manifest authors. + title: Instance Properties + description: >- + Defines the schema for the DSC Resource's properties. Must define at least one property. type: object minProperties: 1 unevaluatedProperties: anyOf: - $ref: https://json-schema.org/draft/2020-12/schema + - $ref: https://json-schema.org/draft/2019-09/schema - $ref: http://json-schema.org/draft-07/schema# properties: _ensure: - $ref: /dsc/2023/07/resource/properties/ensure.yaml + title: 'Standard Property: _ensure' + description: >- + Indicates that the DSC Resource uses the standard `_ensure` property to specify + whether an instance should exist with the `Present` and `Absent` enums. + const: + $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.yaml _inDesiredState: - $ref: /dsc/2023/07/resource/properties/inDesiredState.yaml + title: 'Standard Property: _inDesiredState' + description: >- + Indicates that the DSC Resource returns this value for it's own `test` method. This + property is mandatory when the manifest defines the `test` property. It shouldn't + be included if the DSC Resource relies on DSC's synthetic testing. + const: + $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.yaml _purge: - $ref: /dsc/2023/07/resource/properties/purge.yaml + title: 'Standard Property: _purge' + description: >- + Indicates that the DSC Resource uses the standard `_purge` property to specify + whether the DSC Resource should remove all non-specified members when it manages + an array of members or values. + const: + $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.yaml _rebootRequested: - $ref: /dsc/2023/07/resource/properties/rebootRequested.yaml + title: 'Standard property: _rebootRequested' + description: >- + Indicates that the DSC Resource uses the standard `_rebootRequested` property to + report whether the machine should be rebooted after the `set` method executes. + const: + $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.yaml url: title: Instance Schema URL description: >- From e423498947039b9956ef1684261ad74499a4a19a Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 21 Jul 2023 10:07:22 -0500 Subject: [PATCH 05/11] (MAINT) Simplify decomposed schemas This change rearranges the definitions for configuration parameters and resources so that only the valid parameter/resource definition in the `parameters` and `resources` properties are references. This makes the documentation and definition a little cleaner and easier to maintain. The validation properties are moved from definitions into the parameter document for the same reason - they aren not referenced anywhere else. In the resource instance schema, this change adds a validation pattern for the `dependsOn` key to match the proposed syntax. In the resource manifest schema, this change ensures that tags for a resource must be unique, disallowing repeated tags. --- .../bundled/config.document.vscode.yaml | 12 +-- docs/schemas/bundled/config.document.yaml | 12 +-- .../bundled/manual.config.document.yaml | 12 +-- docs/schemas/config/document.parameter.yaml | 78 +++++++++++++++++++ docs/schemas/config/document.parameters.yaml | 60 -------------- docs/schemas/config/document.resource.yaml | 32 ++++++++ docs/schemas/config/document.resources.yaml | 36 --------- docs/schemas/config/document.yaml | 17 +++- .../{dataType.yaml => dataTypes.yaml} | 4 +- .../integerValidationProperties.yaml | 26 ------- .../lengthValidationProperties.yaml | 26 ------- docs/schemas/resource/manifest.yaml | 1 + 12 files changed, 146 insertions(+), 170 deletions(-) create mode 100644 docs/schemas/config/document.parameter.yaml delete mode 100644 docs/schemas/config/document.parameters.yaml create mode 100644 docs/schemas/config/document.resource.yaml delete mode 100644 docs/schemas/config/document.resources.yaml rename docs/schemas/definitions/parameters/{dataType.yaml => dataTypes.yaml} (90%) delete mode 100644 docs/schemas/definitions/parameters/integerValidationProperties.yaml delete mode 100644 docs/schemas/definitions/parameters/lengthValidationProperties.yaml diff --git a/docs/schemas/bundled/config.document.vscode.yaml b/docs/schemas/bundled/config.document.vscode.yaml index 9316a0dda..20f18c0e7 100644 --- a/docs/schemas/bundled/config.document.vscode.yaml +++ b/docs/schemas/bundled/config.document.vscode.yaml @@ -21,7 +21,7 @@ properties: description: Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value. type: object resources: - $ref: '#/$defs/dsc/2023/07/config/document.resources.yaml' + $ref: '#/$defs/dsc/2023/07/config/dataTypes.yaml' metadata: title: Configuration metadata description: Defines a set of key-value pairs for the configuration. This metadata isn't validated. @@ -46,7 +46,7 @@ $defs: - type properties: type: - $ref: '#/$defs/dsc/2023/07/definitions/parameters/dataType.yaml' + $ref: '#/$defs/dsc/2023/07/definitions/parameters/dataTypes.yaml' defaultValue: title: Default value description: Defines the default value for the parameter. @@ -85,9 +85,9 @@ $defs: const: array then: $ref: '#/$defs/dsc/2023/07/definitions/parameters/lengthValidationProperties.yaml' - document.resources.yaml: + dataTypes.yaml: $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/config/document.resources.yaml + $id: https://schemas.microsoft.com/dsc/2023/07/config/dataTypes.yaml title: DSC Configuration document resources description: Defines a list of DSC Resource instances for the configuration to manage. type: array @@ -115,9 +115,9 @@ $defs: type: object definitions: parameters: - dataType.yaml: + dataTypes.yaml: $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataType.yaml + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataTypes.yaml title: Data Type description: Defines the data type for the value. type: string diff --git a/docs/schemas/bundled/config.document.yaml b/docs/schemas/bundled/config.document.yaml index 1b3c83161..62af0fd4b 100644 --- a/docs/schemas/bundled/config.document.yaml +++ b/docs/schemas/bundled/config.document.yaml @@ -21,7 +21,7 @@ properties: description: Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value. type: object resources: - $ref: /dsc/2023/07/config/document.resources.yaml + $ref: /dsc/2023/07/config/dataTypes.yaml metadata: title: Configuration metadata description: Defines a set of key-value pairs for the configuration. This metadata isn't validated. @@ -42,7 +42,7 @@ $defs: - type properties: type: - $ref: /dsc/2023/07/definitions/parameters/dataType.yaml + $ref: /dsc/2023/07/definitions/parameters/dataTypes.yaml defaultValue: title: Default value description: Defines the default value for the parameter. @@ -81,9 +81,9 @@ $defs: const: array then: $ref: /dsc/2023/07/definitions/parameters/lengthValidationProperties.yaml - https://schemas.microsoft.com/dsc/2023/07/config/document.resources.yaml: + https://schemas.microsoft.com/dsc/2023/07/config/dataTypes.yaml: $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/config/document.resources.yaml + $id: https://schemas.microsoft.com/dsc/2023/07/config/dataTypes.yaml title: DSC Configuration document resources description: Defines a list of DSC Resource instances for the configuration to manage. type: array @@ -109,9 +109,9 @@ $defs: title: Managed instance properties description: Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema. type: object - https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataType.yaml: + https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataTypes.yaml: $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataType.yaml + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataTypes.yaml title: Data Type description: Defines the data type for the value. type: string diff --git a/docs/schemas/bundled/manual.config.document.yaml b/docs/schemas/bundled/manual.config.document.yaml index 3de84cbd0..ba0fc4f26 100644 --- a/docs/schemas/bundled/manual.config.document.yaml +++ b/docs/schemas/bundled/manual.config.document.yaml @@ -33,7 +33,7 @@ properties: type: object resources: - $ref: /dsc/2023/07/config/document.resources.yaml + $ref: /dsc/2023/07/config/dataTypes.yaml metadata: title: Configuration metadata @@ -62,7 +62,7 @@ $defs: - type properties: type: - $ref: /dsc/2023/07/definitions/parameters/dataType.yaml + $ref: /dsc/2023/07/definitions/parameters/dataTypes.yaml defaultValue: title: Default value description: >- @@ -146,9 +146,9 @@ $defs: type: integer minimum: 0 - https://schemas.microsoft.com/dsc/2023/07/config/document.resources.yaml: + https://schemas.microsoft.com/dsc/2023/07/config/dataTypes.yaml: $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/config/document.resources.yaml + $id: https://schemas.microsoft.com/dsc/2023/07/config/dataTypes.yaml title: DSC Configuration document resources description: >- Defines a list of DSC Resource instances for the configuration to manage. @@ -182,9 +182,9 @@ $defs: against the DSC Resource's schema. type: object - https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataType.yaml: + https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataTypes.yaml: $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataType.yaml + $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataTypes.yaml title: Data Type description: >- Defines the data type for the value. diff --git a/docs/schemas/config/document.parameter.yaml b/docs/schemas/config/document.parameter.yaml new file mode 100644 index 000000000..61976b8b7 --- /dev/null +++ b/docs/schemas/config/document.parameter.yaml @@ -0,0 +1,78 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/config/document.parameter.yaml +title: Parameter +description: Defines a runtime option for a DSC Configuration Document. + +type: object +required: + - type +properties: + type: + $ref: /dsc/2023/07/definitions/parameters/dataTypes.yaml + defaultValue: + title: Default value + description: >- + Defines the default value for the parameter. + $ref: /dsc/2023/07/definitions/parameters/validValueTypes.yaml + allowedValues: + title: Allowed values + description: >- + Defines a list of valid values for the parameter. If the + parameter is defined with any other values, it's invalid. + type: array + items: + $ref: /dsc/2023/07/definitions/parameters/validValueTypes.yaml + description: + title: Parameter description + description: >- + Defines a synopsis for the parameter explaining its purpose. + type: string + metadata: + title: Parameter metadata + description: >- + Defines a set of key-value pairs for the parameter. This metadata + isn't validated. + type: object +allOf: + - if: + properties: + type: + const: int + then: + minValue: + title: Minimum value + description: >- + The minimum valid value for an integer type. If defined with the + `maxValue` property, this value must be less than the value of + `maxValue`. + type: integer + maxValue: + title: Maximum value + description: >- + The maximum valid value for an integer type. If defined with the + `minValue` property, this value must be greater than the value of + `minValue`. + type: integer + - if: + oneOf: + - properties: { type: { const: string } } + - properties: { type: { const: securestring } } + - properties: { type: { const: array } } + then: + minLength: + title: Minimum length + description: >- + The minimum valid length for a `string`, `securestring`, or `array`. If + defined with the `maxLength` property, this value must be less than the + value of `maxLength`. + type: integer + minimum: 0 + maxLength: + title: Maximum length + description: >- + The maximum valid length for a `string`, `securestring`, or `array`. If + defined with the `minLength` property, this value must be less than the + value of `minLength`. + type: integer + minimum: 0 diff --git a/docs/schemas/config/document.parameters.yaml b/docs/schemas/config/document.parameters.yaml deleted file mode 100644 index d6d781a16..000000000 --- a/docs/schemas/config/document.parameters.yaml +++ /dev/null @@ -1,60 +0,0 @@ -# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema -$schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.yaml - -title: DSC Configuration document parameters -description: >- - Defines runtime options for the configuration. Users and integrating tools - can override use the defined parameters to pass alternate values to the - configuration. -type: object - -patternProperties: - ".": - title: Parameter - description: >- - Defines a runtime option for a DSC Configuration Document. - type: object - required: - - type - properties: - type: - $ref: /dsc/2023/07/definitions/parameters/dataType.yaml - defaultValue: - title: Default value - description: >- - Defines the default value for the parameter. - $ref: /dsc/2023/07/definitions/parameters/validValueTypes.yaml - allowedValues: - title: Allowed values - description: >- - Defines a list of valid values for the parameter. If the - parameter is defined with any other values, it's invalid. - type: array - items: - $ref: /dsc/2023/07/definitions/parameters/validValueTypes.yaml - description: - title: Parameter description - description: >- - Defines a synopsis for the parameter explaining its purpose. - type: string - metadata: - title: Parameter metadata - description: >- - Defines a set of key-value pairs for the parameter. This metadata - isn't validated. - type: object - allOf: - - if: - properties: - type: - const: int - then: - $ref: /dsc/2023/07/definitions/parameters/integerValidationProperties.yaml - - if: - oneOf: - - properties: { type: { const: string } } - - properties: { type: { const: securestring } } - - properties: { type: { const: array } } - then: - $ref: /dsc/2023/07/definitions/parameters/lengthValidationProperties.yaml diff --git a/docs/schemas/config/document.resource.yaml b/docs/schemas/config/document.resource.yaml new file mode 100644 index 000000000..b14b604de --- /dev/null +++ b/docs/schemas/config/document.resource.yaml @@ -0,0 +1,32 @@ +# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema +$schema: https://json-schema.org/draft/2020-12/schema +$id: https://schemas.microsoft.com/dsc/2023/07/config/document.resource.yaml + +title: DSC Resource instance +type: object +required: + - type + - name +properties: + type: + $ref: /dsc/2023/07/definitions/resourceType.yaml + name: + $ref: /dsc/2023/07/definitions/instanceName.yaml + dependsOn: + title: Instance depends on + description: >- + Defines a list of DSC Resource instances that DSC must successfully + process before processing this instance. Each value for this property + must be the value of another DSC Resource instance's `name` property. + type: array + items: + type: string + uniqueItems: true + pattern: ^\[\w+(\.\w+){0,2}\/\w+\].+$ + properties: + title: Managed instance properties + description: >- + Defines the properties of the DSC Resource this instance manages. This + property's value must be an object. DSC validates the property's value + against the DSC Resource's schema. + type: object diff --git a/docs/schemas/config/document.resources.yaml b/docs/schemas/config/document.resources.yaml deleted file mode 100644 index 1af7f97a5..000000000 --- a/docs/schemas/config/document.resources.yaml +++ /dev/null @@ -1,36 +0,0 @@ -# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema -$schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/config/document.resources.yaml - -title: DSC Configuration document resources -description: >- - Defines a list of DSC Resource instances for the configuration to manage. -type: array -items: - title: DSC Resource instance - type: object - required: - - type - - name - properties: - type: - $ref: /dsc/2023/07/definitions/resourceType.yaml - name: - $ref: /dsc/2023/07/definitions/instanceName.yaml - dependsOn: - title: Instance depends on - description: >- - Defines a list of DSC Resource instances that DSC must successfully - process before processing this instance. Each value for this property - must be the value of another DSC Resource instance's `name` property. - type: array - items: - type: string - uniqueItems: true - properties: - title: Managed instance properties - description: >- - Defines the properties of the DSC Resource this instance manages. This - property's value must be an object. DSC validates the property's value - against the DSC Resource's schema. - type: object diff --git a/docs/schemas/config/document.yaml b/docs/schemas/config/document.yaml index 6d05ea3a7..a4320a797 100644 --- a/docs/schemas/config/document.yaml +++ b/docs/schemas/config/document.yaml @@ -22,7 +22,14 @@ properties: - https://schemas.microsoft.com/dsc/2023/07/config/document.yaml parameters: - $ref: /dsc/2023/07/config/document.parameters.yaml + title: DSC Configuration document parameters + description: >- + Defines runtime options for the configuration. Users and integrating tools + can override use the defined parameters to pass alternate values to the + configuration. + type: object + additionalProperties: + $ref: /dsc/2023/07/config/document.parameters.yaml variables: title: Configuration variables @@ -33,7 +40,13 @@ properties: type: object resources: - $ref: /dsc/2023/07/config/document.resources.yaml + title: DSC Configuration document resources + description: >- + Defines a list of DSC Resource instances for the configuration to manage. + type: array + minItems: 1 + items: + $ref: /dsc/2023/07/config/document.resource.yaml metadata: title: Configuration metadata diff --git a/docs/schemas/definitions/parameters/dataType.yaml b/docs/schemas/definitions/parameters/dataTypes.yaml similarity index 90% rename from docs/schemas/definitions/parameters/dataType.yaml rename to docs/schemas/definitions/parameters/dataTypes.yaml index 1cfa893d6..db8a0c28b 100644 --- a/docs/schemas/definitions/parameters/dataType.yaml +++ b/docs/schemas/definitions/parameters/dataTypes.yaml @@ -1,8 +1,8 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataType.yaml +$id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataTypes.yaml -title: Data Type +title: Data Types description: >- Defines the data type for the value. type: string diff --git a/docs/schemas/definitions/parameters/integerValidationProperties.yaml b/docs/schemas/definitions/parameters/integerValidationProperties.yaml deleted file mode 100644 index 66479a82f..000000000 --- a/docs/schemas/definitions/parameters/integerValidationProperties.yaml +++ /dev/null @@ -1,26 +0,0 @@ -# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema -$schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/integerValidationProperties.yaml - -$comment: | - This schema fragment makes it a little easier to compose the valid properties - for DSC Configuration document parameters. These only apply to `int` type - parameters. - -properties: - minValue: - title: Minimum value - description: >- - The minimum valid value for an integer type. If defined with the - `maxValue` property, this value must be less than the value of - `maxValue`. - type: integer - minimum: 0 - maxValue: - title: Maximum value - description: >- - The maximum valid value for an integer type. If defined with the - `minValue` property, this value must be greater than the value of - `minValue`. - type: integer - minimum: 0 diff --git a/docs/schemas/definitions/parameters/lengthValidationProperties.yaml b/docs/schemas/definitions/parameters/lengthValidationProperties.yaml deleted file mode 100644 index c2aa560eb..000000000 --- a/docs/schemas/definitions/parameters/lengthValidationProperties.yaml +++ /dev/null @@ -1,26 +0,0 @@ -# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema -$schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/lengthValidationProperties.yaml - -$comment: | - This schema fragment makes it a little easier to compose the valid properties - for DSC Configuration document parameters. These only apply to `string`, - `securestring`, and `array` type parameters. - -properties: - minLength: - title: Minimum length - description: >- - The minimum valid length for a `string`, `securestring`, or `array`. If - defined with the `maxLength` property, this value must be less than the - value of `maxLength`. - type: integer - minimum: 0 - maxLength: - title: Maximum length - description: >- - The maximum valid length for a `string`, `securestring`, or `array`. If - defined with the `minLength` property, this value must be less than the - value of `minLength`. - type: integer - minimum: 0 diff --git a/docs/schemas/resource/manifest.yaml b/docs/schemas/resource/manifest.yaml index 00c6ed686..c49a9c1d3 100644 --- a/docs/schemas/resource/manifest.yaml +++ b/docs/schemas/resource/manifest.yaml @@ -41,6 +41,7 @@ properties: description: >- An array of short strings used to search for DSC Resources. type: array + uniqueItems: true items: type: string pattern: ^\w+$ From 3979ecf7b62445ff66bdd6ac7a957ab26e296b05 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 21 Jul 2023 10:08:53 -0500 Subject: [PATCH 06/11] (DOCS) Document resource and config schemas This change adds initial documentation for the configuration document and resource manifest schemas. It also documents the well-known property schemas so they can be referenced in the resource manifest docs. --- docs/reference/schemas/config/document.md | 122 +++++++++ docs/reference/schemas/config/parameter.md | 181 +++++++++++++ docs/reference/schemas/config/resource.md | 99 +++++++ .../definitions/parameters/dataTypes.md | 243 ++++++++++++++++++ .../schemas/resource/manifest/get.md | 114 ++++++++ .../schemas/resource/manifest/provider.md | 122 +++++++++ .../schemas/resource/manifest/root.md | 222 ++++++++++++++++ .../resource/manifest/schema/embedded.md | 161 ++++++++++++ .../resource/manifest/schema/property.md | 153 +++++++++++ .../schemas/resource/manifest/set.md | 145 +++++++++++ .../schemas/resource/manifest/test.md | 139 ++++++++++ .../schemas/resource/manifest/validate.md | 77 ++++++ .../schemas/resource/properties/ensure.md | 48 ++++ .../resource/properties/inDesiredState.md | 44 ++++ .../schemas/resource/properties/overview.md | 47 ++++ .../schemas/resource/properties/purge.md | 42 +++ .../resource/properties/rebootRequested.md | 41 +++ 17 files changed, 2000 insertions(+) create mode 100644 docs/reference/schemas/config/document.md create mode 100644 docs/reference/schemas/config/parameter.md create mode 100644 docs/reference/schemas/config/resource.md create mode 100644 docs/reference/schemas/definitions/parameters/dataTypes.md create mode 100644 docs/reference/schemas/resource/manifest/get.md create mode 100644 docs/reference/schemas/resource/manifest/provider.md create mode 100644 docs/reference/schemas/resource/manifest/root.md create mode 100644 docs/reference/schemas/resource/manifest/schema/embedded.md create mode 100644 docs/reference/schemas/resource/manifest/schema/property.md create mode 100644 docs/reference/schemas/resource/manifest/set.md create mode 100644 docs/reference/schemas/resource/manifest/test.md create mode 100644 docs/reference/schemas/resource/manifest/validate.md create mode 100644 docs/reference/schemas/resource/properties/ensure.md create mode 100644 docs/reference/schemas/resource/properties/inDesiredState.md create mode 100644 docs/reference/schemas/resource/properties/overview.md create mode 100644 docs/reference/schemas/resource/properties/purge.md create mode 100644 docs/reference/schemas/resource/properties/rebootRequested.md diff --git a/docs/reference/schemas/config/document.md b/docs/reference/schemas/config/document.md new file mode 100644 index 000000000..38acd851b --- /dev/null +++ b/docs/reference/schemas/config/document.md @@ -0,0 +1,122 @@ +# 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://schemas.microsoft.com/dsc/2023/07/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 recommneds drafting configuration documents in YAML. + +For DSC's authoring tools to recognize a file as a DSC Configuration document, the file name 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 + + + +## 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://schemas.microsoft.com/dsc/2023/07/config/document.yaml +``` + +### 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://schemas.microsoft.com/dsc/2023/07/config/document.parameter.yaml +``` + +### 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: false +Minimum Item Count: 1 +Valid Item Schema: https://schemas.microsoft.com/dsc/2023/07/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 diff --git a/docs/reference/schemas/config/parameter.md b/docs/reference/schemas/config/parameter.md new file mode 100644 index 000000000..a554dc950 --- /dev/null +++ b/docs/reference/schemas/config/parameter.md @@ -0,0 +1,181 @@ +# DSC Configuration document parameter schema + +Defines runtime options for a configuration. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.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 diff --git a/docs/reference/schemas/config/resource.md b/docs/reference/schemas/config/resource.md new file mode 100644 index 000000000..518dced49 --- /dev/null +++ b/docs/reference/schemas/config/resource.md @@ -0,0 +1,99 @@ +# DSC Configuration document resource schema + +Defines instances of DSC Resources that compose a configuration. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/config/document.resources.json +Type : object +``` + +## Description + +The `resources` property of a DSC Configuration document always includes at least one DSC Resource +instance. Together, the instances in a configuration define the desired state that DSC can get, +test, and set on a machine. + +This document describes the JSON schema for a valid DSC Resource instance in a configuration +document. + +For more information about DSC Resources, see [Anatomy of a command-based DSC Resource][01]. + +## Required Properties + +Every resource instance must be an object that defines these properties: + +- [name](#name) +- [type](#type) + +## Properties + +### name + +The `name` property of a resource instance defines the short, human-readable name for a DSC +Resource instance. This property must be unique within a DSC Configuration document. If any +resource instances share the same name, DSC raises an error. + +```yaml +Type: string +Required: true +``` + +### type + +The `type` property identifies the instance's DSC Resource. The value for this property must be the +valid fully-qualified type name for the resource. For more information about type names, see +[Anatomy of a command-based DSC Resource][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +### properties + +The `properties` of a resource instance define its desired state. The value of this property must +be an object. For [assertion resources][02], the value may be an empty object (`{}`). DSC uses the +DSC Resource's instance schema to validate the defined properties. + +For more information about instance schemas in DSC, see [DSC Resource instance schemas][03]. + +```yaml +Type: object +Required: true +``` + +### dependsOn + +To declare that a resource instance is dependent on another instance in the configuration, define the `dependsOn` property. + +This property must be an array of dependency declarations. Each dependency must use this +syntax: + +```yaml +"[]" +``` + +In the dependency syntax, `` is the `type` property of the dependent resource +and `` is the dependency's `name` property. + +Multiple instances can depend on the same instance, but every dependency for an instance must be +unique in that instance's `dependsOn` property. + +For more information, see [Configuration resource dependencies][04]. + +```yaml +Type: array +Required: false +Items Must be Unique: true +Valid Items Type: string +Valid Items Pattern: ^\[\w+(\.\w+){0,2}\/\w+\].+$ +``` + +[01]: ../../../resources/concepts/anatomy.md +[02]: ../../../resources/concepts/assertion-resources.md +[03]: ../../../resources/concepts/schemas.md +[04]: ../../../configurations/concepts/dependencies.md diff --git a/docs/reference/schemas/definitions/parameters/dataTypes.md b/docs/reference/schemas/definitions/parameters/dataTypes.md new file mode 100644 index 000000000..3a83c99a7 --- /dev/null +++ b/docs/reference/schemas/definitions/parameters/dataTypes.md @@ -0,0 +1,243 @@ +# DSC configuration parameter data type schema reference + +Defines valid data types for a DSC configuration parameter + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataTypes.yaml +Type : string +Valid Values: + - array + - bool + - int + - object + - string + - secureobject + - securestring +``` + +## Description + +Parameters in a [DSC Configuration document][01] must be a valid data type. + +The valid data types for a parameter are: + +- `array` for arrays +- `bool` for booleans +- `int` for integers +- `object` for objects +- `string` for strings +- `secureobject` for secure objects +- `securestring` for secure strings + +Access parameters in a configuration using this syntax: + +```yaml +"[parameter('')]" +``` + +In YAML, the parameter syntax needs to be enclosed in double-quotes when used as an inline value. If the syntax isn't quoted, YAML interprets the syntax as an array. + +```yaml +valid: "[parameter('example')]" +# This unquoted syntax: +invalid: [parameter('example')] +# Evaluates to this YAML: +invalid: + - parameter('example') +``` + +## Arrays + +Arrays are a list of one or more values. The values in the array can be any valid data type. Values in the array can be the same type or different types. + +```yaml +parameters: + exampleIntArray: + type: array + defaultValue: + - 1 + - 2 + - 3 + exampleMixedArray: + type: array + defaultValue: + - 1 + - true + - example string +``` + +Access items in an array can by their index. The first item in an array is index `0`. Use this +syntax to access an index in an array parameter: + +```yaml +"[parameter('')[]]" +``` + +```yaml +parameters: + members: + type: array + defaultValue: + - first + - second + - third +resources: + # Use the entire array as the value for a resource property + - name: Operators Group + type: Example.Security/Group + properties: + groupName: operators + members: "[parameter('members')]" + # Use a single item in the array as the value for a resource property + - name: Admin Group + type: Example.Security/Group + properties: + groupName: admins + members: + - "[parameter('members')[0]]" +``` + +## Booleans + +Boolean values are either `true` or `false`. + +```yaml +parameters: + exampleBool: + type: bool + defaultValue: true +``` + +## Integers + +Integer values are numbers without a fractional part. Integer values may be limited by integrating tools or the DSC Resources they're used with. DSC itself supports integer values between `-9223372036854775808` and `9223372036854775807`. + +```yaml +parameters: + exampleInt: + type: int + defaultValue: 12 +``` + +## Objects + +Objects define a set of key-value pairs. The value for each key can be any valid data type. The +values can be the same type or different types. + +```yaml +parameters: + exampleObject: + type: object + defaultValue: + scope: machine + updateAutomatically: true + updatefrequency: 30 +``` + +Access keys in the object using dot-notation. Dot-notation uses this syntax: + +```yaml +"[parameters('').] +``` + +```yaml +parameters: + tstoy: + type: object + defaultValue: + scope: machine + updateAutomatically: true + updatefrequency: 30 + registryKeys: + type: object + defaultValue: + productName: + keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion + valueName: ProductName + systemRoot: + keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion + valueName: SystemRoot +resources: + # Use the base object for the property definition + - name: TSToy + type: TSToy.Example/gotstoy + properties: "[parameter('tstoy')]" + # Use dot-notation for the property definition + - name: Windows Product Name + type: Microsoft.Windows/Registry + properties: "[parameter('registryKeys').productName]" + # Use dot-notation for each value in the property definition + - name: Windows System Root + type: Microsoft.Windows/Registry + properties: + keyPath: "[parameters('registryKeys').systemRoot.keyPath]" + valueName: "[parameters('registryKeys').systemRoot.valueName]" +``` + +## Strings + +Strings are an arbitrary set of text. + +```yaml +parameters: + exampleString: + type: string + defaultValue: This example includes spaces and 'quoted' "text." +``` + +To define a long string without newlines in YAML, use the folded block syntax by adding a `>` and a line break after the key. Then, indent the next line. Every line in the string must start +at the same level of indentation. The lines are combined with a single space instead of newlines. +To trim trailing whitespace, use `>-` instead of `>`. + +```yaml +parameters: + foldedBlockExample: + type: string + defaultValue: >- + This example spans multiple lines + in the definition, but the lines are + joined with spaces instead of newlines. +``` + +To define a long string with newlines in YAML, use the literal block syntax by adding a `|` and a +line break after the key. Then, indent the next line. Every line in the string must start at the +same level of indentation or higher. The lines are interpreted literally, but with the leading +indentation removed. If any lines after the first line are indented more than the first line, only +the extra indentation is preserved. To trim trailing whitespace, use `|-` instead of `|`. + +```yaml +parameters: + literalBlockExample: + type: string + defaultValue: |- + This example spans multiple lines + in the definition. + + It can even include paragraphs. + + When a line is indented further + than the first line, that extra + indentation is preserved. +``` + +## Secure strings and objects + +Secure strings use the same format as strings and secure objects use the same format as objects. +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. Never define a default value for secure string or +secure object parameters. + +```yaml +parameters: + password: + type: securestring + sensitiveOptions: + type: secureobject +``` diff --git a/docs/reference/schemas/resource/manifest/get.md b/docs/reference/schemas/resource/manifest/get.md new file mode 100644 index 000000000..fcfbc94fb --- /dev/null +++ b/docs/reference/schemas/resource/manifest/get.md @@ -0,0 +1,114 @@ +# Command-based DSC Resource manifest schema reference + +## Synopsis + +Defines how to retrieve a DSC Resource instance. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.json +Type : object +``` + +## Description + +Every command-based DSC Resource must define the `get` property in its manifest. This property +defines how DSC can get the current state of a resource instance. + +## Examples + +### Example 1 - Minimal definition + +This example is from the `Microsoft/OSInfo` DSC Resource. + +```json +"get": { + "executable": "osinfo" +} +``` + +It only defines the `executable` property. When a manifest doesn't define `args`, DSC passes no +arguments to the command. When a manifest doesn't define `input`, the default behavior is to send a +JSON blob to the command over `stdin`. + +With this definition, DSC calls the `get` method for this resource by running: + +```sh +{ ... } | osinfo +``` + +### Example 2 - Full definition + +This example is from the `Microsoft.Windows/Registry` DSC Resource. + +```json +"get": { + "executable": "registry", + "args": [ + "config", + "get" + ], + "input": "stdin" +} +``` + +It defines `executable` as `registry`, rather than `registry.exe`. The extension isn't required +when the operating system recognizes the command as an executable. The manifest defines two +arguments, `config` and `get`. The `input` property indicates that the `get` command expects its +input as a JSON blob from `stdin`. Combined with the value for `executable`, DSC calls the get +method for this resource by running: + +```sh +{ ... } | registry config get +``` + +## Required Properties + +The `get` definition must include these properties: + +- [executable](#executable) + +## Properties + +### executable + +The `executable` property defines the name of the command to run. The value must be the name of a +command discoverable in the system's `PATH` environment variable or the full path to the command. A +file extension is only required when the command isn't recognizable by the operating system as an +executable. + +```yaml +Type: string +Required: true +``` + +### args + +The `args` property defines an array of strings to pass as arguments to the command. DSC passes the +arguments to the command in the order they're specified. + +```yaml +Type: array +Required: false +Default: [] +``` + +### input + +The `input` property defines how to pass input to the resource. The value of this property must +be one of the following strings: + +- `args` - Indicates that the resource expects the properties of an instance to be specified with + command line arguments. This option isn't implemented yet. +- `stdin` - Indicates that the resource expects a JSON blob representing an instance from `stdin`. + +```yaml +Type: string +Required: false +Default: stdin +Valid Values: + - args + - stdin +``` diff --git a/docs/reference/schemas/resource/manifest/provider.md b/docs/reference/schemas/resource/manifest/provider.md new file mode 100644 index 000000000..de66e0dd6 --- /dev/null +++ b/docs/reference/schemas/resource/manifest/provider.md @@ -0,0 +1,122 @@ +# DSC Resource manifest provider property schema reference + +## Synopsis + +Defines a DSC Resource as a DSC Resource Provider. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.json +Type : object +``` + +## Description + +DSC Resource Providers must define the `provider` property in their manifest. This property +identifies the resource as a provider and defines how DSC can call the provider to get the +resources the provider supports and how to pass resource instances to the provider. + +## Examples + +### Example 1 - DSC/PowerShellGroup + +This example is from the `DSC/PowerShellGroup` DSC Resource Provider. + +```json +"provider": { + "config": "full", + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo" + "-NonInteractive" + "-NoProfile" + "-Command" + "./powershellgroup.resource.ps1 List" + ] + } +} +``` + +The manifest sets `config` to `full`, indicating that the provider expects a JSON blob representing +the full and unprocessed configuration from `stdin`. + +It defines `list.executable` as `pwsh`. The arguments defined in `list.args` ensure that DSC runs +PowerShell: + +- Without the logo banner +- In non-interactive mode +- Without loading any profile scripts +- To invoke the `powershellgroup.resource.ps1` script in the same folder as the `dsc` command and + pass the `List` argument. + +With this definition, DSC calls the `list` method for this provider by running: + +```sh +pwsh -NoLogo -NonInteractive -NoProfile -Command "./powershellgroup.resource.ps1 List" +``` + +## Required Properties + +The `provider` definition must include these properties: + +- [config](#config) +- [list](#list) + +## Properties + +### config + +The `config` property defines how the provider expects to receive resource configurations. The +value must be one of the following options: + +- `full` - Indicates that the provider expects a JSON blob containing the full and + unprocessed configuration as a single JSON blob over `stdin`. +- `sequence` - Indicates that the provider expects each resource's configuration as + a [JSON Line][01] over `stdin`. + +```yaml +Type: string +Valid Values: + - full + - sequence +``` + +### list + +The `list` property defines how to call the provider to list the resources it supports. The value +of this property must be an object and define the `executable` subproperty. + +```yaml +Type: object +Required: true +Required Properties: + - executable +``` + +#### executable + +The `executable` subproperty defines the name of the command to run. The value must be the name of +a command discoverable in the system's `PATH` environment variable or the full path to the command. +A file extension is only required when the command isn't recognizable by the operating system as an +executable. + +```yaml +Type: string +Required: true +``` + +#### args + +The `args` subproperty defines an array of strings to pass as arguments to the command. DSC passes +the arguments to the command in the order they're specified. + +```yaml +Type: array +Required: false +Default: [] +``` + +[01]: https://jsonlines.org/ diff --git a/docs/reference/schemas/resource/manifest/root.md b/docs/reference/schemas/resource/manifest/root.md new file mode 100644 index 000000000..1f2a5b955 --- /dev/null +++ b/docs/reference/schemas/resource/manifest/root.md @@ -0,0 +1,222 @@ +# Command-based DSC Resource manifest schema reference + +## Synopsis + +The JSON file that defines a command-based DSC Resource. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/manifest.json +Type : object +``` + +## Description + +Every command-based DSC Resource must have a manifest. The manifest must: + +1. Be discoverable in the `PATH` environment variable. +1. Follow the naming convention `.resource.json`. +1. Be valid for the schema described in this document. + +The rest of this document describes the manifest's schema. + +## Required properties + +The manifest must include these properties: + +- [manifestVersion](#manifestversion) +- [type](#type) +- [version](#version) +- [get](#get) + +## Properties + +### manifestVersion + +The `manifestVersion` property indicates the semantic version (semver) of this schema that the +manifest validates against. This property is mandatory. DSC uses this value to validate the +manifest against the correct JSON schema. + +```yaml +Type: string +Required: true +Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ +Valid Values: + - '1.0' +``` + +### type + +The `type` property represents the fully qualified the name of the resource in its namespace. It's +used to specify the resource in configuration documents and as the value of the `--resource` flag +when using the `dsc resource *` commands. This value must use the following syntax: + +```text +`[.][.]/` +``` + +Each component must be string of alphanumeric characters and underscores. No other characters are +permitted. Every resource must define an `owner` and a `name`. Use the `group` and `area` +components to organize resources into related namespaces. For example: + +- `Microsoft.SqlServer/Database` +- `Microsoft.SqlServer.Database/Role` +- `Microsoft.SqlServer.Database/User` +- `Microsoft.SqlServer/Endpoint` +- `Microsoft.SqlServer.Endpoint/Permission` +- `Microsoft.SqlServer/Login` +- `Microsoft.SqlServer/MaxDop` + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +### version + +The `version` property must be the current version of the resource as a valid semantic version +(semver) string. The version applies to the resource, not the software it manages. + +```yaml +Type: string +Required: true +Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ +``` + +### description + +The `description` property defines a synopsis for the resource's purpose. The value for this +property must be a short string. + +```yaml +Type: string +Required: false +``` + +### tags + +The `tags` property defines a list of searchable terms for the resource. The value of this +property must be an array of strings. Each tag must contain only alphanumeric characters and +underscores. No other characters are permitted. Each tag must be unique. + +```yaml +Type: array +Required: false +Valid Items: + Type: string + Pattern: ^\w+$ + Unique: true +``` + +### get + +The `get` property defines how to call the resource to get the current state of an instance. This +property is mandatory for all resources. + +The value of this property must be an object. The object's `executable` property, defining the name +of the command to call, is mandatory. The `args` and `input` properties are optional. For more +information, see [DSC Resource manifest get property schema reference][01]. + +```yaml +Type: object +Required: true +``` + +### set + +The `set` property defines how to call the resource to set the desired state of an instance. It +also defines how to process the output from the resource for this method. When this property isn't +defined, the DSC can't manage instances of the resource. It can only get their current state and +test whether the instance is in the desired state. + +The value of this property must be an object. The `executable` property, defining the name of the +command to call, is mandatory. The `args` `input`, `preTest`, and `returns` properties are +optional. For more information, see [DSC Resource manifest set property schema reference][02]. + +```yaml +Type: object +Required: false +``` + +### test + +The `test` property defines how to call the resource to test whether an instance is in the desired +state. It also defines how to process the output from the resource for this method. When this +property isn't defined, DSC performs a basic synthetic test for instances of the DSC Resource. + +The value of this property must be an object. The object's `executable` property, defining the name +of the command to call, is mandatory. The `args` `input`, and `returns` properties are optional. +For more information, see [DSC Resource manifest test property schema reference][03]. + +```yaml +Type: object +Required: false +``` + +### validate + +The `validate` property defines how to call a DSC Group Resource to validate its instances. This +property is mandatory for DSC Group Resources. DSC ignores this property for all other resources. + +The value of this property must be an object. The object's `executable` property, defining the name +of the command to call, is mandatory. The `args` property is optional. For more information, see +[DSC Resource manifest validate property schema reference][04]. + +```yaml +Type: object +Required: false +``` + +### provider + +When specified, the `provider` property defines the resource as a DSC Resource Provider. + +The value of this property must be an object. The object's `list` and `config` properties are +mandatory. The `list` property defines how to call the provider to return the resources that the +provider can manage. The `config` property defines how the provider expects input. For more +information, see the [DSC Resource manifest provider property schema reference][05]. + +### exitCodes + +The `exitCodes` property defines a set of valid exit codes for the resource and their meaning. +Define this property as a set of key-value pairs where: + +- The key is a string containing an integer that maps to a known exit code for the resource. +- The value is a string describing the semantic meaning of that exit code for a human reader. + +DSC interprets exit code `0` as a successful operation and any other exit code as an error. + +```yaml +Type: object +Required: false +Valid Properties: + Name Pattern: ^[0-9]+# + Value Type: string +``` + +### schema + +The `schema` property defines how to get the JSON schema that validates an instance of the +resource. This property must always be an object that defines one of the following properties: + +- `command` - When you specify the `command` property, DSC calls the defined command to get the + JSON schema. +- `embedded` - When you specify the `embedded` property, DSC uses the defined value as the JSON + schema. + +For more information, see [DSC Resource manifest schema property reference][06]. + +```yaml +Type: object +Required: true +``` + +[01]: get.md +[02]: set.md +[03]: test.md +[04]: validate.md +[05]: provider.md +[06]: schema.md diff --git a/docs/reference/schemas/resource/manifest/schema/embedded.md b/docs/reference/schemas/resource/manifest/schema/embedded.md new file mode 100644 index 000000000..13b63d377 --- /dev/null +++ b/docs/reference/schemas/resource/manifest/schema/embedded.md @@ -0,0 +1,161 @@ +# DSC Resource manifest embedded schema reference + +## Synopsis + +Defines a JSON Schema that validates a DSC Resource instance. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.json#/properties/embedded +Type : object +``` + +## Description + +The `embedded` subproperty defines a full JSON schema for a DSC Resource's instances. DSC uses the +JSON schema to validate every instance of the resource before calling the resource's commands and +after receiving an instance as output from the resource. + +Embedded JSON schemas are also used by integrating and authoring tools like VS Code to validate +resource instances and provide IntelliSense. + +## Required keywordds + +The `embedded` definition must include these keywords: + +- [$schema](#schema) +- [type](#type) +- [properties](#properties) + +## Keywords + +### $schema + +The `$schema` keyword defines the dialect of JSON Schema the resource's instance schema uses. DSC +uses this keyword when processing the schema. The dialect defines which keywords are available and +how to interpret them. + +DSC only supports JSON Schema Draft 07 and later. + +```yaml +Type: string +Required: true +Format: uri-reference +Valid Values: + - https://json-schema.org/draft/2020-12/schema + - https://json-schema.org/draft/2019-09/schema + - http://json-schema.org/draft-07/schema# +``` + +### $id + +The `$id` keyword defines the unique ID for the instance schema. If the instance schema is published +to its own public URI, set this keyword to that URI. + +```yaml +Type: string +Required: false +Format: uri-reference +``` + +### type + +The `type` keyword defines what kind of value the instance is. Instances must be objects. Set this +keyword to `object`. + +```yaml +Type: string +Required: true +Valid Value: object +``` + +### properties + +The `properties` keyword defines the properties that DSC can retrieve and manage for the resource's +instances. This keyword must define at least one property as a key-value pair. The key is the +property's name. The value is a subschema that validates the property. + +Resources can define any properties they need for managing instances. DSC defines shared schemas +for well-known properties. Some well-known properties enable a DSC Resource to use built-in +processing. The well-known properties always start with an underscore (`_`) and DSC Resources that +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) +- [_inDesiredState](#_indesiredstate) +- [_purge](#_purge) +- [_rebootRequested](#_rebootrequested) + +#### _ensure + +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. + +If defined, this property must be a reference to the schema for the well-known property: + +```json +"_ensure": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json" +} +``` + +For more information, see [DSC Resource _ensure property schema][01]. + +#### _inDesiredState + +The read-only `_inDesiredState` property indicates whether a resource instance is in the desired +state. This property is mandatory for command-based DSC Resources that define the [test][02] +property. + +If defined, this property must be a reference to the schema for the well-known property: + +```json +"_inDesiredState": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json" +} +``` + +For more information, see [DSC Resource _inDesiredState property schema][03]. + +#### _purge + +Resources that need to distinguish between whether unmanaged entries in a list are valid or must be +removed can define the write-only `_purge` property. This property provides shared semantics for +DSC Resources and integrating tools, but doesn't enable any built-in processing with DSC. + +If defined, this property must be a reference to the schema for the well-known property: + +```json +"_inDesiredState": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json" +} +``` + +For more information, see [DSC Resource _purge property schema][04]. + +#### _rebootRequested + +The read-only `_rebootRequested` property indicates whether a resource instance requires a reboot +after a set operation. To use DSC's built-in reboot notification processing, resources must define +this property in their manifest. + +If defined, this property must be a reference to the schema for the well-known property: + +```json +"_rebootRequested": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json" +} +``` + +For more information, see [DSC Resource _rebootRequested property schema][05] + +[01]: ../../properties/ensure.md +[02]: ../test.md +[03]: ../../properties/inDesiredState.md +[04]: ../../properties/purge.md +[05]: ../../properties/rebootRequested.md diff --git a/docs/reference/schemas/resource/manifest/schema/property.md b/docs/reference/schemas/resource/manifest/schema/property.md new file mode 100644 index 000000000..8cd6bf4c6 --- /dev/null +++ b/docs/reference/schemas/resource/manifest/schema/property.md @@ -0,0 +1,153 @@ +# DSC Resource manifest schema property reference + +## Synopsis + +Defines how to retrieve the JSON Schema that validates a DSC Resource instance. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.json +Type : object +``` + +## Description + +Every command-based DSC Resource must define the `schema` property in its manifest. This property +defines how DSC can get the JSON schema it needs to validate instances of the resource. + +The JSON schema can be defined dynamically with the [command](#command) property or statically with +the [embedded](#embedded) property. + +For development purposes, it can be more convenient to use the `command` property and avoid needing +to adjust both the code and the schema. + +Microsoft recommends using the `embedded` property when publishing a resource publicly. When the +manifest declares the schema with the `command` property, DSC calls the command at the beginning of +any operation using the resource, possibly impacting performance. The schema is also unavailable to +integrating tools when the resource isn't installed locally. When the schema is embedded in the +manifest, DSC and integrating tools only need the manifest itself. + +## Examples + +### Example 1 - Get JSON schema with a command + +This example is from the `Microsoft.Windows/Registry` DSC Resource. + +```json +"schema": { + "command": { + "executable": "registry", + "args": ["schema"] + } +} +``` + +With the `command` property defined, DSC gets the JSON schema to validate instances of this +resource with the following command: + +```sh +registry schema +``` + +### Example 2 - Embedded JSON schema + +This example is from the `Microsoft/OSInfo` DSC Resource. It defines an embedded JSON schema that +DSC uses to validate an instance of the resource. + +```json +"schema": { + "embedded": { + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "OSInfo", + "type": "object", + "required": [], + "properties": { + "$id": { "type": "string" }, + "architecture": { "type": ["string","null"] }, + "bitness": { "$ref": "#/definitions/Bitness" }, + "codename": { "type": ["string","null"] }, + "edition": { "type": ["string","null"] }, + "family": { "$ref": "#/definitions/Family" }, + "version": { "type": "string" } + }, + "additionalProperties": false, + "definitions": { + "Bitness": { "type": "string", "enum": ["32","64","unknown"] }, + "Family": { "type": "string", "enum": ["Linux","macOS","Windows"] } + } + } +} +``` + +## Required Properties + +The `schema` definition must include exactly one of these properties: + +- [command](#command) +- [embedded](#embedded) + +## Properties + +### command + +The `command` property defines how DSC must call the resource to get the JSON schema that validates +its instances. The value of this property must be an object and define the `executable` property. + +When publishing a manifest with the `command` property, Microsoft recommends publishing the JSON +schema to a publicly available URI and setting the `url` property to that URI. This enables +authoring tools and other integrating applications to validate instances without running the +command locally. + +```yaml +Type: object +Required Properties: + - executable +``` + +#### executable + +The `executable` property defines the name of the command to run. The value must be the name of a +command discoverable in the system's `PATH` environment variable or the full path to the command. A +file extension is only required when the command isn't recognizable by the operating system as an +executable. + +```yaml +Type: string +Required: true +``` + +#### args + +The `args` property defines an array of strings to pass as arguments to the command. DSC passes the +arguments to the command in the order they're specified. + +```yaml +Type: array +Required: false +Default: [] +``` + +### embedded + +The `embedded` property defines the full JSON schema for DSC to validate instances of the DSC +Resource. The value for this property must be a valid JSON schema that defines the `$schema`, `type`, and `properties` keywords. + +```yaml +Type: object +Minimum Property Count: 1 +``` + +### url + +The `url` property defines the URL to the resource's published JSON schema. It's used by +integrating tools for resources that define the `command` property instead of the `embedded` +property. + + + +```yaml +Type: string +Format: uri +``` diff --git a/docs/reference/schemas/resource/manifest/set.md b/docs/reference/schemas/resource/manifest/set.md new file mode 100644 index 000000000..562779c67 --- /dev/null +++ b/docs/reference/schemas/resource/manifest/set.md @@ -0,0 +1,145 @@ +# DSC Resource manifest set property schema reference + +## Synopsis + +Defines how to enforce state for a DSC Resource instance. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.json +Type : object +``` + +## Description + +To manage an instance with DSC, a DSC Resource must define the `set` property in its manifest. This +property defines how DSC can enforce the current state of an instance. + +When this property isn't defined, DSC can only get the current state of instances and test whether +they're in the desired state. DSC can't enforce desired state for the resource. + +## Examples + +### Example 1 - Full definition + +This example is from the `Microsoft.Windows/Registry` DSC Resource. + +```json +"set": { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "preTest": true, + "return": "state" +} +``` + +It defines `executable` as `registry`, rather than `registry.exe`. The extension isn't required +when the operating system recognizes the command as an executable. + +The manifest defines two arguments, `config` and `set`. The value of the `input` property indicates +that the `set` command expects its input as a JSON blob from `stdin`. + +Combined with the value for `executable`, DSC calls the set method for this resource by +running: + +```sh +{ ... } | registry config set +``` + +Because the manifest defines `preTest` as `true`, DSC won't call the `test` method for the resource +before calling `set`. This setting indicates that the resource itself tests instances before +enforcing their desired state. + +The manifest defines `return` as `state`, indicating that it only returns the final state of the +resource after the `set` method runs. DSC compares the desired state to the return data of this +resource to identify which of the resource's properties the `set` method enforced, if any. + +## Required Properties + +The `set` definition must include these properties: + +- [executable](#executable) + +## Properties + +### executable + +The `executable` property defines the name of the command to run. The value must be the name of a +command discoverable in the system's `PATH` environment variable or the full path to the command. A +file extension is only required when the command isn't recognizable by the operating system as an +executable. + +```yaml +Type: string +Required: true +``` + +### args + +The `args` property defines an array of strings to pass as arguments to the command. DSC passes the +arguments to the command in the order they're specified. + +```yaml +Type: array +Required: false +Default: [] +``` + +### input + +The `input` property defines how to pass input to the resource. The value of this property must +be one of the following strings: + +- `args` - Indicates that the resource expects the properties of an instance to be specified + with command line arguments. This option isn't implemented yet. +- `stdin` - Indicates that the resource expects a JSON blob representing an instance from + `stdin`. + +```yaml +Type: string +Required: false +Default: stdin +Valid Values: + - args + - stdin +``` + +### preTest + +The `preTest` property defines whether the resource tests the instance internally before +enforcing the desired state. Set this property to `true` when the resource tests the instance. +Set this property to `false` to ensure DSC tests the instance first instead. The default value +is `false`. + +```yaml +Type: boolean +Required: false +Default: false +``` + +### return + +The `return` property defines how DSC should process the output for this method. The value of this +property must be one of the following strings: + +- `state` - Indicates that the resource returns only the instance's final state after the set + operation as a JSON blob. +- `stateAndDiff` - Indicates that the resource returns the instance's final state and an array of + property names that the resource modified. + +The default value is `state`. + +```yaml +Type: string +Required: false +Default: state +Valid Values: + - state + - stateAndDiff +``` diff --git a/docs/reference/schemas/resource/manifest/test.md b/docs/reference/schemas/resource/manifest/test.md new file mode 100644 index 000000000..d5d50d85a --- /dev/null +++ b/docs/reference/schemas/resource/manifest/test.md @@ -0,0 +1,139 @@ +# DSC Resource manifest test property schema reference + +## Synopsis + +Defines how to test whether a DSC Resource instance is in the desired state. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.json +Type : object +``` + +## Description + +If a DSC Resource implements its own logic for determining whether an instance is in the desired +state, it must define the `test` property in its manifest. This property defines how DSC can call +the resource to test whether an instance is in the desired state. + +When this property isn't defined, DSC uses a synthetic test method for the resource. The synthetic +test method: + +1. Gets the actual state of the instance using the resource's `get` method. +1. Compares every defined property of the instance's desired state to the actual state. +1. If the desired state of a property isn't equal to the actual state of that property, DSC reports + that the instance isn't in the desired state. + +Because the synthetic test only checks for equivalency, it can't accurately test resources with +properties that can't be evaluated with equivalency alone. For example, if a resource manages +package versions and allows setting the version to `latest`, DSC would report an instance with a +version of `3.1.0` as being out of the desired state, even if `3.1.0` is the latest version of the +package. + +For resources with properties that can't be evaluated by equivalency alone, always define the +`test` property in the manifest. + +## Examples + +### Example 1 - Full definition + +This example is from the `Microsoft.Windows/Registry` DSC Resource. + +```json +"test": { + "executable": "registry", + "args": [ + "config", + "test" + ], + "input": "stdin", + "return": "state" +} +``` + +It defines `executable` as `registry`, rather than `registry.exe`. The extension isn't required +when the operating system recognizes the command as an executable. + +The manifest defines two arguments, `config` and `test`. The value of the `input` property +indicates that the `test` command expects its input as a JSON blob from `stdin`. + +Combined with the value for `executable`, DSC calls the `test` method for this resource by running: + +```sh +{ ... } | registry config test +``` + +The manifest defines `return` as `state`, indicating that it only returns the actual state of the +resource when the `test` method runs. + +## Required Properties + +The `test` definition must include these properties: + +- [executable](#executable) + +## Properties + +### executable + +The `executable` property defines the name of the command to run. The value must be the name of a +command discoverable in the system's `PATH` environment variable or the full path to the command. A +file extension is only required when the command isn't recognizable by the operating system as an +executable. + +```yaml +Type: string +Required: true +``` + +### args + +The `args` property defines an array of strings to pass as arguments to the command. DSC passes the +arguments to the command in the order they're specified. + +```yaml +Type: array +Required: false +Default: [] +``` + +### input + +The `input` property defines how to pass input to the resource. The value of this property must +be one of the following strings: + +- `args` - Indicates that the resource expects the properties of an instance to be specified + with command line arguments. This option isn't implemented yet. +- `stdin` - Indicates that the resource expects a JSON blob representing an instance from + `stdin`. + +```yaml +Type: string +Required: false +Default: stdin +Valid Values: + - args + - stdin +``` + +### return + +The `return` property defines how DSC should process the output for this method. The value of this +property must be one of the following strings: + +- `state` - Indicates that the resource returns only the instance's actual state. +- `stateAndDiff` - Indicates that the resource returns the instance's actual state and an array of + property names that are out of the desired state. + +The default value is `state`. + +```yaml +Type: string +Required: false +Default: state +Valid Values: + - state + - stateAndDiff +``` diff --git a/docs/reference/schemas/resource/manifest/validate.md b/docs/reference/schemas/resource/manifest/validate.md new file mode 100644 index 000000000..dfb50be27 --- /dev/null +++ b/docs/reference/schemas/resource/manifest/validate.md @@ -0,0 +1,77 @@ +# DSC Resource manifest validate property schema reference + +## Synopsis + +This property + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.json +Type : object +``` + +## Description + +DSC Group Resources must define the `validate` property in their DSC Resource manifest. This +property defines how DSC can call the group resource to test whether instances in the group +have valid definitions. + +Always define the `validate` property for group resources in the DSC Resource manifest. + +## Examples + +### Example 1 - Full definition + +This example is from the `DSC/AssertionGroup` DSC Group Resource. + +```json +"validate": { + "executable": "dsc", + "args": [ + "config", + "validate" + ] +} +``` + +It defines the executable as `dsc` with the arguments `config` and `validate`. The `validate` +method always sends the method's input as a JSON blob over `stdin`. + +With this definition, DSC calls the `validate` method for this DSC Group Resource by running: + +```sh +{ ... } | dsc config validate +``` + +## Required Properties + +The `validate` definition must include these properties: + +- [executable](#executable) + +## Properties + +### executable + +The `executable` property defines the name of the command to run. The value must be the name of a +command discoverable in the system's `PATH` environment variable or the full path to the command. A +file extension is only required when the command isn't recognizable by the operating system as an +executable. + +```yaml +Type: string +Required: true +``` + +### args + +The `args` property defines an array of strings to pass as arguments to the command. DSC passes the +arguments to the command in the order they're specified. + +```yaml +Type: array +Required: false +Default: [] +``` diff --git a/docs/reference/schemas/resource/properties/ensure.md b/docs/reference/schemas/resource/properties/ensure.md new file mode 100644 index 000000000..a5e082bfd --- /dev/null +++ b/docs/reference/schemas/resource/properties/ensure.md @@ -0,0 +1,48 @@ +# DSC Resource _ensure property schema + +## Synopsis + +Indicates whether an instance should exist. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json +Type : string +Valid Values : [Absent, Present] +``` + +## Description + +The `_ensure` property indicates that the resource can enforce whether instances exist using the +shared present and absent semantics. + +When `_ensure` is set to `Present` for the desired state, the instance is expected to exist. If it +doesn't exist, the resource creates the instance during the set operation. + +When `_ensure` is set to `Absent` for the desired state, the instance is expected to not exist. If +it does exist, the resource removes the instance during the set operation. + +To add this property to a resource's instance schema, define the property with the following snippet: + +```json +"_ensure": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json" +} +``` + +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. + +For example, a resource that manages a file might be designed to ensure whether the file exists, is +specifically a file, or exists as a symlink. In that case, the resource would define its own +`ensure` property, such as with the snippet below. + +```json +"ensure": { + "type": "string", + "enum": ["present", "absent", "file", "symlink"], + "default": "present" +} +``` diff --git a/docs/reference/schemas/resource/properties/inDesiredState.md b/docs/reference/schemas/resource/properties/inDesiredState.md new file mode 100644 index 000000000..75b7c2188 --- /dev/null +++ b/docs/reference/schemas/resource/properties/inDesiredState.md @@ -0,0 +1,44 @@ +# DSC Resource _inDesiredState property schema + +## Synopsis + +Indicates whether an instance is in the desired state. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json +Type : [boolean, 'null'] +Read Only : true +``` + +## Description + +The `_inDesiredState` property indicates whether a resource instance is in the desired state. +Whether a resource's instance schema should include this property depends on whether the resource's +[manifest][01] defines the [test][02] property. + +If the resource's manifest doesn't define `test`, the resource relies on DSC's synthetic test. The +resource's instance schema must not include the `_inDesiredState` property. + +If the resource's manifest defines `test`, the instance schema must include the `_inDesiredState` +property. When the resource returns the state of an instance for the get and set operations, +`_inDesiredState` must be `null`. When the resource returns the state of an instance for the test +operation, `_inDesiredState` must be `true` if the instance is in the desired state and otherwise +`false`. + +This property is read-only. The resource returns instances with this property, but the desired +state can't include it. + +To add this property to a resource's instance schema, define the property with the following +snippet: + +```json +"_inDesiredState": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json" +} +``` + +[01]: ../manifest/root.md +[02]: ../manifest/test.md diff --git a/docs/reference/schemas/resource/properties/overview.md b/docs/reference/schemas/resource/properties/overview.md new file mode 100644 index 000000000..d8ba9b6e4 --- /dev/null +++ b/docs/reference/schemas/resource/properties/overview.md @@ -0,0 +1,47 @@ +# DSC well-known properties + +DSC has support for several well-known properties. Some well-known properties enable a DSC Resource +to use built-in processing. The well-known properties always start with an underscore (`_`) and DSC +Resources that use these properties may not override or extend them. + +## _ensure + +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. + +For more information, see [DSC Resource _ensure property schema][01]. + +## _inDesiredState + +The read-only `_inDesiredState` property indicates whether a resource instance is in the desired +state. This property is mandatory for command-based DSC Resources that define the [test][02] +property in their [manifest][03]. + +For more information, see [DSC Resource _inDesiredState property schema][04]. + +## _purge + +DSC Resources that need to distinguish between whether unmanaged entries in a list are valid or +must be removed can define the write-only `_purge` property. This property provides shared +semantics for DSC Resources and integrating tools, but doesn't enable any built-in processing with +DSC. + +For more information, see [DSC Resource _purge property schema][05]. + +## _rebootRequested + +The read-only `_rebootRequested` property indicates whether a resource instance requires a reboot +after a set operation. To use DSC's built-in reboot notification processing, resources must define +this property in their manifest. + +For more information, see [DSC Resource _rebootRequested property schema][06]. + +[01]: ensure.md +[02]: ../manifest/test.md +[03]: ../manifest/root.md +[04]: inDesiredState.md +[05]: purge.md +[06]: rebootRequested.md diff --git a/docs/reference/schemas/resource/properties/purge.md b/docs/reference/schemas/resource/properties/purge.md new file mode 100644 index 000000000..f13acbcb5 --- /dev/null +++ b/docs/reference/schemas/resource/properties/purge.md @@ -0,0 +1,42 @@ +# DSC Resource _purge property schema + +## Synopsis + +Indicates that the resource should treat non-defined entries in a list as invalid. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json +Type : [boolean, 'null'] +Write Only : true +``` + +## Description + +DSC Resources that need to distinguish between whether unmanaged entries in a list are valid or +must be removed can define the `_purge` property. + +When a resource's instance schema defines this property, it indicates that the resource changes its +behavior based on the property's value in an instance's desired state: + +- When `_purge` is `true`, the resource removes unmanaged entries. The resource treats any entries + not listed in the instance's desired state as invalid. +- When `_purge` is `false` or not specified, the resource ignores unmanaged entries. + +When a resource defines this property, it should always document which property or properties +`_purge` affects. A resource may define `_purge` as a subproperty for a complex property. + +This property is write-only. A resource that uses the `_purge` property should never return +`_purge` in the instance's output state. A resource must not define `_purge` as a mandatory +property. + +To add this property to a resource's instance schema, define the property with the following +snippet: + +```json +"_inDesiredState": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json" +} +``` diff --git a/docs/reference/schemas/resource/properties/rebootRequested.md b/docs/reference/schemas/resource/properties/rebootRequested.md new file mode 100644 index 000000000..809c2939f --- /dev/null +++ b/docs/reference/schemas/resource/properties/rebootRequested.md @@ -0,0 +1,41 @@ +# DSC Resource _rebootRequested property schema + +## Synopsis + +Indicates whether an instance is in the desired state. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json +Type : [boolean, 'null'] +Read Only : true +``` + +## Description + +The `_rebootRequested` property indicates whether a resource instance requires a reboot after a set +operation. + +If the resource determines during a set operation that the node needs to reboot before the state +change takes full effect, it should return the instance's data with the `_rebootRequested` property +set to `true`. If a resource returns an instance from the set operation with the `_rebootRequested` +property set to `true`, DSC generates a reboot notification. + +If the resource returns an instance from the set operation without the `_rebootRequested` property +defined, or if the property value is `false`, DSC doesn't generate a reboot notification. + +Resources must define this property to use DSC's built-in reboot request notifications. + +This property is read-only. The resource returns instances with this property, but the desired +state can't include it. + +To add this property to a resource's instance schema, define the property with the following +snippet: + +```json +"_rebootRequested": { + "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json" +} +``` From abea7b73a6a2adefea0607c913708074cc845c3d Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Tue, 1 Aug 2023 16:30:25 -0500 Subject: [PATCH 07/11] (DOCS) Update schemas and docs for schema changes --- docs/reference/schemas/config/document.md | 18 +- docs/reference/schemas/config/parameter.md | 8 +- docs/reference/schemas/config/resource.md | 11 +- .../definitions/parameters/dataTypes.md | 21 +- .../schemas/definitions/resourceType.md | 65 +++++ .../schemas/resource/manifest/root.md | 52 ++-- .../resource/manifest/schema/property.md | 3 +- .../schemas/resource/properties/ensure.md | 3 +- docs/schemas/bundled/config.document.json | 224 +++-------------- .../bundled/config.document.vscode.json | 230 +++--------------- .../bundled/config.document.vscode.yaml | 186 +++----------- docs/schemas/bundled/config.document.yaml | 185 +++----------- docs/schemas/bundled/outputs.config.get.json | 8 +- docs/schemas/bundled/outputs.config.set.json | 16 +- docs/schemas/bundled/outputs.config.test.json | 26 +- .../schemas/bundled/outputs.resource.get.json | 8 +- .../bundled/outputs.resource.list.json | 8 +- .../schemas/bundled/outputs.resource.set.json | 16 +- .../bundled/outputs.resource.test.json | 26 +- docs/schemas/bundled/resource.manifest.json | 1 + .../bundled/resource.manifest.vscode.json | 1 + .../bundled/resource.manifest.vscode.yaml | 1 + docs/schemas/bundled/resource.manifest.yaml | 1 + docs/schemas/outputs/resource/get.yaml | 8 +- docs/schemas/outputs/resource/list.yaml | 12 +- docs/schemas/outputs/resource/set.yaml | 16 +- docs/schemas/outputs/resource/test.yaml | 26 +- 27 files changed, 376 insertions(+), 804 deletions(-) create mode 100644 docs/reference/schemas/definitions/resourceType.md diff --git a/docs/reference/schemas/config/document.md b/docs/reference/schemas/config/document.md index 38acd851b..486910c8d 100644 --- a/docs/reference/schemas/config/document.md +++ b/docs/reference/schemas/config/document.md @@ -18,9 +18,10 @@ DSC Configurations enable users to define state by combining different DSC Resou 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 recommneds drafting configuration documents in YAML. +A configuration document can be defined as either YAML or JSON. For ease of authoring, Microsoft +recommneds drafting configuration documents in YAML. -For DSC's authoring tools to recognize a file as a DSC Configuration document, the file name must +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] @@ -67,9 +68,13 @@ 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. +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. +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 @@ -104,7 +109,10 @@ Required: false 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]. +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 diff --git a/docs/reference/schemas/config/parameter.md b/docs/reference/schemas/config/parameter.md index a554dc950..5275b73dc 100644 --- a/docs/reference/schemas/config/parameter.md +++ b/docs/reference/schemas/config/parameter.md @@ -1,5 +1,7 @@ # DSC Configuration document parameter schema +## Synopsis + Defines runtime options for a configuration. ## Metadata @@ -20,7 +22,8 @@ Parameters are defined as key-value pairs in the `parameters` property of a conf 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. +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 @@ -100,7 +103,8 @@ Parameters may limit the set of valid values for the parameter by defining the ` 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. +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 diff --git a/docs/reference/schemas/config/resource.md b/docs/reference/schemas/config/resource.md index 518dced49..d7e55943c 100644 --- a/docs/reference/schemas/config/resource.md +++ b/docs/reference/schemas/config/resource.md @@ -1,5 +1,7 @@ # DSC Configuration document resource schema +## Synopsis + Defines instances of DSC Resources that compose a configuration. ## Metadata @@ -44,8 +46,8 @@ Required: true ### type The `type` property identifies the instance's DSC Resource. The value for this property must be the -valid fully-qualified type name for the resource. For more information about type names, see -[Anatomy of a command-based DSC Resource][01]. +valid fully qualified type name for the resource. For more information about type names, see +[DSC Resource fully qualified type name schema reference][01]. ```yaml Type: string @@ -68,7 +70,8 @@ Required: true ### dependsOn -To declare that a resource instance is dependent on another instance in the configuration, define the `dependsOn` property. +To declare that a resource instance is dependent on another instance in the configuration, define +the `dependsOn` property. This property must be an array of dependency declarations. Each dependency must use this syntax: @@ -93,7 +96,7 @@ Valid Items Type: string Valid Items Pattern: ^\[\w+(\.\w+){0,2}\/\w+\].+$ ``` -[01]: ../../../resources/concepts/anatomy.md +[01]: ../definitions/resourceType.md [02]: ../../../resources/concepts/assertion-resources.md [03]: ../../../resources/concepts/schemas.md [04]: ../../../configurations/concepts/dependencies.md diff --git a/docs/reference/schemas/definitions/parameters/dataTypes.md b/docs/reference/schemas/definitions/parameters/dataTypes.md index 3a83c99a7..84aa28525 100644 --- a/docs/reference/schemas/definitions/parameters/dataTypes.md +++ b/docs/reference/schemas/definitions/parameters/dataTypes.md @@ -1,5 +1,7 @@ # DSC configuration parameter data type schema reference +## Synopsis + Defines valid data types for a DSC configuration parameter ## Metadata @@ -38,7 +40,8 @@ Access parameters in a configuration using this syntax: "[parameter('')]" ``` -In YAML, the parameter syntax needs to be enclosed in double-quotes when used as an inline value. If the syntax isn't quoted, YAML interprets the syntax as an array. +In YAML, the parameter syntax needs to be enclosed in double-quotes when used as an inline value. +If the syntax isn't quoted, YAML interprets the syntax as an array. ```yaml valid: "[parameter('example')]" @@ -51,7 +54,8 @@ invalid: ## Arrays -Arrays are a list of one or more values. The values in the array can be any valid data type. Values in the array can be the same type or different types. +Arrays are a list of one or more values. The values in the array can be any valid data type. Values +in the array can be the same type or different types. ```yaml parameters: @@ -113,7 +117,9 @@ parameters: ## Integers -Integer values are numbers without a fractional part. Integer values may be limited by integrating tools or the DSC Resources they're used with. DSC itself supports integer values between `-9223372036854775808` and `9223372036854775807`. +Integer values are numbers without a fractional part. Integer values may be limited by integrating +tools or the DSC Resources they're used with. DSC itself supports integer values between +`-9223372036854775808` and `9223372036854775807`. ```yaml parameters: @@ -188,9 +194,10 @@ parameters: defaultValue: This example includes spaces and 'quoted' "text." ``` -To define a long string without newlines in YAML, use the folded block syntax by adding a `>` and a line break after the key. Then, indent the next line. Every line in the string must start -at the same level of indentation. The lines are combined with a single space instead of newlines. -To trim trailing whitespace, use `>-` instead of `>`. +To define a long string without newlines in YAML, use the folded block syntax by adding a `>` and a +line break after the key. Then, indent the next line. Every line in the string must start at the +same level of indentation. The lines are combined with a single space instead of newlines. To trim +trailing whitespace, use `>-` instead of `>`. ```yaml parameters: @@ -241,3 +248,5 @@ parameters: sensitiveOptions: type: secureobject ``` + +[01]: ../../config/document.md diff --git a/docs/reference/schemas/definitions/resourceType.md b/docs/reference/schemas/definitions/resourceType.md new file mode 100644 index 000000000..7425a223b --- /dev/null +++ b/docs/reference/schemas/definitions/resourceType.md @@ -0,0 +1,65 @@ +# DSC Resource fully qualified type name schema reference + +## Synopsis + +Identifies a DSC Resource. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml +Type : string +Pattern : ^\w+(\.\w+){0,2}\/\w+$ +``` + +## Description + +DSC Resources are identified by their fully qualified type name. Values of this type are used to +specify a resource in configuration documents and as the value of the `--resource` flag when +using the `dsc resource *` commands. + +The fully qualified type name of a resource uses the following syntax: + +```text +`[.][.]/` +``` + +Each segment must be string of alphanumeric characters and underscores. No other characters are +permitted. Every resource must define an `owner` and a `name`. Use the `group` and `area` +components to organize resources into related namespaces. For example: + +- `Microsoft.SqlServer/Database` +- `Microsoft.SqlServer.Database/Role` +- `Microsoft.SqlServer.Database/User` +- `Microsoft.SqlServer/Endpoint` +- `Microsoft.SqlServer.Endpoint/Permission` +- `Microsoft.SqlServer/Login` +- `Microsoft.SqlServer/MaxDop` + +## Type name segments + +### Owner + +The owner segment of the type name is mandatory. It identifies the person or organization that +owns, develops and maintains the resource. + +### Group + +The group segment of the type name is optional. It defines a logical grouping for a collection of +resources. For example, resources that manage SQL Server might use the `SqlServer` group in their +type name. + +### Area + +The area segment of the type name is optional. It defines a grouping for a collection of resources +by purpose or higher-level component. For example, resources that manage components of a SQL Server +database might use the `Database` area in their type name. + +### Name + +The name segment of the type name is mandatory. It identifies the component that the resource +manages. This segment should be a singular noun unless the resource always manages a list of +components in a single resource instance. In that case, the resource name should be the plural form +of the noun it manages or the singular form of the noun followed by the word `List`, like +`JeaRoleCapabilities` or `JeaRoleCapabilityList`. diff --git a/docs/reference/schemas/resource/manifest/root.md b/docs/reference/schemas/resource/manifest/root.md index 1f2a5b955..ef0687597 100644 --- a/docs/reference/schemas/resource/manifest/root.md +++ b/docs/reference/schemas/resource/manifest/root.md @@ -14,10 +14,10 @@ Type : object ## Description -Every command-based DSC Resource must have a manifest. The manifest must: +Every command-based DSC Resource must have a manifest. The manifest file must: 1. Be discoverable in the `PATH` environment variable. -1. Follow the naming convention `.resource.json`. +1. Follow the naming convention `.dsc.resource.json`. 1. Be valid for the schema described in this document. The rest of this document describes the manifest's schema. @@ -49,25 +49,10 @@ Valid Values: ### type -The `type` property represents the fully qualified the name of the resource in its namespace. It's -used to specify the resource in configuration documents and as the value of the `--resource` flag -when using the `dsc resource *` commands. This value must use the following syntax: - -```text -`[.][.]/` -``` - -Each component must be string of alphanumeric characters and underscores. No other characters are -permitted. Every resource must define an `owner` and a `name`. Use the `group` and `area` -components to organize resources into related namespaces. For example: - -- `Microsoft.SqlServer/Database` -- `Microsoft.SqlServer.Database/Role` -- `Microsoft.SqlServer.Database/User` -- `Microsoft.SqlServer/Endpoint` -- `Microsoft.SqlServer.Endpoint/Permission` -- `Microsoft.SqlServer/Login` -- `Microsoft.SqlServer/MaxDop` +The `type` property represents the fully qualified type name of the resource. It's used to specify +the resource in configuration documents and as the value of the `--resource` flag when using the +`dsc resource *` commands. For more information about resource type names, see +[DSC Resource fully qualified type name schema reference][01]. ```yaml Type: string @@ -118,7 +103,7 @@ property is mandatory for all resources. The value of this property must be an object. The object's `executable` property, defining the name of the command to call, is mandatory. The `args` and `input` properties are optional. For more -information, see [DSC Resource manifest get property schema reference][01]. +information, see [DSC Resource manifest get property schema reference][02]. ```yaml Type: object @@ -134,7 +119,7 @@ test whether the instance is in the desired state. The value of this property must be an object. The `executable` property, defining the name of the command to call, is mandatory. The `args` `input`, `preTest`, and `returns` properties are -optional. For more information, see [DSC Resource manifest set property schema reference][02]. +optional. For more information, see [DSC Resource manifest set property schema reference][03]. ```yaml Type: object @@ -149,7 +134,7 @@ property isn't defined, DSC performs a basic synthetic test for instances of the The value of this property must be an object. The object's `executable` property, defining the name of the command to call, is mandatory. The `args` `input`, and `returns` properties are optional. -For more information, see [DSC Resource manifest test property schema reference][03]. +For more information, see [DSC Resource manifest test property schema reference][04]. ```yaml Type: object @@ -163,7 +148,7 @@ property is mandatory for DSC Group Resources. DSC ignores this property for all The value of this property must be an object. The object's `executable` property, defining the name of the command to call, is mandatory. The `args` property is optional. For more information, see -[DSC Resource manifest validate property schema reference][04]. +[DSC Resource manifest validate property schema reference][05]. ```yaml Type: object @@ -177,7 +162,7 @@ When specified, the `provider` property defines the resource as a DSC Resource P The value of this property must be an object. The object's `list` and `config` properties are mandatory. The `list` property defines how to call the provider to return the resources that the provider can manage. The `config` property defines how the provider expects input. For more -information, see the [DSC Resource manifest provider property schema reference][05]. +information, see the [DSC Resource manifest provider property schema reference][06]. ### exitCodes @@ -207,16 +192,17 @@ resource. This property must always be an object that defines one of the followi - `embedded` - When you specify the `embedded` property, DSC uses the defined value as the JSON schema. -For more information, see [DSC Resource manifest schema property reference][06]. +For more information, see [DSC Resource manifest schema property reference][07]. ```yaml Type: object Required: true ``` -[01]: get.md -[02]: set.md -[03]: test.md -[04]: validate.md -[05]: provider.md -[06]: schema.md +[01]: ../../definitions/resourceType.md +[02]: get.md +[03]: set.md +[04]: test.md +[05]: validate.md +[06]: provider.md +[07]: schema.md diff --git a/docs/reference/schemas/resource/manifest/schema/property.md b/docs/reference/schemas/resource/manifest/schema/property.md index 8cd6bf4c6..328d87009 100644 --- a/docs/reference/schemas/resource/manifest/schema/property.md +++ b/docs/reference/schemas/resource/manifest/schema/property.md @@ -132,7 +132,8 @@ Default: [] ### embedded The `embedded` property defines the full JSON schema for DSC to validate instances of the DSC -Resource. The value for this property must be a valid JSON schema that defines the `$schema`, `type`, and `properties` keywords. +Resource. The value for this property must be a valid JSON schema that defines the `$schema`, +`type`, and `properties` keywords. ```yaml Type: object diff --git a/docs/reference/schemas/resource/properties/ensure.md b/docs/reference/schemas/resource/properties/ensure.md index a5e082bfd..097198880 100644 --- a/docs/reference/schemas/resource/properties/ensure.md +++ b/docs/reference/schemas/resource/properties/ensure.md @@ -24,7 +24,8 @@ doesn't exist, the resource creates the instance during the set operation. When `_ensure` is set to `Absent` for the desired state, the instance is expected to not exist. If it does exist, the resource removes the instance during the set operation. -To add this property to a resource's instance schema, define the property with the following snippet: +To add this property to a resource's instance schema, define the property with the following +snippet: ```json "_ensure": { diff --git a/docs/schemas/bundled/config.document.json b/docs/schemas/bundled/config.document.json index bc86c8adf..7118f9fca 100644 --- a/docs/schemas/bundled/config.document.json +++ b/docs/schemas/bundled/config.document.json @@ -19,7 +19,12 @@ ] }, "parameters": { - "$ref": "/dsc/2023/07/config/document.parameters.json" + "title": "DSC Configuration document parameters", + "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "type": "object", + "additionalProperties": { + "$ref": "/dsc/2023/07/config/document.parameters.json" + } }, "variables": { "title": "Configuration variables", @@ -27,7 +32,13 @@ "type": "object" }, "resources": { - "$ref": "/dsc/2023/07/config/document.resources.json" + "title": "DSC Configuration document resources", + "description": "Defines a list of DSC Resource instances for the configuration to manage.", + "type": "array", + "minItems": 1, + "items": { + "$ref": "/dsc/2023/07/config/document.resource.json" + } }, "metadata": { "title": "Configuration metadata", @@ -36,195 +47,36 @@ } }, "$defs": { - "https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.json": { + "https://schemas.microsoft.com/dsc/2023/07/config/document.resource.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.json", - "title": "DSC Configuration document parameters", - "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "$id": "https://schemas.microsoft.com/dsc/2023/07/config/document.resource.json", + "title": "DSC Resource instance", "type": "object", - "patternProperties": { - ".": { - "title": "Parameter", - "description": "Defines a runtime option for a DSC Configuration Document.", - "type": "object", - "required": [ - "type" - ], - "properties": { - "type": { - "$ref": "/dsc/2023/07/definitions/parameters/dataType.json" - }, - "defaultValue": { - "title": "Default value", - "description": "Defines the default value for the parameter.", - "$ref": "/dsc/2023/07/definitions/parameters/validValueTypes.json" - }, - "allowedValues": { - "title": "Allowed values", - "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", - "type": "array", - "items": { - "$ref": "/dsc/2023/07/definitions/parameters/validValueTypes.json" - } - }, - "description": { - "title": "Parameter description", - "description": "Defines a synopsis for the parameter explaining its purpose.", - "type": "string" - }, - "metadata": { - "title": "Parameter metadata", - "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", - "type": "object" - } - }, - "allOf": [ - { - "if": { - "properties": { - "type": { - "const": "int" - } - } - }, - "then": { - "$ref": "/dsc/2023/07/definitions/parameters/integerValidationProperties.json" - } - }, - { - "if": { - "oneOf": [ - { - "properties": { - "type": { - "const": "string" - } - } - }, - { - "properties": { - "type": { - "const": "securestring" - } - } - }, - { - "properties": { - "type": { - "const": "array" - } - } - } - ] - }, - "then": { - "$ref": "/dsc/2023/07/definitions/parameters/lengthValidationProperties.json" - } - } - ] - } - } - }, - "https://schemas.microsoft.com/dsc/2023/07/config/document.resources.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/config/document.resources.json", - "title": "DSC Configuration document resources", - "description": "Defines a list of DSC Resource instances for the configuration to manage.", - "type": "array", - "items": { - "title": "DSC Resource instance", - "type": "object", - "required": [ - "type", - "name" - ], - "properties": { - "type": { - "$ref": "/dsc/2023/07/definitions/resourceType.json" - }, - "name": { - "$ref": "/dsc/2023/07/definitions/instanceName.json" - }, - "dependsOn": { - "title": "Instance depends on", - "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", - "type": "array", - "items": { - "type": "string", - "uniqueItems": true - } - }, - "properties": { - "title": "Managed instance properties", - "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", - "type": "object" - } - } - } - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataType.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataType.json", - "title": "Data Type", - "description": "Defines the data type for the value.", - "type": "string", - "enum": [ - "string", - "securestring", - "int", - "bool", - "object", - "secureobject", - "array" - ] - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/validValueTypes.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/validValueTypes.json", - "$comment": "This schema fragment makes it a little easier to compose the valid properties\nfor DSC Configuration document parameters. As-written, values must be one of\nthose on this list - the schema definition for dataType excludes `null` and\nnumbers with fractional parts, like `3.5`.\n", - "type": [ - "string", - "integer", - "object", - "array", - "boolean" - ] - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/integerValidationProperties.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/integerValidationProperties.json", - "$comment": "This schema fragment makes it a little easier to compose the valid properties\nfor DSC Configuration document parameters. These only apply to `int` type\nparameters.\n", + "required": [ + "type", + "name" + ], "properties": { - "minValue": { - "title": "Minimum value", - "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", - "type": "integer", - "minimum": 0 + "type": { + "$ref": "/dsc/2023/07/definitions/resourceType.json" }, - "maxValue": { - "title": "Maximum value", - "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", - "type": "integer", - "minimum": 0 - } - } - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/lengthValidationProperties.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/lengthValidationProperties.json", - "$comment": "This schema fragment makes it a little easier to compose the valid properties\nfor DSC Configuration document parameters. These only apply to `string`,\n`securestring`, and `array` type parameters.\n", - "properties": { - "minLength": { - "title": "Minimum length", - "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", - "type": "integer", - "minimum": 0 + "name": { + "$ref": "/dsc/2023/07/definitions/instanceName.json" }, - "maxLength": { - "title": "Maximum length", - "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", - "type": "integer", - "minimum": 0 + "dependsOn": { + "title": "Instance depends on", + "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", + "type": "array", + "items": { + "type": "string", + "uniqueItems": true, + "pattern": "^\\[\\w+(\\.\\w+){0,2}\\/\\w+\\].+$" + } + }, + "properties": { + "title": "Managed instance properties", + "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", + "type": "object" } } }, diff --git a/docs/schemas/bundled/config.document.vscode.json b/docs/schemas/bundled/config.document.vscode.json index 86fc9159c..e609080a0 100644 --- a/docs/schemas/bundled/config.document.vscode.json +++ b/docs/schemas/bundled/config.document.vscode.json @@ -19,7 +19,12 @@ ] }, "parameters": { - "$ref": "#/$defs/dsc/2023/07/config/document.parameters.json" + "title": "DSC Configuration document parameters", + "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/dsc/2023/07/config/document.parameters.json" + } }, "variables": { "title": "Configuration variables", @@ -27,7 +32,13 @@ "type": "object" }, "resources": { - "$ref": "#/$defs/dsc/2023/07/config/document.resources.json" + "title": "DSC Configuration document resources", + "description": "Defines a list of DSC Resource instances for the configuration to manage.", + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/dsc/2023/07/config/document.resource.json" + } }, "metadata": { "title": "Configuration metadata", @@ -40,202 +51,41 @@ "2023": { "07": { "config": { - "document.parameters.json": { + "document.resource.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.json", - "title": "DSC Configuration document parameters", - "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "$id": "https://schemas.microsoft.com/dsc/2023/07/config/document.resource.json", + "title": "DSC Resource instance", "type": "object", - "patternProperties": { - ".": { - "title": "Parameter", - "description": "Defines a runtime option for a DSC Configuration Document.", - "type": "object", - "required": [ - "type" - ], - "properties": { - "type": { - "$ref": "#/$defs/dsc/2023/07/definitions/parameters/dataType.json" - }, - "defaultValue": { - "title": "Default value", - "description": "Defines the default value for the parameter.", - "$ref": "#/$defs/dsc/2023/07/definitions/parameters/validValueTypes.json" - }, - "allowedValues": { - "title": "Allowed values", - "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", - "type": "array", - "items": { - "$ref": "#/$defs/dsc/2023/07/definitions/parameters/validValueTypes.json" - } - }, - "description": { - "title": "Parameter description", - "description": "Defines a synopsis for the parameter explaining its purpose.", - "type": "string" - }, - "metadata": { - "title": "Parameter metadata", - "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", - "type": "object" - } - }, - "allOf": [ - { - "if": { - "properties": { - "type": { - "const": "int" - } - } - }, - "then": { - "$ref": "#/$defs/dsc/2023/07/definitions/parameters/integerValidationProperties.json" - } - }, - { - "if": { - "oneOf": [ - { - "properties": { - "type": { - "const": "string" - } - } - }, - { - "properties": { - "type": { - "const": "securestring" - } - } - }, - { - "properties": { - "type": { - "const": "array" - } - } - } - ] - }, - "then": { - "$ref": "#/$defs/dsc/2023/07/definitions/parameters/lengthValidationProperties.json" - } - } - ] - } - } - }, - "document.resources.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/config/document.resources.json", - "title": "DSC Configuration document resources", - "description": "Defines a list of DSC Resource instances for the configuration to manage.", - "type": "array", - "items": { - "title": "DSC Resource instance", - "type": "object", - "required": [ - "type", - "name" - ], - "properties": { - "type": { - "$ref": "#/$defs/dsc/2023/07/definitions/resourceType.json" - }, - "name": { - "$ref": "#/$defs/dsc/2023/07/definitions/instanceName.json" - }, - "dependsOn": { - "title": "Instance depends on", - "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", - "type": "array", - "items": { - "type": "string", - "uniqueItems": true - } - }, - "properties": { - "title": "Managed instance properties", - "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", - "type": "object" + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "$ref": "#/$defs/dsc/2023/07/definitions/resourceType.json" + }, + "name": { + "$ref": "#/$defs/dsc/2023/07/definitions/instanceName.json" + }, + "dependsOn": { + "title": "Instance depends on", + "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", + "type": "array", + "items": { + "type": "string", + "uniqueItems": true, + "pattern": "^\\[\\w+(\\.\\w+){0,2}\\/\\w+\\].+$" } + }, + "properties": { + "title": "Managed instance properties", + "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", + "type": "object" } } } }, "definitions": { - "parameters": { - "dataType.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataType.json", - "title": "Data Type", - "description": "Defines the data type for the value.", - "type": "string", - "enum": [ - "string", - "securestring", - "int", - "bool", - "object", - "secureobject", - "array" - ] - }, - "validValueTypes.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/validValueTypes.json", - "$comment": "This schema fragment makes it a little easier to compose the valid properties\nfor DSC Configuration document parameters. As-written, values must be one of\nthose on this list - the schema definition for dataType excludes `null` and\nnumbers with fractional parts, like `3.5`.\n", - "type": [ - "string", - "integer", - "object", - "array", - "boolean" - ] - }, - "integerValidationProperties.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/integerValidationProperties.json", - "$comment": "This schema fragment makes it a little easier to compose the valid properties\nfor DSC Configuration document parameters. These only apply to `int` type\nparameters.\n", - "properties": { - "minValue": { - "title": "Minimum value", - "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", - "type": "integer", - "minimum": 0 - }, - "maxValue": { - "title": "Maximum value", - "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", - "type": "integer", - "minimum": 0 - } - } - }, - "lengthValidationProperties.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/lengthValidationProperties.json", - "$comment": "This schema fragment makes it a little easier to compose the valid properties\nfor DSC Configuration document parameters. These only apply to `string`,\n`securestring`, and `array` type parameters.\n", - "properties": { - "minLength": { - "title": "Minimum length", - "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", - "type": "integer", - "minimum": 0 - }, - "maxLength": { - "title": "Maximum length", - "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", - "type": "integer", - "minimum": 0 - } - } - } - }, "resourceType.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json", diff --git a/docs/schemas/bundled/config.document.vscode.yaml b/docs/schemas/bundled/config.document.vscode.yaml index 20f18c0e7..6d8a9e0d6 100644 --- a/docs/schemas/bundled/config.document.vscode.yaml +++ b/docs/schemas/bundled/config.document.vscode.yaml @@ -15,13 +15,22 @@ properties: enum: - https://schemas.microsoft.com/dsc/2023/07/config/document.yaml parameters: - $ref: '#/$defs/dsc/2023/07/config/document.parameters.yaml' + title: DSC Configuration document parameters + description: Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration. + type: object + additionalProperties: + $ref: '#/$defs/dsc/2023/07/config/document.parameters.yaml' variables: title: Configuration variables description: Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value. type: object resources: - $ref: '#/$defs/dsc/2023/07/config/dataTypes.yaml' + title: DSC Configuration document resources + description: Defines a list of DSC Resource instances for the configuration to manage. + type: array + minItems: 1 + items: + $ref: '#/$defs/dsc/2023/07/config/document.resource.yaml' metadata: title: Configuration metadata description: Defines a set of key-value pairs for the configuration. This metadata isn't validated. @@ -31,161 +40,32 @@ $defs: "2023": "07": config: - document.parameters.yaml: + document.resource.yaml: $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.yaml - title: DSC Configuration document parameters - description: Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration. + $id: https://schemas.microsoft.com/dsc/2023/07/config/document.resource.yaml + title: DSC Resource instance type: object - patternProperties: - .: - title: Parameter - description: Defines a runtime option for a DSC Configuration Document. - type: object - required: - - type - properties: - type: - $ref: '#/$defs/dsc/2023/07/definitions/parameters/dataTypes.yaml' - defaultValue: - title: Default value - description: Defines the default value for the parameter. - $ref: '#/$defs/dsc/2023/07/definitions/parameters/validValueTypes.yaml' - allowedValues: - title: Allowed values - description: Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid. - type: array - items: - $ref: '#/$defs/dsc/2023/07/definitions/parameters/validValueTypes.yaml' - description: - title: Parameter description - description: Defines a synopsis for the parameter explaining its purpose. - type: string - metadata: - title: Parameter metadata - description: Defines a set of key-value pairs for the parameter. This metadata isn't validated. - type: object - allOf: - - if: - properties: - type: - const: int - then: - $ref: '#/$defs/dsc/2023/07/definitions/parameters/integerValidationProperties.yaml' - - if: - oneOf: - - properties: - type: - const: string - - properties: - type: - const: securestring - - properties: - type: - const: array - then: - $ref: '#/$defs/dsc/2023/07/definitions/parameters/lengthValidationProperties.yaml' - dataTypes.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/config/dataTypes.yaml - title: DSC Configuration document resources - description: Defines a list of DSC Resource instances for the configuration to manage. - type: array - items: - title: DSC Resource instance - type: object - required: - - type - - name - properties: - type: - $ref: '#/$defs/dsc/2023/07/definitions/resourceType.yaml' - name: - $ref: '#/$defs/dsc/2023/07/definitions/instanceName.yaml' - dependsOn: - title: Instance depends on - description: Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property. - type: array - items: - type: string - uniqueItems: true - properties: - title: Managed instance properties - description: Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema. - type: object - definitions: - parameters: - dataTypes.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataTypes.yaml - title: Data Type - description: Defines the data type for the value. - type: string - enum: - - string - - securestring - - int - - bool - - object - - secureobject - - array - validValueTypes.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/validValueTypes.yaml - $comment: > - This schema fragment makes it a little easier to compose the valid properties - - for DSC Configuration document parameters. As-written, values must be one of - - those on this list - the schema definition for dataType excludes `null` and - - numbers with fractional parts, like `3.5`. + required: + - type + - name + properties: type: - - string - - integer - - object - - array - - boolean - integerValidationProperties.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/integerValidationProperties.yaml - $comment: > - This schema fragment makes it a little easier to compose the valid properties - - for DSC Configuration document parameters. These only apply to `int` type - - parameters. + $ref: '#/$defs/dsc/2023/07/definitions/resourceType.yaml' + name: + $ref: '#/$defs/dsc/2023/07/definitions/instanceName.yaml' + dependsOn: + title: Instance depends on + description: Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property. + type: array + items: + type: string + uniqueItems: true + pattern: ^\[\w+(\.\w+){0,2}\/\w+\].+$ properties: - minValue: - title: Minimum value - description: The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`. - type: integer - minimum: 0 - maxValue: - title: Maximum value - description: The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`. - type: integer - minimum: 0 - lengthValidationProperties.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/lengthValidationProperties.yaml - $comment: > - This schema fragment makes it a little easier to compose the valid properties - - for DSC Configuration document parameters. These only apply to `string`, - - `securestring`, and `array` type parameters. - properties: - minLength: - title: Minimum length - description: The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`. - type: integer - minimum: 0 - maxLength: - title: Maximum length - description: The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`. - type: integer - minimum: 0 + title: Managed instance properties + description: Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema. + type: object + definitions: resourceType.yaml: $schema: https://json-schema.org/draft/2020-12/schema $id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml diff --git a/docs/schemas/bundled/config.document.yaml b/docs/schemas/bundled/config.document.yaml index 62af0fd4b..b7afabd3d 100644 --- a/docs/schemas/bundled/config.document.yaml +++ b/docs/schemas/bundled/config.document.yaml @@ -15,171 +15,52 @@ properties: enum: - https://schemas.microsoft.com/dsc/2023/07/config/document.yaml parameters: - $ref: /dsc/2023/07/config/document.parameters.yaml + title: DSC Configuration document parameters + description: Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration. + type: object + additionalProperties: + $ref: /dsc/2023/07/config/document.parameters.yaml variables: title: Configuration variables description: Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value. type: object resources: - $ref: /dsc/2023/07/config/dataTypes.yaml + title: DSC Configuration document resources + description: Defines a list of DSC Resource instances for the configuration to manage. + type: array + minItems: 1 + items: + $ref: /dsc/2023/07/config/document.resource.yaml metadata: title: Configuration metadata description: Defines a set of key-value pairs for the configuration. This metadata isn't validated. type: object $defs: - https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.yaml: + https://schemas.microsoft.com/dsc/2023/07/config/document.resource.yaml: $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.yaml - title: DSC Configuration document parameters - description: Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration. + $id: https://schemas.microsoft.com/dsc/2023/07/config/document.resource.yaml + title: DSC Resource instance type: object - patternProperties: - .: - title: Parameter - description: Defines a runtime option for a DSC Configuration Document. - type: object - required: - - type - properties: - type: - $ref: /dsc/2023/07/definitions/parameters/dataTypes.yaml - defaultValue: - title: Default value - description: Defines the default value for the parameter. - $ref: /dsc/2023/07/definitions/parameters/validValueTypes.yaml - allowedValues: - title: Allowed values - description: Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid. - type: array - items: - $ref: /dsc/2023/07/definitions/parameters/validValueTypes.yaml - description: - title: Parameter description - description: Defines a synopsis for the parameter explaining its purpose. - type: string - metadata: - title: Parameter metadata - description: Defines a set of key-value pairs for the parameter. This metadata isn't validated. - type: object - allOf: - - if: - properties: - type: - const: int - then: - $ref: /dsc/2023/07/definitions/parameters/integerValidationProperties.yaml - - if: - oneOf: - - properties: - type: - const: string - - properties: - type: - const: securestring - - properties: - type: - const: array - then: - $ref: /dsc/2023/07/definitions/parameters/lengthValidationProperties.yaml - https://schemas.microsoft.com/dsc/2023/07/config/dataTypes.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/config/dataTypes.yaml - title: DSC Configuration document resources - description: Defines a list of DSC Resource instances for the configuration to manage. - type: array - items: - title: DSC Resource instance - type: object - required: - - type - - name - properties: - type: - $ref: /dsc/2023/07/definitions/resourceType.yaml - name: - $ref: /dsc/2023/07/definitions/instanceName.yaml - dependsOn: - title: Instance depends on - description: Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property. - type: array - items: - type: string - uniqueItems: true - properties: - title: Managed instance properties - description: Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema. - type: object - https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataTypes.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataTypes.yaml - title: Data Type - description: Defines the data type for the value. - type: string - enum: - - string - - securestring - - int - - bool - - object - - secureobject - - array - https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/validValueTypes.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/validValueTypes.yaml - $comment: > - This schema fragment makes it a little easier to compose the valid properties - - for DSC Configuration document parameters. As-written, values must be one of - - those on this list - the schema definition for dataType excludes `null` and - - numbers with fractional parts, like `3.5`. - type: - - string - - integer - - object - - array - - boolean - https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/integerValidationProperties.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/integerValidationProperties.yaml - $comment: > - This schema fragment makes it a little easier to compose the valid properties - - for DSC Configuration document parameters. These only apply to `int` type - - parameters. - properties: - minValue: - title: Minimum value - description: The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`. - type: integer - minimum: 0 - maxValue: - title: Maximum value - description: The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`. - type: integer - minimum: 0 - https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/lengthValidationProperties.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/lengthValidationProperties.yaml - $comment: > - This schema fragment makes it a little easier to compose the valid properties - - for DSC Configuration document parameters. These only apply to `string`, - - `securestring`, and `array` type parameters. + required: + - type + - name properties: - minLength: - title: Minimum length - description: The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`. - type: integer - minimum: 0 - maxLength: - title: Maximum length - description: The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`. - type: integer - minimum: 0 + type: + $ref: /dsc/2023/07/definitions/resourceType.yaml + name: + $ref: /dsc/2023/07/definitions/instanceName.yaml + dependsOn: + title: Instance depends on + description: Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property. + type: array + items: + type: string + uniqueItems: true + pattern: ^\[\w+(\.\w+){0,2}\/\w+\].+$ + properties: + title: Managed instance properties + description: Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema. + type: object https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml: $schema: https://json-schema.org/draft/2020-12/schema $id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml diff --git a/docs/schemas/bundled/outputs.config.get.json b/docs/schemas/bundled/outputs.config.get.json index 9e76e6a42..528ddca0a 100644 --- a/docs/schemas/bundled/outputs.config.get.json +++ b/docs/schemas/bundled/outputs.config.get.json @@ -61,15 +61,15 @@ "https://schemas.microsoft.com/dsc/2023/07/results/resource/get.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://schemas.microsoft.com/dsc/2023/07/results/resource/get.json", - "title": "DSC Resource get result", + "title": "dsc resource get result", "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command.", "type": "object", "required": [ - "actual_state" + "actualState" ], "properties": { - "actual_state": { - "title": "The DSC Resource instance's current state", + "actualState": { + "title": "Actual state", "description": "This property always represents the current state of the DSC Resource instance as returned by its `get` method. DSC validates this return value against the DSC Resource's schema.", "type": "object" } diff --git a/docs/schemas/bundled/outputs.config.set.json b/docs/schemas/bundled/outputs.config.set.json index 58d14c8e1..7c3cf6b35 100644 --- a/docs/schemas/bundled/outputs.config.set.json +++ b/docs/schemas/bundled/outputs.config.set.json @@ -61,27 +61,27 @@ "https://schemas.microsoft.com/dsc/2023/07/results/resource/set.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://schemas.microsoft.com/dsc/2023/07/results/resource/set.json", - "title": "DSC Resource set result", + "title": "dsc resource set result", "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command.", "type": "object", "required": [ - "before_state", - "after_state", - "changed_properties" + "beforeState", + "afterState", + "changedProperties" ], "properties": { - "before_state": { + "beforeState": { "title": "State before enforcing", "description": "This property always represents the desired state of the DSC Resource instance before the `set` method runs. DSC validates this return value against the DSC Resource's schema.", "type": "object" }, - "after_state": { + "afterState": { "title": "State after enforcing", "description": "This property always represents the current state of the DSC Resource instance as returned by its `set` method after enforcing the desired state. DSC validates this return value against the DSC Resource's schema.", "type": "object" }, - "changed_properties": { - "title": "Changed Properties", + "changedProperties": { + "title": "Changed properties", "description": "This property always represents the list of property names for the DSC Resource instance that the `set` method modified. When this value is an empty array, the `set` method didn't enforce any properties for the instance.", "type": "array", "default": [], diff --git a/docs/schemas/bundled/outputs.config.test.json b/docs/schemas/bundled/outputs.config.test.json index cc14bdf98..4f4061f4b 100644 --- a/docs/schemas/bundled/outputs.config.test.json +++ b/docs/schemas/bundled/outputs.config.test.json @@ -61,27 +61,33 @@ "https://schemas.microsoft.com/dsc/2023/07/results/resource/test.json": { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://schemas.microsoft.com/dsc/2023/07/results/resource/test.json", - "title": "DSC Resource test result", + "title": "dsc resource test result", "description": "Describes the return data for a DSC Resource instance from the `dsc resource test` command.", "type": "object", "required": [ - "expected_state", - "actual_state", - "diff_properties" + "desiredState", + "actualState", + "inDesiredState", + "differingProperties" ], "properties": { - "expected_state": { - "title": "Expected State", + "desiredState": { + "title": "Desired state", "description": "This property always represents the desired state of the DSC Resource instance as specified to DSC.", "type": "object" }, - "actual_state": { - "title": "Actual State", + "actualState": { + "title": "Actual state", "description": "This property always represents the current state of the DSC Resource instance as returned by its `test` method or, if the DSC Resource doesn't define the `test` method, by its `get` method. DSC validates this return value against the DSC Resource's schema.", "type": "object" }, - "diff_properties": { - "title": "Differing Properties", + "inDesiredState": { + "title": "Instance is in the desired state", + "description": "This property indicates whether the instance is in the desired state.", + "type": "boolean" + }, + "differingProperties": { + "title": "Differing properties", "description": "This property always represents the list of property names for the DSC Resource instance that aren't in the desired state. When this property is an empty array, the instance is in the desired state.", "type": "array", "default": [], diff --git a/docs/schemas/bundled/outputs.resource.get.json b/docs/schemas/bundled/outputs.resource.get.json index 48f452a8a..57986c4e6 100644 --- a/docs/schemas/bundled/outputs.resource.get.json +++ b/docs/schemas/bundled/outputs.resource.get.json @@ -1,15 +1,15 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.resource.get.json", - "title": "DSC Resource get result", + "title": "dsc resource get result", "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command.", "type": "object", "required": [ - "actual_state" + "actualState" ], "properties": { - "actual_state": { - "title": "The DSC Resource instance's current state", + "actualState": { + "title": "Actual state", "description": "This property always represents the current state of the DSC Resource instance as returned by its `get` method. DSC validates this return value against the DSC Resource's schema.", "type": "object" } diff --git a/docs/schemas/bundled/outputs.resource.list.json b/docs/schemas/bundled/outputs.resource.list.json index aa5eba629..0e5c23c4e 100644 --- a/docs/schemas/bundled/outputs.resource.list.json +++ b/docs/schemas/bundled/outputs.resource.list.json @@ -1,7 +1,7 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.resource.list.json", - "title": "DSC Resource list result", + "title": "dsc resource list result", "description": "Describes the return data for a DSC Resource instance from the `dsc resource list` command.", "type": "object", "properties": { @@ -11,6 +11,11 @@ "version": { "$ref": "/dsc/2023/07/definitions/semver.json" }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, "path": { "title": "Path", "description": "Indicates the path to the DSC Resource on the file system.", @@ -139,6 +144,7 @@ "title": "Tags", "description": "An array of short strings used to search for DSC Resources.", "type": "array", + "uniqueItems": true, "items": { "type": "string", "pattern": "^\\w+$" diff --git a/docs/schemas/bundled/outputs.resource.set.json b/docs/schemas/bundled/outputs.resource.set.json index f816305e7..9863e4551 100644 --- a/docs/schemas/bundled/outputs.resource.set.json +++ b/docs/schemas/bundled/outputs.resource.set.json @@ -1,27 +1,27 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.resource.set.json", - "title": "DSC Resource set result", + "title": "dsc resource set result", "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command.", "type": "object", "required": [ - "before_state", - "after_state", - "changed_properties" + "beforeState", + "afterState", + "changedProperties" ], "properties": { - "before_state": { + "beforeState": { "title": "State before enforcing", "description": "This property always represents the desired state of the DSC Resource instance before the `set` method runs. DSC validates this return value against the DSC Resource's schema.", "type": "object" }, - "after_state": { + "afterState": { "title": "State after enforcing", "description": "This property always represents the current state of the DSC Resource instance as returned by its `set` method after enforcing the desired state. DSC validates this return value against the DSC Resource's schema.", "type": "object" }, - "changed_properties": { - "title": "Changed Properties", + "changedProperties": { + "title": "Changed properties", "description": "This property always represents the list of property names for the DSC Resource instance that the `set` method modified. When this value is an empty array, the `set` method didn't enforce any properties for the instance.", "type": "array", "default": [], diff --git a/docs/schemas/bundled/outputs.resource.test.json b/docs/schemas/bundled/outputs.resource.test.json index 346ce4944..028056c4f 100644 --- a/docs/schemas/bundled/outputs.resource.test.json +++ b/docs/schemas/bundled/outputs.resource.test.json @@ -1,27 +1,33 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.resource.test.json", - "title": "DSC Resource test result", + "title": "dsc resource test result", "description": "Describes the return data for a DSC Resource instance from the `dsc resource test` command.", "type": "object", "required": [ - "expected_state", - "actual_state", - "diff_properties" + "desiredState", + "actualState", + "inDesiredState", + "differingProperties" ], "properties": { - "expected_state": { - "title": "Expected State", + "desiredState": { + "title": "Desired state", "description": "This property always represents the desired state of the DSC Resource instance as specified to DSC.", "type": "object" }, - "actual_state": { - "title": "Actual State", + "actualState": { + "title": "Actual state", "description": "This property always represents the current state of the DSC Resource instance as returned by its `test` method or, if the DSC Resource doesn't define the `test` method, by its `get` method. DSC validates this return value against the DSC Resource's schema.", "type": "object" }, - "diff_properties": { - "title": "Differing Properties", + "inDesiredState": { + "title": "Instance is in the desired state", + "description": "This property indicates whether the instance is in the desired state.", + "type": "boolean" + }, + "differingProperties": { + "title": "Differing properties", "description": "This property always represents the list of property names for the DSC Resource instance that aren't in the desired state. When this property is an empty array, the instance is in the desired state.", "type": "array", "default": [], diff --git a/docs/schemas/bundled/resource.manifest.json b/docs/schemas/bundled/resource.manifest.json index 7863612b9..ffad7c948 100644 --- a/docs/schemas/bundled/resource.manifest.json +++ b/docs/schemas/bundled/resource.manifest.json @@ -36,6 +36,7 @@ "title": "Tags", "description": "An array of short strings used to search for DSC Resources.", "type": "array", + "uniqueItems": true, "items": { "type": "string", "pattern": "^\\w+$" diff --git a/docs/schemas/bundled/resource.manifest.vscode.json b/docs/schemas/bundled/resource.manifest.vscode.json index fdead63ad..4ecb719d9 100644 --- a/docs/schemas/bundled/resource.manifest.vscode.json +++ b/docs/schemas/bundled/resource.manifest.vscode.json @@ -36,6 +36,7 @@ "title": "Tags", "description": "An array of short strings used to search for DSC Resources.", "type": "array", + "uniqueItems": true, "items": { "type": "string", "pattern": "^\\w+$" diff --git a/docs/schemas/bundled/resource.manifest.vscode.yaml b/docs/schemas/bundled/resource.manifest.vscode.yaml index 26eca8df2..55f8e53b9 100644 --- a/docs/schemas/bundled/resource.manifest.vscode.yaml +++ b/docs/schemas/bundled/resource.manifest.vscode.yaml @@ -29,6 +29,7 @@ properties: title: Tags description: An array of short strings used to search for DSC Resources. type: array + uniqueItems: true items: type: string pattern: ^\w+$ diff --git a/docs/schemas/bundled/resource.manifest.yaml b/docs/schemas/bundled/resource.manifest.yaml index 8fbe2614a..fff419b56 100644 --- a/docs/schemas/bundled/resource.manifest.yaml +++ b/docs/schemas/bundled/resource.manifest.yaml @@ -29,6 +29,7 @@ properties: title: Tags description: An array of short strings used to search for DSC Resources. type: array + uniqueItems: true items: type: string pattern: ^\w+$ diff --git a/docs/schemas/outputs/resource/get.yaml b/docs/schemas/outputs/resource/get.yaml index 0930ef584..2cc1c9a90 100644 --- a/docs/schemas/outputs/resource/get.yaml +++ b/docs/schemas/outputs/resource/get.yaml @@ -2,17 +2,17 @@ $schema: https://json-schema.org/draft/2020-12/schema $id: https://schemas.microsoft.com/dsc/2023/07/results/resource/get.yaml -title: DSC Resource get result +title: dsc resource get result description: >- Describes the return data for a DSC Resource instance from the `dsc resource get` command. type: object required: - - actual_state + - actualState properties: - actual_state: - title: The DSC Resource instance's current state + actualState: + title: Actual state description: >- This property always represents the current state of the DSC Resource instance as returned by its `get` method. DSC validates this return value diff --git a/docs/schemas/outputs/resource/list.yaml b/docs/schemas/outputs/resource/list.yaml index ebf63295a..77511b54a 100644 --- a/docs/schemas/outputs/resource/list.yaml +++ b/docs/schemas/outputs/resource/list.yaml @@ -2,7 +2,7 @@ $schema: https://json-schema.org/draft/2020-12/schema $id: https://schemas.microsoft.com/dsc/2023/07/results/resource/list.yaml -title: DSC Resource list result +title: dsc resource list result description: >- Describes the return data for a DSC Resource instance from the `dsc resource list` command. @@ -18,6 +18,12 @@ properties: version: # Only the Test* resources seem to have this field populated. $ref: /dsc/2023/07/definitions/semver.yaml + description: + title: Resource Description + description: >- + A short synopsis of the DSC Resource's purpose. + # Should this include a maximum length or a pattern that forbids newlines? + type: string path: # This value seems to mean something different for the Test* resources title: Path @@ -34,9 +40,7 @@ properties: implementedAs: title: Implemented as description: >- - Indicates how the DSC Resource was implemented. To specify a custom - implementation, specify this value as an object with the `custom` - property. + Indicates how the DSC Resource was implemented. oneOf: - title: Standard implementation description: >- diff --git a/docs/schemas/outputs/resource/set.yaml b/docs/schemas/outputs/resource/set.yaml index 088ec4d4c..27410b8a1 100644 --- a/docs/schemas/outputs/resource/set.yaml +++ b/docs/schemas/outputs/resource/set.yaml @@ -2,33 +2,33 @@ $schema: https://json-schema.org/draft/2020-12/schema $id: https://schemas.microsoft.com/dsc/2023/07/results/resource/set.yaml -title: DSC Resource set result +title: dsc resource set result description: >- Describes the return data for a DSC Resource instance from the `dsc resource set` command. type: object required: - - before_state - - after_state - - changed_properties + - beforeState + - afterState + - changedProperties properties: - before_state: + beforeState: title: State before enforcing description: >- This property always represents the desired state of the DSC Resource instance before the `set` method runs. DSC validates this return value against the DSC Resource's schema. type: object - after_state: + afterState: title: State after enforcing description: >- This property always represents the current state of the DSC Resource instance as returned by its `set` method after enforcing the desired state. DSC validates this return value against the DSC Resource's schema. type: object - changed_properties: - title: Changed Properties + changedProperties: + title: Changed properties description: >- This property always represents the list of property names for the DSC Resource instance that the `set` method modified. When this value is an diff --git a/docs/schemas/outputs/resource/test.yaml b/docs/schemas/outputs/resource/test.yaml index 17789f04d..fdd8a70d9 100644 --- a/docs/schemas/outputs/resource/test.yaml +++ b/docs/schemas/outputs/resource/test.yaml @@ -2,33 +2,39 @@ $schema: https://json-schema.org/draft/2020-12/schema $id: https://schemas.microsoft.com/dsc/2023/07/results/resource/test.yaml -title: DSC Resource test result +title: dsc resource test result description: >- Describes the return data for a DSC Resource instance from the `dsc resource test` command. type: object required: - - expected_state - - actual_state - - diff_properties + - desiredState + - actualState + - inDesiredState + - differingProperties properties: - expected_state: - title: Expected State + desiredState: + title: Desired state description: >- This property always represents the desired state of the DSC Resource instance as specified to DSC. type: object - actual_state: - title: Actual State + actualState: + title: Actual state description: >- This property always represents the current state of the DSC Resource instance as returned by its `test` method or, if the DSC Resource doesn't define the `test` method, by its `get` method. DSC validates this return value against the DSC Resource's schema. type: object - diff_properties: - title: Differing Properties + inDesiredState: + title: Instance is in the desired state + description: >- + This property indicates whether the instance is in the desired state. + type: boolean + differingProperties: + title: Differing properties description: >- This property always represents the list of property names for the DSC Resource instance that aren't in the desired state. When this property From ecdd9ba872324e734268805df9773a2b7ce9061d Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Tue, 1 Aug 2023 16:31:04 -0500 Subject: [PATCH 08/11] (DOCS) Document CLI output schemas --- docs/reference/schemas/definitions/message.md | 71 ++++++++ docs/reference/schemas/outputs/config/get.md | 91 ++++++++++ docs/reference/schemas/outputs/config/set.md | 92 ++++++++++ docs/reference/schemas/outputs/config/test.md | 92 ++++++++++ .../reference/schemas/outputs/resource/get.md | 37 ++++ .../schemas/outputs/resource/list.md | 158 ++++++++++++++++++ .../reference/schemas/outputs/resource/set.md | 59 +++++++ .../schemas/outputs/resource/test.md | 67 ++++++++ 8 files changed, 667 insertions(+) create mode 100644 docs/reference/schemas/definitions/message.md create mode 100644 docs/reference/schemas/outputs/config/get.md create mode 100644 docs/reference/schemas/outputs/config/set.md create mode 100644 docs/reference/schemas/outputs/config/test.md create mode 100644 docs/reference/schemas/outputs/resource/get.md create mode 100644 docs/reference/schemas/outputs/resource/list.md create mode 100644 docs/reference/schemas/outputs/resource/set.md create mode 100644 docs/reference/schemas/outputs/resource/test.md diff --git a/docs/reference/schemas/definitions/message.md b/docs/reference/schemas/definitions/message.md new file mode 100644 index 000000000..aa1e0caf0 --- /dev/null +++ b/docs/reference/schemas/definitions/message.md @@ -0,0 +1,71 @@ +# Structured message schema reference + +## Synopsis + +A message emitted by a DSC Resource with associated metadata. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/definitions/message.yaml +Type : object +``` + +## Description + +## Required properties + +Every message must be an object that defines these properties: + +- [name](#name) +- [type](#type) +- [message](#message) +- [level](#level) + +## Properties + +### name + +Identifies the instance by its short, unique, human-readable name as defined in the configuration +document. + +```yaml +Type: string +Required: true +``` + +### type + +Identifies the instance's DSC Resource by its fully qualified type name. For more information about +type names, see [DSC Resource fully qualified type name schema reference][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +### message + +The actual content of the message as emitted by the DSC Resource. + +```yaml +Type: string +Required: true +``` + +### level + +Indicates the severity of the message. + +```yaml +Type: string +Required: true +Valid Values: + - Error + - Warning + - Information +``` + +[01]: resourceType.md diff --git a/docs/reference/schemas/outputs/config/get.md b/docs/reference/schemas/outputs/config/get.md new file mode 100644 index 000000000..71a12420c --- /dev/null +++ b/docs/reference/schemas/outputs/config/get.md @@ -0,0 +1,91 @@ +# dsc config get result schema reference + +## Synopsis + +The result output from the `dsc config get` command. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/results/config/get.yaml +Type : object +``` + +## Description + +The output from the `dsc config get` command includes the actual state for every resource instance +in the configuration document. + +## Required properties + +The output always includes these properties: + +- [results](#results) +- [messages](#messages) +- [hadErrors](#haderrors) + +## Properties + +### results + +Defines the list of results for the `get` operation invoked against every instance in the +configuration document. Every entry in the list includes the resource's type name, instance name, +and the result data for an instance. + +```yaml +Type: array +Required: true +Items Type: object +``` + +#### type + +An item's `type` property identifies the instance's DSC Resource by its fully qualified type name. +For more information about type names, see +[DSC Resource fully qualified type name schema reference][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +#### name + +An item's `name` property identifies the instance by its short, unique, human-readable name. + +```yaml +Type: string +Required: true +``` + +#### result + +An item's `result` property includes the actual state for the resource instance. The value for this +property adheres to the same schema as the output for the `dsc resource get` command. For more +information, see [dsc resource get result schema reference][02]. + +### messages + +Defines the list of structured messages emitted by resources during the get operation. For more +information, see [Structured message schema reference][03]. + +```yaml +Type: array +Required: true +``` + +### hadErrors + +Indicates whether the operation encountered any errors. This value is `true` if the configuration +document failed validation or any resource exited with an exit code other than `0`. + +```yaml +Type: boolean +Required: true +``` + +[01]: ../../definitions/resourceType.md +[02]: ../resource/get.md +[03]: ../../definitions/message.md diff --git a/docs/reference/schemas/outputs/config/set.md b/docs/reference/schemas/outputs/config/set.md new file mode 100644 index 000000000..4450a0d37 --- /dev/null +++ b/docs/reference/schemas/outputs/config/set.md @@ -0,0 +1,92 @@ +# dsc config set result schema reference + +## Synopsis + +The result output from the `dsc config set` command. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/results/config/set.yaml +Type : object +``` + +## Description + +The output from the `dsc config set` command includes the state of every resource instance in the +configuration before and after the set operation, and the list of properties the operation changed +for each instance. + +## Required properties + +The output always includes these properties: + +- [results](#results) +- [messages](#messages) +- [hadErrors](#haderrors) + +## Properties + +### results + +Defines the list of results for the `set` operation invoked against every instance in the +configuration document. Every entry in the list includes the resource's type name, instance name, +and the result data for an instance. + +```yaml +Type: array +Required: true +Items Type: object +``` + +#### type + +An item's `type` property identifies the instance's DSC Resource by its fully qualified type name. +For more information about type names, see +[DSC Resource fully qualified type name schema reference][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +#### name + +An item's `name` property identifies the instance by its short, unique, human-readable name. + +```yaml +Type: string +Required: true +``` + +#### result + +An item's `result` property includes the actual state for the resource instance. The value for this +property adheres to the same schema as the output for the `dsc resource set` command. For more +information, see [dsc resource set result schema reference][02]. + +### messages + +Defines the list of structured messages emitted by resources during the set operation. For more +information, see [Structured message schema reference][03]. + +```yaml +Type: array +Required: true +``` + +### hadErrors + +Indicates whether the operation encountered any errors. This value is `true` if the configuration +document failed validation or any resource exited with an exit code other than `0`. + +```yaml +Type: boolean +Required: true +``` + +[01]: ../../definitions/resourceType.md +[02]: ../resource/set.md +[03]: ../../definitions/message.md diff --git a/docs/reference/schemas/outputs/config/test.md b/docs/reference/schemas/outputs/config/test.md new file mode 100644 index 000000000..a0aeb566e --- /dev/null +++ b/docs/reference/schemas/outputs/config/test.md @@ -0,0 +1,92 @@ +# dsc config test result schema reference + +## Synopsis + +The result output from the `dsc config test` command. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/results/config/test.yaml +Type : object +``` + +## Description + +The output from the `dsc config test` command includes the state of every resource instance in the +configuration before and after the test operation, and the list of properties the operation changed +for each instance. + +## Required properties + +The output always includes these properties: + +- [results](#results) +- [messages](#messages) +- [hadErrors](#haderrors) + +## Properties + +### results + +Defines the list of results for the `test` operation invoked against every instance in the +configuration document. Every entry in the list includes the resource's type name, instance name, +and the result data for an instance. + +```yaml +Type: array +Required: true +Items Type: object +``` + +#### type + +An item's `type` property identifies the instance's DSC Resource by its fully qualified type name. +For more information about type names, see +[DSC Resource fully qualified type name schema reference][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +#### name + +An item's `name` property identifies the instance by its short, unique, human-readable name. + +```yaml +Type: string +Required: true +``` + +#### result + +An item's `result` property includes the actual state for the resource instance. The value for this +property adheres to the same schema as the output for the `dsc resource test` command. For more +information, see [dsc resource test result schema reference][02]. + +### messages + +Defines the list of structured messages emitted by resources during the test operation. For more +information, see [Structured message schema reference][03]. + +```yaml +Type: array +Required: true +``` + +### hadErrors + +Indicates whether the operation encountered any errors. This value is `true` if the configuration +document failed validation or any resource exited with an exit code other than `0`. + +```yaml +Type: boolean +Required: true +``` + +[01]: ../../definitions/resourceType.md +[02]: ../resource/test.md +[03]: ../../definitions/message.md diff --git a/docs/reference/schemas/outputs/resource/get.md b/docs/reference/schemas/outputs/resource/get.md new file mode 100644 index 000000000..2aa370346 --- /dev/null +++ b/docs/reference/schemas/outputs/resource/get.md @@ -0,0 +1,37 @@ +# dsc resource get result schema reference + +## Synopsis + +The result output from the `dsc resource get` command. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/results/resource/get.yaml +Type : object +``` + +## Description + +The output from the `dsc resource get` command includes the actual state for the specified resource +instance. + +## Required properties + +The output always includes these properties: + +- [actualState](#actualstate) + +## Properties + +### actualState + +The `actualState` property always includes the state of the instance returned when DSC invokes the +resource's get operation. DSC validates this property's value against the resource's instance +schema. + +```yaml +Type: object +Required: true +``` diff --git a/docs/reference/schemas/outputs/resource/list.md b/docs/reference/schemas/outputs/resource/list.md new file mode 100644 index 000000000..20e5e25cc --- /dev/null +++ b/docs/reference/schemas/outputs/resource/list.md @@ -0,0 +1,158 @@ +# dsc resource list result schema reference + +## Synopsis + +The result output from the `dsc resource list` command. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/results/resource/list.yaml +Type : object +``` + +## Description + +The output from the `dsc resource list` command includes a representation of discovered DSC +Resources as a series of [JSON Lines][01]. This schema describes the JSON object returned for each +resource. + +## Required properties + +Each resource in the output always includes these properties: + +- [type](#type) +- [version](#version) +- [path](#path) +- [directory](#directory) +- [implementedAs](#implementedas) +- [author](#author) +- [properties](#properties) +- [requires](#requires) +- [manifest](#manifest) + +## Properties + +### type + +Identifies the fully qualified type name of the resource. It's used to specify the resource in +configuration documents and as the value of the `--resource` flag when using the `dsc resource *` +commands. For more information about resource type names, see +[DSC Resource fully qualified type name schema reference][02]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +### version + +Represents the current version of the resource as a valid semantic version (semver) string. The +version applies to the resource, not the software it manages. + +```yaml +Type: string +Required: true +Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ +``` + +### description + +Defines a synopsis for the resource's purpose as a short string. If the resource doesn't have a +description, this property is `null`. + +```yaml +Type: [string, 'null'] +Required: true +``` + +### path + +Represents the path to the resource's manifest on the machine. For resources made available through +a provider, this property identifies the path to the file that defines the resource instead. + +```yaml +Type: string +Required: true +``` + +### directory + +Represents the path to the folder containing the resource's manifest on the machine. For resources +made available through a provider, this property identifies the path to the folder containing the +file that defines the resource instead. + +```yaml +Type: string +Required: true +``` + +### implementedAs + +Indicates how the DSC Resource was implemented. For command-based resources, this value is always +`Command`. + + + +### author + +Indicates the name of the person or organization that developed and maintains the DSC Resource. If +this property is `null`, the author is unknown. + + + +```yaml +Type: [string, 'null'] +Required: true +``` + +### properties + +Defines the property names for resources made available through a provider resource. For other +resources, this property is an empty array. + + + +```yaml +Type: array +Required: true +Items Type: string +Items Pattern: ^\w+$ +``` + +### requires + +Defines the fully qualified type name of the provider resource that this resource is made available +through. + +```yaml +Type: [string, 'null'] +Required: true +``` + +### manifest + +Represents the values defined in the resource's manifest. This value is `null` for resources that +aren't command-based. For more information on the value for this property, see +[Command-based DSC Resource manifest schema reference][03]. + +```yaml +Type: [object, 'null'] +Required: true +``` + +[01]: https://jsonlines.org/ +[02]: ../../definitions/resourceType.md +[03]: ../../resource/manifest/root.md diff --git a/docs/reference/schemas/outputs/resource/set.md b/docs/reference/schemas/outputs/resource/set.md new file mode 100644 index 000000000..c1445a666 --- /dev/null +++ b/docs/reference/schemas/outputs/resource/set.md @@ -0,0 +1,59 @@ +# dsc resource set result schema reference + +## Synopsis + +The result output from the `dsc resource set` command. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/results/resource/set.yaml +Type : object +``` + +## Description + +The output from the `dsc resource set` command includes the state of the resource instance before +and after the set operation, and the list of properties the operation changed. + +## Required properties + +The output always includes these properties: + +- [beforeState](#beforestate) +- [afterState](#afterstate) +- [changedProperties](#changedproperties) + +## Properties + +### beforeState + +Represents the state of the instance returned before the set operation. DSC validates this +property's value against the resource's instance schema. + +```yaml +Type: object +Required: true +``` + +### afterState + +Represents the state of the instance returned after the set operation. DSC validates this +property's value against the resource's instance schema. + +```yaml +Type: object +Required: true +``` + +### changedProperties + +Defines the names of the properties the set operation enforced. If this value is an empty array, +the resource made no changes during the set operation. + +```yaml +Type: array +Required: true +Items Type: string +``` diff --git a/docs/reference/schemas/outputs/resource/test.md b/docs/reference/schemas/outputs/resource/test.md new file mode 100644 index 000000000..afe52020f --- /dev/null +++ b/docs/reference/schemas/outputs/resource/test.md @@ -0,0 +1,67 @@ +# dsc resource test result schema reference + +## Synopsis + +The result output from the `dsc resource test` command. + +## Metadata + +```yaml +Schema Dialect : https://json-schema.org/draft/2020-12/schema +Schema ID : https://schemas.microsoft.com/dsc/2023/07/results/resource/test.yaml +Type : object +``` + +## Description + +The output from the `dsc resource test` command includes the actual state for the specified +resource instance. + +## Required properties + +The output always includes these properties: + +- [desiredState](#desiredstate) + +## Properties + +### desiredState + +Represents the desired state of the resource instance. DSC validates this property's value against +the resource's instance schema. + +```yaml +Type: object +Required: true +``` + +### actualState + +Represents the actual state of the resource instance. DSC validates this property's value against +the resource's instance schema. + +```yaml +Type: object +Required: true +``` + +### inDesiredState + +Indicates whether the resource instance's properties are in the desired state. This value is `true` +if every property is in the desired state and otherwise `false`. + +```yaml +Type: boolean +Required: true +``` + +### differingProperties + +Defines the names of the properties that aren't in the desired state. If this value is an empty +array, the instance's properties are in the desired state. + +```yaml +Type: array +Required: true +Items Type: string +``` From 5a68b02fbdeacb4509ed6bab3f5e4117b2c01d88 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Thu, 3 Aug 2023 13:09:07 -0500 Subject: [PATCH 09/11] (MAINT) Rework schemas for GitHub hosting This change prepares the repository and project for using the GitHub repository as the hosting location for the JSON Schemas. This change: - Moves the schemas out of the docs folder and into their own location - Updates the schema build script to generate a versioned output of the schemas that can be committed to the repository for external access in a reliable, coherent way. - Updates the schema build script to only export the schemas from source as JSON. - Updates the documentation to use the new canonical IDs for the schemas. --- docs/reference/schemas/config/document.md | 8 +- docs/reference/schemas/config/parameter.md | 2 +- docs/reference/schemas/config/resource.md | 6 +- docs/reference/schemas/definitions/message.md | 2 +- .../definitions/parameters/dataTypes.md | 2 +- .../schemas/definitions/resourceType.md | 2 +- docs/reference/schemas/outputs/config/get.md | 2 +- docs/reference/schemas/outputs/config/set.md | 2 +- docs/reference/schemas/outputs/config/test.md | 2 +- .../reference/schemas/outputs/resource/get.md | 2 +- .../schemas/outputs/resource/list.md | 2 +- .../reference/schemas/outputs/resource/set.md | 2 +- .../schemas/outputs/resource/test.md | 2 +- .../schemas/resource/manifest/get.md | 2 +- .../schemas/resource/manifest/provider.md | 2 +- .../schemas/resource/manifest/root.md | 2 +- .../resource/manifest/schema/embedded.md | 10 +- .../resource/manifest/schema/property.md | 2 +- .../schemas/resource/manifest/set.md | 2 +- .../schemas/resource/manifest/test.md | 2 +- .../schemas/resource/manifest/validate.md | 2 +- .../schemas/resource/properties/ensure.md | 4 +- .../resource/properties/inDesiredState.md | 4 +- .../schemas/resource/properties/purge.md | 4 +- .../resource/properties/rebootRequested.md | 4 +- docs/schemas/bundle.config.yaml | 42 - docs/schemas/bundled/config.document.json | 99 -- .../bundled/config.document.vscode.json | 109 -- .../bundled/config.document.vscode.yaml | 91 -- docs/schemas/bundled/config.document.yaml | 86 -- .../bundled/example.gotstoy.resource.json | 65 - .../bundled/example.gotstoy.resource.yaml | 55 - .../bundled/manual.config.document.yaml | 224 ---- .../bundled/manual.resource.manifest.yaml | 337 ----- docs/schemas/bundled/outputs.config.test.json | 157 --- .../bundled/outputs.config.validate.json | 9 - .../bundled/resource.manifest.vscode.json | 549 -------- .../bundled/resource.manifest.vscode.yaml | 432 ------ docs/schemas/bundled/resource.manifest.yaml | 463 ------- docs/schemas/outputs/config/validate.yaml | 13 - schemas/2023/08/bundled/config/document.json | 226 ++++ .../08/bundled/config/document.vscode.json | 244 ++++ .../2023/08/bundled/outputs/config/get.json | 251 ++-- .../2023/08/bundled/outputs/config/set.json | 267 ++-- .../2023/08/bundled/outputs/config/test.json | 118 ++ .../2023/08/bundled/outputs/resource/get.json | 34 +- .../08/bundled/outputs/resource/list.json | 1190 +++++++---------- .../08/bundled/outputs/resource/schema.json | 14 +- .../2023/08/bundled/outputs/resource/set.json | 66 +- .../08/bundled/outputs/resource/test.json | 78 +- .../2023/08/bundled/outputs/schema.json | 14 +- .../2023/08/bundled/resource/manifest.json | 1021 ++++++-------- .../08/bundled/resource/manifest.vscode.json | 412 ++++++ schemas/2023/08/config/document.json | 49 + .../2023/08/config/document.parameter.json | 102 ++ schemas/2023/08/config/document.resource.json | 33 + schemas/2023/08/definitions/commandArgs.json | 10 + .../08/definitions/commandExecutable.json | 7 + schemas/2023/08/definitions/hadErrors.json | 7 + schemas/2023/08/definitions/inputKind.json | 12 + schemas/2023/08/definitions/instanceName.json | 7 + schemas/2023/08/definitions/message.json | 39 + schemas/2023/08/definitions/messages.json | 10 + .../08/definitions/parameters/dataTypes.json | 16 + .../parameters/validValueTypes.json | 12 + schemas/2023/08/definitions/resourceType.json | 8 + schemas/2023/08/definitions/returnKind.json | 12 + schemas/2023/08/definitions/semver.json | 9 + schemas/2023/08/outputs/config/get.json | 45 + schemas/2023/08/outputs/config/set.json | 45 + schemas/2023/08/outputs/config/test.json | 45 + schemas/2023/08/outputs/resource/get.json | 17 + schemas/2023/08/outputs/resource/list.json | 91 ++ schemas/2023/08/outputs/resource/schema.json | 7 + schemas/2023/08/outputs/resource/set.json | 33 + schemas/2023/08/outputs/resource/test.json | 39 + schemas/2023/08/outputs/schema.json | 7 + schemas/2023/08/resource/manifest.get.json | 34 + schemas/2023/08/resource/manifest.json | 88 ++ .../2023/08/resource/manifest.provider.json | 53 + schemas/2023/08/resource/manifest.schema.json | 195 +++ schemas/2023/08/resource/manifest.set.json | 44 + schemas/2023/08/resource/manifest.test.json | 38 + .../2023/08/resource/manifest.validate.json | 27 + .../2023/08/resource/properties/ensure.json | 11 + .../resource/properties/inDesiredState.json | 11 + .../2023/08/resource/properties/purge.json | 11 + .../resource/properties/rebootRequested.json | 11 + {docs/schemas => schemas}/build.ps1 | 185 ++- schemas/examples/foo.dsc.resource.json | 40 + schemas/examples/foo.dsc.resource.yaml | 20 + schemas/schemas.config.yaml | 61 + .../src}/config/document.parameter.yaml | 8 +- .../src}/config/document.resource.yaml | 6 +- .../src}/config/document.yaml | 8 +- .../src}/definitions/commandArgs.yaml | 2 +- .../src}/definitions/commandExecutable.yaml | 2 +- .../src}/definitions/hadErrors.yaml | 2 +- .../src}/definitions/inputKind.yaml | 2 +- .../src}/definitions/instanceName.yaml | 2 +- .../src}/definitions/message.yaml | 4 +- .../src}/definitions/messages.yaml | 4 +- .../definitions/parameters/dataTypes.yaml | 2 +- .../parameters/validValueTypes.yaml | 2 +- .../src}/definitions/resourceType.yaml | 2 +- .../src}/definitions/returnKind.yaml | 2 +- .../src}/definitions/semver.yaml | 2 +- .../src}/outputs/config/get.yaml | 12 +- .../src}/outputs/config/set.yaml | 12 +- .../src}/outputs/config/test.yaml | 12 +- .../src}/outputs/resource/get.yaml | 2 +- .../src}/outputs/resource/list.yaml | 10 +- .../src}/outputs/resource/schema.yaml | 2 +- .../src}/outputs/resource/set.yaml | 2 +- .../src}/outputs/resource/test.yaml | 2 +- .../src}/outputs/schema.yaml | 2 +- .../src}/resource/manifest.get.yaml | 8 +- .../src}/resource/manifest.provider.yaml | 6 +- .../src}/resource/manifest.schema.yaml | 14 +- .../src}/resource/manifest.set.yaml | 10 +- .../src}/resource/manifest.test.yaml | 10 +- .../src}/resource/manifest.validate.yaml | 6 +- .../src}/resource/manifest.yaml | 20 +- .../src}/resource/properties/ensure.yaml | 2 +- .../resource/properties/inDesiredState.yaml | 2 +- .../src}/resource/properties/purge.yaml | 2 +- .../resource/properties/rebootRequested.yaml | 2 +- 127 files changed, 3843 insertions(+), 4578 deletions(-) delete mode 100644 docs/schemas/bundle.config.yaml delete mode 100644 docs/schemas/bundled/config.document.json delete mode 100644 docs/schemas/bundled/config.document.vscode.json delete mode 100644 docs/schemas/bundled/config.document.vscode.yaml delete mode 100644 docs/schemas/bundled/config.document.yaml delete mode 100644 docs/schemas/bundled/example.gotstoy.resource.json delete mode 100644 docs/schemas/bundled/example.gotstoy.resource.yaml delete mode 100644 docs/schemas/bundled/manual.config.document.yaml delete mode 100644 docs/schemas/bundled/manual.resource.manifest.yaml delete mode 100644 docs/schemas/bundled/outputs.config.test.json delete mode 100644 docs/schemas/bundled/outputs.config.validate.json delete mode 100644 docs/schemas/bundled/resource.manifest.vscode.json delete mode 100644 docs/schemas/bundled/resource.manifest.vscode.yaml delete mode 100644 docs/schemas/bundled/resource.manifest.yaml delete mode 100644 docs/schemas/outputs/config/validate.yaml create mode 100644 schemas/2023/08/bundled/config/document.json create mode 100644 schemas/2023/08/bundled/config/document.vscode.json rename docs/schemas/bundled/outputs.config.get.json => schemas/2023/08/bundled/outputs/config/get.json (58%) rename docs/schemas/bundled/outputs.config.set.json => schemas/2023/08/bundled/outputs/config/set.json (50%) create mode 100644 schemas/2023/08/bundled/outputs/config/test.json rename docs/schemas/bundled/outputs.resource.get.json => schemas/2023/08/bundled/outputs/resource/get.json (84%) rename docs/schemas/bundled/outputs.resource.list.json => schemas/2023/08/bundled/outputs/resource/list.json (60%) rename docs/schemas/bundled/outputs.resource.schema.json => schemas/2023/08/bundled/outputs/resource/schema.json (73%) rename docs/schemas/bundled/outputs.resource.set.json => schemas/2023/08/bundled/outputs/resource/set.json (91%) rename docs/schemas/bundled/outputs.resource.test.json => schemas/2023/08/bundled/outputs/resource/test.json (92%) rename docs/schemas/bundled/outputs.schema.json => schemas/2023/08/bundled/outputs/schema.json (73%) rename docs/schemas/bundled/resource.manifest.json => schemas/2023/08/bundled/resource/manifest.json (58%) create mode 100644 schemas/2023/08/bundled/resource/manifest.vscode.json create mode 100644 schemas/2023/08/config/document.json create mode 100644 schemas/2023/08/config/document.parameter.json create mode 100644 schemas/2023/08/config/document.resource.json create mode 100644 schemas/2023/08/definitions/commandArgs.json create mode 100644 schemas/2023/08/definitions/commandExecutable.json create mode 100644 schemas/2023/08/definitions/hadErrors.json create mode 100644 schemas/2023/08/definitions/inputKind.json create mode 100644 schemas/2023/08/definitions/instanceName.json create mode 100644 schemas/2023/08/definitions/message.json create mode 100644 schemas/2023/08/definitions/messages.json create mode 100644 schemas/2023/08/definitions/parameters/dataTypes.json create mode 100644 schemas/2023/08/definitions/parameters/validValueTypes.json create mode 100644 schemas/2023/08/definitions/resourceType.json create mode 100644 schemas/2023/08/definitions/returnKind.json create mode 100644 schemas/2023/08/definitions/semver.json create mode 100644 schemas/2023/08/outputs/config/get.json create mode 100644 schemas/2023/08/outputs/config/set.json create mode 100644 schemas/2023/08/outputs/config/test.json create mode 100644 schemas/2023/08/outputs/resource/get.json create mode 100644 schemas/2023/08/outputs/resource/list.json create mode 100644 schemas/2023/08/outputs/resource/schema.json create mode 100644 schemas/2023/08/outputs/resource/set.json create mode 100644 schemas/2023/08/outputs/resource/test.json create mode 100644 schemas/2023/08/outputs/schema.json create mode 100644 schemas/2023/08/resource/manifest.get.json create mode 100644 schemas/2023/08/resource/manifest.json create mode 100644 schemas/2023/08/resource/manifest.provider.json create mode 100644 schemas/2023/08/resource/manifest.schema.json create mode 100644 schemas/2023/08/resource/manifest.set.json create mode 100644 schemas/2023/08/resource/manifest.test.json create mode 100644 schemas/2023/08/resource/manifest.validate.json create mode 100644 schemas/2023/08/resource/properties/ensure.json create mode 100644 schemas/2023/08/resource/properties/inDesiredState.json create mode 100644 schemas/2023/08/resource/properties/purge.json create mode 100644 schemas/2023/08/resource/properties/rebootRequested.json rename {docs/schemas => schemas}/build.ps1 (76%) create mode 100644 schemas/examples/foo.dsc.resource.json create mode 100644 schemas/examples/foo.dsc.resource.yaml create mode 100644 schemas/schemas.config.yaml rename {docs/schemas => schemas/src}/config/document.parameter.yaml (89%) rename {docs/schemas => schemas/src}/config/document.resource.yaml (83%) rename {docs/schemas => schemas/src}/config/document.yaml (85%) rename {docs/schemas => schemas/src}/definitions/commandArgs.yaml (76%) rename {docs/schemas => schemas/src}/definitions/commandExecutable.yaml (72%) rename {docs/schemas => schemas/src}/definitions/hadErrors.yaml (77%) rename {docs/schemas => schemas/src}/definitions/inputKind.yaml (80%) rename {docs/schemas => schemas/src}/definitions/instanceName.yaml (78%) rename {docs/schemas => schemas/src}/definitions/message.yaml (87%) rename {docs/schemas => schemas/src}/definitions/messages.yaml (69%) rename {docs/schemas => schemas/src}/definitions/parameters/dataTypes.yaml (78%) rename {docs/schemas => schemas/src}/definitions/parameters/validValueTypes.yaml (83%) rename {docs/schemas => schemas/src}/definitions/resourceType.yaml (84%) rename {docs/schemas => schemas/src}/definitions/returnKind.yaml (86%) rename {docs/schemas => schemas/src}/definitions/semver.yaml (93%) rename {docs/schemas => schemas/src}/outputs/config/get.yaml (67%) rename {docs/schemas => schemas/src}/outputs/config/set.yaml (67%) rename {docs/schemas => schemas/src}/outputs/config/test.yaml (67%) rename {docs/schemas => schemas/src}/outputs/resource/get.yaml (88%) rename {docs/schemas => schemas/src}/outputs/resource/list.yaml (90%) rename {docs/schemas => schemas/src}/outputs/resource/schema.yaml (81%) rename {docs/schemas => schemas/src}/outputs/resource/set.yaml (94%) rename {docs/schemas => schemas/src}/outputs/resource/test.yaml (94%) rename {docs/schemas => schemas/src}/outputs/schema.yaml (82%) rename {docs/schemas => schemas/src}/resource/manifest.get.yaml (65%) rename {docs/schemas => schemas/src}/resource/manifest.provider.yaml (85%) rename {docs/schemas => schemas/src}/resource/manifest.schema.yaml (90%) rename {docs/schemas => schemas/src}/resource/manifest.set.yaml (77%) rename {docs/schemas => schemas/src}/resource/manifest.test.yaml (71%) rename {docs/schemas => schemas/src}/resource/manifest.validate.yaml (71%) rename {docs/schemas => schemas/src}/resource/manifest.yaml (78%) rename {docs/schemas => schemas/src}/resource/properties/ensure.yaml (76%) rename {docs/schemas => schemas/src}/resource/properties/inDesiredState.yaml (79%) rename {docs/schemas => schemas/src}/resource/properties/purge.yaml (84%) rename {docs/schemas => schemas/src}/resource/properties/rebootRequested.yaml (76%) diff --git a/docs/reference/schemas/config/document.md b/docs/reference/schemas/config/document.md index 486910c8d..1891f901a 100644 --- a/docs/reference/schemas/config/document.md +++ b/docs/reference/schemas/config/document.md @@ -8,7 +8,7 @@ The YAML or JSON file that defines a DSC Configuration. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/config/document.json +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json Type : object ``` @@ -52,7 +52,7 @@ Type: string Required: true Format: URI Valid Values: - - https://schemas.microsoft.com/dsc/2023/07/config/document.yaml + - https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json ``` ### metadata @@ -83,7 +83,7 @@ configuration, see [DSC Configuration parameters][03] ```yaml Type: object Required: false -Valid Property Schema: https://schemas.microsoft.com/dsc/2023/07/config/document.parameter.yaml +Valid Property Schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json ``` ### variables @@ -118,7 +118,7 @@ in a configuration, see [DSC Configuration resources][06] and Type: array Required: false Minimum Item Count: 1 -Valid Item Schema: https://schemas.microsoft.com/dsc/2023/07/config/document.resource.json +Valid Item Schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json ``` [01]: ../../../configurations/overview.md diff --git a/docs/reference/schemas/config/parameter.md b/docs/reference/schemas/config/parameter.md index 5275b73dc..178fc55bc 100644 --- a/docs/reference/schemas/config/parameter.md +++ b/docs/reference/schemas/config/parameter.md @@ -8,7 +8,7 @@ Defines runtime options for a configuration. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.json +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json Type : object ``` diff --git a/docs/reference/schemas/config/resource.md b/docs/reference/schemas/config/resource.md index d7e55943c..0f3fb0b81 100644 --- a/docs/reference/schemas/config/resource.md +++ b/docs/reference/schemas/config/resource.md @@ -1,14 +1,14 @@ -# DSC Configuration document resource schema +# DSC Configuration document resource instance schema ## Synopsis -Defines instances of DSC Resources that compose a configuration. +Defines a DSC Resource instance in a configuration document. ## Metadata ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/config/document.resources.json +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json Type : object ``` diff --git a/docs/reference/schemas/definitions/message.md b/docs/reference/schemas/definitions/message.md index aa1e0caf0..c64c5d88d 100644 --- a/docs/reference/schemas/definitions/message.md +++ b/docs/reference/schemas/definitions/message.md @@ -8,7 +8,7 @@ A message emitted by a DSC Resource with associated metadata. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/definitions/message.yaml +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/message.json Type : object ``` diff --git a/docs/reference/schemas/definitions/parameters/dataTypes.md b/docs/reference/schemas/definitions/parameters/dataTypes.md index 84aa28525..f8fcb981c 100644 --- a/docs/reference/schemas/definitions/parameters/dataTypes.md +++ b/docs/reference/schemas/definitions/parameters/dataTypes.md @@ -8,7 +8,7 @@ Defines valid data types for a DSC configuration parameter ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataTypes.yaml +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json Type : string Valid Values: - array diff --git a/docs/reference/schemas/definitions/resourceType.md b/docs/reference/schemas/definitions/resourceType.md index 7425a223b..72526d715 100644 --- a/docs/reference/schemas/definitions/resourceType.md +++ b/docs/reference/schemas/definitions/resourceType.md @@ -8,7 +8,7 @@ Identifies a DSC Resource. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/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 index 71a12420c..bc78fee06 100644 --- a/docs/reference/schemas/outputs/config/get.md +++ b/docs/reference/schemas/outputs/config/get.md @@ -8,7 +8,7 @@ The result output from the `dsc config get` command. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/results/config/get.yaml +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/get.json Type : object ``` diff --git a/docs/reference/schemas/outputs/config/set.md b/docs/reference/schemas/outputs/config/set.md index 4450a0d37..24dc5c34f 100644 --- a/docs/reference/schemas/outputs/config/set.md +++ b/docs/reference/schemas/outputs/config/set.md @@ -8,7 +8,7 @@ The result output from the `dsc config set` command. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/results/config/set.yaml +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/set.json Type : object ``` diff --git a/docs/reference/schemas/outputs/config/test.md b/docs/reference/schemas/outputs/config/test.md index a0aeb566e..61e8593cd 100644 --- a/docs/reference/schemas/outputs/config/test.md +++ b/docs/reference/schemas/outputs/config/test.md @@ -8,7 +8,7 @@ The result output from the `dsc config test` command. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/results/config/test.yaml +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/test.json Type : object ``` diff --git a/docs/reference/schemas/outputs/resource/get.md b/docs/reference/schemas/outputs/resource/get.md index 2aa370346..85eebee3a 100644 --- a/docs/reference/schemas/outputs/resource/get.md +++ b/docs/reference/schemas/outputs/resource/get.md @@ -8,7 +8,7 @@ The result output from the `dsc resource get` command. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/results/resource/get.yaml +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/get.json Type : object ``` diff --git a/docs/reference/schemas/outputs/resource/list.md b/docs/reference/schemas/outputs/resource/list.md index 20e5e25cc..8e06b5177 100644 --- a/docs/reference/schemas/outputs/resource/list.md +++ b/docs/reference/schemas/outputs/resource/list.md @@ -8,7 +8,7 @@ The result output from the `dsc resource list` command. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/results/resource/list.yaml +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/list.json Type : object ``` diff --git a/docs/reference/schemas/outputs/resource/set.md b/docs/reference/schemas/outputs/resource/set.md index c1445a666..8dfab0f2e 100644 --- a/docs/reference/schemas/outputs/resource/set.md +++ b/docs/reference/schemas/outputs/resource/set.md @@ -8,7 +8,7 @@ The result output from the `dsc resource set` command. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/results/resource/set.yaml +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/set.json Type : object ``` diff --git a/docs/reference/schemas/outputs/resource/test.md b/docs/reference/schemas/outputs/resource/test.md index afe52020f..8f4e2de4d 100644 --- a/docs/reference/schemas/outputs/resource/test.md +++ b/docs/reference/schemas/outputs/resource/test.md @@ -8,7 +8,7 @@ The result output from the `dsc resource test` command. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/results/resource/test.yaml +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/test.json Type : object ``` diff --git a/docs/reference/schemas/resource/manifest/get.md b/docs/reference/schemas/resource/manifest/get.md index fcfbc94fb..938837cbc 100644 --- a/docs/reference/schemas/resource/manifest/get.md +++ b/docs/reference/schemas/resource/manifest/get.md @@ -8,7 +8,7 @@ Defines how to retrieve a DSC Resource instance. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.json +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json Type : object ``` diff --git a/docs/reference/schemas/resource/manifest/provider.md b/docs/reference/schemas/resource/manifest/provider.md index de66e0dd6..cf0fbe1b8 100644 --- a/docs/reference/schemas/resource/manifest/provider.md +++ b/docs/reference/schemas/resource/manifest/provider.md @@ -8,7 +8,7 @@ Defines a DSC Resource as a DSC Resource Provider. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.json +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json Type : object ``` diff --git a/docs/reference/schemas/resource/manifest/root.md b/docs/reference/schemas/resource/manifest/root.md index ef0687597..113d9c092 100644 --- a/docs/reference/schemas/resource/manifest/root.md +++ b/docs/reference/schemas/resource/manifest/root.md @@ -8,7 +8,7 @@ The JSON file that defines a command-based DSC Resource. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/manifest.json +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json Type : object ``` diff --git a/docs/reference/schemas/resource/manifest/schema/embedded.md b/docs/reference/schemas/resource/manifest/schema/embedded.md index 13b63d377..5951d09d8 100644 --- a/docs/reference/schemas/resource/manifest/schema/embedded.md +++ b/docs/reference/schemas/resource/manifest/schema/embedded.md @@ -8,7 +8,7 @@ Defines a JSON Schema that validates a DSC Resource instance. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.json#/properties/embedded +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json#/properties/embedded Type : object ``` @@ -100,7 +100,7 @@ If defined, this property must be a reference to the schema for the well-known p ```json "_ensure": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json" } ``` @@ -116,7 +116,7 @@ If defined, this property must be a reference to the schema for the well-known p ```json "_inDesiredState": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json" } ``` @@ -132,7 +132,7 @@ If defined, this property must be a reference to the schema for the well-known p ```json "_inDesiredState": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json" } ``` @@ -148,7 +148,7 @@ If defined, this property must be a reference to the schema for the well-known p ```json "_rebootRequested": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" } ``` diff --git a/docs/reference/schemas/resource/manifest/schema/property.md b/docs/reference/schemas/resource/manifest/schema/property.md index 328d87009..9eca4c2c3 100644 --- a/docs/reference/schemas/resource/manifest/schema/property.md +++ b/docs/reference/schemas/resource/manifest/schema/property.md @@ -8,7 +8,7 @@ Defines how to retrieve the JSON Schema that validates a DSC Resource instance. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.json +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json Type : object ``` diff --git a/docs/reference/schemas/resource/manifest/set.md b/docs/reference/schemas/resource/manifest/set.md index 562779c67..30677f954 100644 --- a/docs/reference/schemas/resource/manifest/set.md +++ b/docs/reference/schemas/resource/manifest/set.md @@ -8,7 +8,7 @@ Defines how to enforce state for a DSC Resource instance. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.json +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json Type : object ``` diff --git a/docs/reference/schemas/resource/manifest/test.md b/docs/reference/schemas/resource/manifest/test.md index d5d50d85a..185f4880d 100644 --- a/docs/reference/schemas/resource/manifest/test.md +++ b/docs/reference/schemas/resource/manifest/test.md @@ -8,7 +8,7 @@ Defines how to test whether a DSC Resource instance is in the desired state. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.json +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json Type : object ``` diff --git a/docs/reference/schemas/resource/manifest/validate.md b/docs/reference/schemas/resource/manifest/validate.md index dfb50be27..e5304da21 100644 --- a/docs/reference/schemas/resource/manifest/validate.md +++ b/docs/reference/schemas/resource/manifest/validate.md @@ -8,7 +8,7 @@ This property ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.json +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json Type : object ``` diff --git a/docs/reference/schemas/resource/properties/ensure.md b/docs/reference/schemas/resource/properties/ensure.md index 097198880..3f373be19 100644 --- a/docs/reference/schemas/resource/properties/ensure.md +++ b/docs/reference/schemas/resource/properties/ensure.md @@ -8,7 +8,7 @@ Indicates whether an instance should exist. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json Type : string Valid Values : [Absent, Present] ``` @@ -29,7 +29,7 @@ snippet: ```json "_ensure": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json" } ``` diff --git a/docs/reference/schemas/resource/properties/inDesiredState.md b/docs/reference/schemas/resource/properties/inDesiredState.md index 75b7c2188..98532aff0 100644 --- a/docs/reference/schemas/resource/properties/inDesiredState.md +++ b/docs/reference/schemas/resource/properties/inDesiredState.md @@ -8,7 +8,7 @@ Indicates whether an instance is in the desired state. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json Type : [boolean, 'null'] Read Only : true ``` @@ -36,7 +36,7 @@ snippet: ```json "_inDesiredState": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json" } ``` diff --git a/docs/reference/schemas/resource/properties/purge.md b/docs/reference/schemas/resource/properties/purge.md index f13acbcb5..1d367c686 100644 --- a/docs/reference/schemas/resource/properties/purge.md +++ b/docs/reference/schemas/resource/properties/purge.md @@ -8,7 +8,7 @@ Indicates that the resource should treat non-defined entries in a list as invali ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json Type : [boolean, 'null'] Write Only : true ``` @@ -37,6 +37,6 @@ snippet: ```json "_inDesiredState": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json" } ``` diff --git a/docs/reference/schemas/resource/properties/rebootRequested.md b/docs/reference/schemas/resource/properties/rebootRequested.md index 809c2939f..0d180617a 100644 --- a/docs/reference/schemas/resource/properties/rebootRequested.md +++ b/docs/reference/schemas/resource/properties/rebootRequested.md @@ -8,7 +8,7 @@ Indicates whether an instance is in the desired state. ```yaml Schema Dialect : https://json-schema.org/draft/2020-12/schema -Schema ID : https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json +Schema ID : https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json Type : [boolean, 'null'] Read Only : true ``` @@ -36,6 +36,6 @@ snippet: ```json "_rebootRequested": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" } ``` diff --git a/docs/schemas/bundle.config.yaml b/docs/schemas/bundle.config.yaml deleted file mode 100644 index 0ea0c40b8..000000000 --- a/docs/schemas/bundle.config.yaml +++ /dev/null @@ -1,42 +0,0 @@ -bundle_schemas: - # Resource manifest bundle - - ConfigFilePath: resource/manifest.yaml - Name: resource.manifest - OutputFormat: ['Json', 'JsonVSCode', 'Yaml', 'YamlVSCode'] - - # Configuration document bundle - - ConfigFilePath: config/document.yaml - Name: config.document - OutputFormat: ['Json', 'JsonVSCode', 'Yaml', 'YamlVSCode'] - - # Output schema bundles - - ConfigFilePath: outputs/schema.yaml - Name: outputs.schema - OutputFormat: ['Json'] - - ConfigFilePath: outputs/config/get.yaml - Name: outputs.config.get - OutputFormat: ['Json'] - - ConfigFilePath: outputs/config/set.yaml - Name: outputs.config.set - OutputFormat: ['Json'] - - ConfigFilePath: outputs/config/test.yaml - Name: outputs.config.test - OutputFormat: ['Json'] - - ConfigFilePath: outputs/config/validate.yaml - Name: outputs.config.validate - OutputFormat: ['Json'] - - ConfigFilePath: outputs/resource/get.yaml - Name: outputs.resource.get - OutputFormat: ['Json'] - - ConfigFilePath: outputs/resource/list.yaml - Name: outputs.resource.list - OutputFormat: ['Json'] - - ConfigFilePath: outputs/resource/schema.yaml - Name: outputs.resource.schema - OutputFormat: ['Json'] - - ConfigFilePath: outputs/resource/set.yaml - Name: outputs.resource.set - OutputFormat: ['Json'] - - ConfigFilePath: outputs/resource/test.yaml - Name: outputs.resource.test - OutputFormat: ['Json'] diff --git a/docs/schemas/bundled/config.document.json b/docs/schemas/bundled/config.document.json deleted file mode 100644 index 7118f9fca..000000000 --- a/docs/schemas/bundled/config.document.json +++ /dev/null @@ -1,99 +0,0 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/config.document.json", - "title": "DSC Configuration Document schema", - "description": "Describes a valid DSC Configuration Document.", - "type": "object", - "required": [ - "$schema", - "resources" - ], - "properties": { - "$schema": { - "title": "Schema", - "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", - "type": "string", - "format": "uri", - "enum": [ - "https://schemas.microsoft.com/dsc/2023/07/config/document.json" - ] - }, - "parameters": { - "title": "DSC Configuration document parameters", - "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", - "type": "object", - "additionalProperties": { - "$ref": "/dsc/2023/07/config/document.parameters.json" - } - }, - "variables": { - "title": "Configuration variables", - "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", - "type": "object" - }, - "resources": { - "title": "DSC Configuration document resources", - "description": "Defines a list of DSC Resource instances for the configuration to manage.", - "type": "array", - "minItems": 1, - "items": { - "$ref": "/dsc/2023/07/config/document.resource.json" - } - }, - "metadata": { - "title": "Configuration metadata", - "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", - "type": "object" - } - }, - "$defs": { - "https://schemas.microsoft.com/dsc/2023/07/config/document.resource.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/config/document.resource.json", - "title": "DSC Resource instance", - "type": "object", - "required": [ - "type", - "name" - ], - "properties": { - "type": { - "$ref": "/dsc/2023/07/definitions/resourceType.json" - }, - "name": { - "$ref": "/dsc/2023/07/definitions/instanceName.json" - }, - "dependsOn": { - "title": "Instance depends on", - "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", - "type": "array", - "items": { - "type": "string", - "uniqueItems": true, - "pattern": "^\\[\\w+(\\.\\w+){0,2}\\/\\w+\\].+$" - } - }, - "properties": { - "title": "Managed instance properties", - "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", - "type": "object" - } - } - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json", - "title": "DSC Resource fully qualified type name", - "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", - "type": "string", - "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.json", - "title": "Instance name", - "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", - "type": "string" - } - } -} diff --git a/docs/schemas/bundled/config.document.vscode.json b/docs/schemas/bundled/config.document.vscode.json deleted file mode 100644 index e609080a0..000000000 --- a/docs/schemas/bundled/config.document.vscode.json +++ /dev/null @@ -1,109 +0,0 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/config.document.json", - "title": "DSC Configuration Document schema", - "description": "Describes a valid DSC Configuration Document.", - "type": "object", - "required": [ - "$schema", - "resources" - ], - "properties": { - "$schema": { - "title": "Schema", - "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", - "type": "string", - "format": "uri", - "enum": [ - "https://schemas.microsoft.com/dsc/2023/07/config/document.json" - ] - }, - "parameters": { - "title": "DSC Configuration document parameters", - "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", - "type": "object", - "additionalProperties": { - "$ref": "#/$defs/dsc/2023/07/config/document.parameters.json" - } - }, - "variables": { - "title": "Configuration variables", - "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", - "type": "object" - }, - "resources": { - "title": "DSC Configuration document resources", - "description": "Defines a list of DSC Resource instances for the configuration to manage.", - "type": "array", - "minItems": 1, - "items": { - "$ref": "#/$defs/dsc/2023/07/config/document.resource.json" - } - }, - "metadata": { - "title": "Configuration metadata", - "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", - "type": "object" - } - }, - "$defs": { - "dsc": { - "2023": { - "07": { - "config": { - "document.resource.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/config/document.resource.json", - "title": "DSC Resource instance", - "type": "object", - "required": [ - "type", - "name" - ], - "properties": { - "type": { - "$ref": "#/$defs/dsc/2023/07/definitions/resourceType.json" - }, - "name": { - "$ref": "#/$defs/dsc/2023/07/definitions/instanceName.json" - }, - "dependsOn": { - "title": "Instance depends on", - "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", - "type": "array", - "items": { - "type": "string", - "uniqueItems": true, - "pattern": "^\\[\\w+(\\.\\w+){0,2}\\/\\w+\\].+$" - } - }, - "properties": { - "title": "Managed instance properties", - "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", - "type": "object" - } - } - } - }, - "definitions": { - "resourceType.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json", - "title": "DSC Resource fully qualified type name", - "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", - "type": "string", - "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" - }, - "instanceName.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.json", - "title": "Instance name", - "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", - "type": "string" - } - } - } - } - } - } -} diff --git a/docs/schemas/bundled/config.document.vscode.yaml b/docs/schemas/bundled/config.document.vscode.yaml deleted file mode 100644 index 6d8a9e0d6..000000000 --- a/docs/schemas/bundled/config.document.vscode.yaml +++ /dev/null @@ -1,91 +0,0 @@ -$schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/bundled/config.document.yaml -title: DSC Configuration Document schema -description: Describes a valid DSC Configuration Document. -type: object -required: -- $schema -- resources -properties: - $schema: - title: Schema - description: This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for. - type: string - format: uri - enum: - - https://schemas.microsoft.com/dsc/2023/07/config/document.yaml - parameters: - title: DSC Configuration document parameters - description: Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration. - type: object - additionalProperties: - $ref: '#/$defs/dsc/2023/07/config/document.parameters.yaml' - variables: - title: Configuration variables - description: Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value. - type: object - resources: - title: DSC Configuration document resources - description: Defines a list of DSC Resource instances for the configuration to manage. - type: array - minItems: 1 - items: - $ref: '#/$defs/dsc/2023/07/config/document.resource.yaml' - metadata: - title: Configuration metadata - description: Defines a set of key-value pairs for the configuration. This metadata isn't validated. - type: object -$defs: - dsc: - "2023": - "07": - config: - document.resource.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/config/document.resource.yaml - title: DSC Resource instance - type: object - required: - - type - - name - properties: - type: - $ref: '#/$defs/dsc/2023/07/definitions/resourceType.yaml' - name: - $ref: '#/$defs/dsc/2023/07/definitions/instanceName.yaml' - dependsOn: - title: Instance depends on - description: Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property. - type: array - items: - type: string - uniqueItems: true - pattern: ^\[\w+(\.\w+){0,2}\/\w+\].+$ - properties: - title: Managed instance properties - description: Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema. - type: object - definitions: - resourceType.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml - title: DSC Resource fully qualified type name - description: > - The namespaced name of the DSC Resource, using the syntax: - - - owner[.group][.area]/name - - - For example: - - - Microsoft.SqlServer/Database - - Microsoft.SqlServer.Database/User - type: string - pattern: ^\w+(\.\w+){0,2}\/\w+$ - instanceName.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.yaml - title: Instance name - description: The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. - type: string diff --git a/docs/schemas/bundled/config.document.yaml b/docs/schemas/bundled/config.document.yaml deleted file mode 100644 index b7afabd3d..000000000 --- a/docs/schemas/bundled/config.document.yaml +++ /dev/null @@ -1,86 +0,0 @@ -$schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/bundled/config.document.yaml -title: DSC Configuration Document schema -description: Describes a valid DSC Configuration Document. -type: object -required: -- $schema -- resources -properties: - $schema: - title: Schema - description: This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for. - type: string - format: uri - enum: - - https://schemas.microsoft.com/dsc/2023/07/config/document.yaml - parameters: - title: DSC Configuration document parameters - description: Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration. - type: object - additionalProperties: - $ref: /dsc/2023/07/config/document.parameters.yaml - variables: - title: Configuration variables - description: Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value. - type: object - resources: - title: DSC Configuration document resources - description: Defines a list of DSC Resource instances for the configuration to manage. - type: array - minItems: 1 - items: - $ref: /dsc/2023/07/config/document.resource.yaml - metadata: - title: Configuration metadata - description: Defines a set of key-value pairs for the configuration. This metadata isn't validated. - type: object -$defs: - https://schemas.microsoft.com/dsc/2023/07/config/document.resource.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/config/document.resource.yaml - title: DSC Resource instance - type: object - required: - - type - - name - properties: - type: - $ref: /dsc/2023/07/definitions/resourceType.yaml - name: - $ref: /dsc/2023/07/definitions/instanceName.yaml - dependsOn: - title: Instance depends on - description: Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property. - type: array - items: - type: string - uniqueItems: true - pattern: ^\[\w+(\.\w+){0,2}\/\w+\].+$ - properties: - title: Managed instance properties - description: Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema. - type: object - https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml - title: DSC Resource fully qualified type name - description: > - The namespaced name of the DSC Resource, using the syntax: - - - owner[.group][.area]/name - - - For example: - - - Microsoft.SqlServer/Database - - Microsoft.SqlServer.Database/User - type: string - pattern: ^\w+(\.\w+){0,2}\/\w+$ - https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.yaml - title: Instance name - description: The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document. - type: string diff --git a/docs/schemas/bundled/example.gotstoy.resource.json b/docs/schemas/bundled/example.gotstoy.resource.json deleted file mode 100644 index 37eae0e85..000000000 --- a/docs/schemas/bundled/example.gotstoy.resource.json +++ /dev/null @@ -1,65 +0,0 @@ -{ - "$schema": "resource.manifest.vscode.json", - "manifestVersion": "1.0", - "type": "TSToy.Example/gotstoy", - "version": "0.1.0", - "description": "The go implementation of a DSC Resource for the fictional TSToy application.", - "get": { - "executable": "gotstoy", - "args": ["get"], - "input": "stdin" - }, - "set": { - "executable": "gotstoy", - "args": ["set"], - "input": "stdin", - "preTest": false, - "return": "state" - }, - "schema": { - "embedded": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "title": "Golang TSToy Resource", - "type": "object", - "required": [ - "scope" - ], - "properties": { - "ensure": { - "title": "Ensure configuration file existence", - "description": "Defines whether the application's configuration file for this scope should exist or not.", - "type": "string", - "enum": [ - "present", - "absent" - ], - "default": "present" - }, - "scope": { - "title": "Target configuration scope", - "description": "Defines which of the application's configuration files the resource should manage.", - "type": "string", - "enum": [ - "machine", - "user" - ] - }, - "updateAutomatically": { - "title": "Should update automatically", - "description": "Indicates whether the application should check for updates when it starts.", - "type": "boolean" - }, - "updateFrequency": { - "title": "Update check frequency", - "description": "Indicates how many days the application should wait before checking for updates.", - "type": "integer", - "minimum": 1, - "maximum": 90 - }, - "_ensure": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json" - } - } - } - } -} diff --git a/docs/schemas/bundled/example.gotstoy.resource.yaml b/docs/schemas/bundled/example.gotstoy.resource.yaml deleted file mode 100644 index da575f64a..000000000 --- a/docs/schemas/bundled/example.gotstoy.resource.yaml +++ /dev/null @@ -1,55 +0,0 @@ -# yaml-language-server: $schema=resource.manifest.vscode.yaml -manifestVersion: '1.0.0' -type: TSToy.Example/gotstoy -version: 0.1.0 -description: The go implementation of a DSC Resource for the fictional TSToy application. -get: - executable: gotstoy - args: - - get - input: stdin -set: - executable: gotstoy - args: - - set - input: stdin - preTest: false - return: state -schema: - embedded: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://tailspintoys.com/schemas/gotstoy - title: Golang TSToy Resource - type: object - required: - - scope - properties: - ensure: - title: Ensure configuration file existence - description: Defines whether the application's configuration file for this - scope should exist or not. - type: string - enum: - - present - - absent - default: present - scope: - title: Target configuration scope - description: Defines which of the application's configuration files the resource - should manage. - type: string - enum: - - machine - - user - updateAutomatically: - title: Should update automatically - description: Indicates whether the application should check for updates when - it starts. - type: boolean - updateFrequency: - title: Update check frequency - description: Indicates how many days the application should wait before checking - for updates. - type: integer - minimum: 1 - maximum: 90 diff --git a/docs/schemas/bundled/manual.config.document.yaml b/docs/schemas/bundled/manual.config.document.yaml deleted file mode 100644 index ba0fc4f26..000000000 --- a/docs/schemas/bundled/manual.config.document.yaml +++ /dev/null @@ -1,224 +0,0 @@ -# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema -$schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/bundled/config.document.yaml - -title: DSC Configuration Document schema -description: >- - Describes a valid DSC Configuration Document. - -type: object -required: - - $schema - - resources -properties: - $schema: - title: Schema - description: >- - This property must be the canonical URL of the DSC Configuration Document - schema that the document is implemented for. - type: string - format: uri - enum: - - https://schemas.microsoft.com/dsc/2023/07/config/document.yaml - - parameters: - $ref: /dsc/2023/07/config/document.parameters.yaml - - variables: - title: Configuration variables - description: >- - Defines a set of reusable values for the configuration document. The - names of this value's properties are the strings used to reference a - variable's value. - type: object - - resources: - $ref: /dsc/2023/07/config/dataTypes.yaml - - metadata: - title: Configuration metadata - description: >- - Defines a set of key-value pairs for the configuration. This metadata - isn't validated. - type: object - -$defs: - https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/config/document.parameters.yaml - title: DSC Configuration document parameters - description: >- - Defines runtime options for the configuration. Users and integrating tools - can override use the defined parameters to pass alternate values to the - configuration. - type: object - patternProperties: - ".": - title: Parameter - description: >- - Defines a runtime option for a DSC Configuration Document. - type: object - required: - - type - properties: - type: - $ref: /dsc/2023/07/definitions/parameters/dataTypes.yaml - defaultValue: - title: Default value - description: >- - Defines the default value for the parameter. - $ref: "#/$defs/ValidValueTypes" - allowedValues: - title: Allowed values - description: >- - Defines a list of valid values for the parameter. If the - parameter is defined with any other values, it's invalid. - type: array - items: - $ref: "#/$defs/ValidValueTypes" - description: - title: Parameter description - description: >- - Defines a synopsis for the parameter explaining its purpose. - type: string - metadata: - title: Parameter metadata - description: >- - Defines a set of key-value pairs for the parameter. This metadata - isn't validated. - type: object - allOf: - - if: - properties: - type: - const: int - then: - $ref: "#/$defs/IntegerValidationProperties" - - if: - oneOf: - - properties: { type: { const: string } } - - properties: { type: { const: securestring } } - - properties: { type: { const: array } } - then: - $ref: "#/$defs/LengthValidationProperties" - $defs: - ValidValueTypes: - type: - - string - - integer - - object - - array - - boolean - IntegerValidationProperties: - properties: - minValue: - title: Minimum value - description: >- - The minimum valid value for an integer type. If defined with the - `maxValue` property, this value must be less than the value of - `maxValue`. - type: integer - minimum: 0 - maxValue: - title: Maximum value - description: >- - The maximum valid value for an integer type. If defined with the - `minValue` property, this value must be greater than the value of - `minValue`. - type: integer - minimum: 0 - LengthValidationProperties: - properties: - minLength: - title: Minimum length - description: >- - The minimum valid length for a `string`, `securestring`, or `array`. - If defined with the `maxLength` property, this value must be less - than the value of `maxLength`. - type: integer - minimum: 0 - maxLength: - title: Maximum length - description: >- - The maximum valid length for a `string`, `securestring`, or `array`. - If defined with the `minLength` property, this value must be less - than the value of `minLength`. - type: integer - minimum: 0 - - https://schemas.microsoft.com/dsc/2023/07/config/dataTypes.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/config/dataTypes.yaml - title: DSC Configuration document resources - description: >- - Defines a list of DSC Resource instances for the configuration to manage. - type: array - items: - title: DSC Resource instance - type: object - required: - - type - - name - properties: - type: - $ref: /dsc/2023/07/definitions/resourceType.yaml - name: - $ref: /dsc/2023/07/definitions/instanceName.yaml - dependsOn: - title: Instance depends on - description: >- - Defines a list of DSC Resource instances that DSC must successfully - process before processing this instance. Each value for this property - must be the value of another DSC Resource instance's `name` property. - type: array - items: - type: string - uniqueItems: true - properties: - title: Managed instance properties - description: >- - Defines the properties of the DSC Resource this instance manages. This - property's value must be an object. DSC validates the property's value - against the DSC Resource's schema. - type: object - - https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataTypes.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataTypes.yaml - title: Data Type - description: >- - Defines the data type for the value. - type: string - enum: - - string - - securestring - - int - - bool - - object - - secureobject - - array - - https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.yaml - title: Instance name - description: >- - The short, human-readable name for a DSC Resource instance. Must be unique - within a DSC Configuration document. - type: string - - https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml - title: DSC Resource fully qualified type name - description: | - The namespaced name of the DSC Resource, using the syntax: - - [.][.]/ - - For example: - - - Microsoft.SqlServer/Database - - Microsoft.SqlServer.Database/User - type: string - pattern: ^\w+(\.\w+){0,2}\/\w+$ diff --git a/docs/schemas/bundled/manual.resource.manifest.yaml b/docs/schemas/bundled/manual.resource.manifest.yaml deleted file mode 100644 index e345c5f9e..000000000 --- a/docs/schemas/bundled/manual.resource.manifest.yaml +++ /dev/null @@ -1,337 +0,0 @@ -# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema -$schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/bundled/resource.manifest.yaml - -title: Command-based DSC Resource Manifest -description: >- - Defines a valid command-based DSC Resource. - -type: object -required: - - manifestVersion - - type - - version - - get -properties: - manifestVersion: - title: Manifest Version - description: >- - The semver of the DSC Resource manifest schema to validate this manifest - with. - $ref: /dsc/2023/07/definitions/semver.yaml - enums: - - '1.0' - type: - $ref: /dsc/2023/07/definitions/resourceType.yaml - version: - title: Resource Semantic Version - description: >- - The semantic version (semver) of the DSC Resource. This version - identifies the DSC Resource, not the version of the application it - manages. - $ref: /dsc/2023/07/definitions/semver.yaml - description: - title: Resource Description - description: >- - A short synopsis of the DSC Resource's purpose. - # Should this include a maximum length or a pattern that forbids newlines? - type: string - tags: - title: Tags - description: >- - An array of short strings used to search for DSC Resources. - type: array - items: - type: string - pattern: ^\w+$ - get: - $ref: "$defs/dsc/2023/07/resource/manifest.get.yaml" - # $ref: /dsc/2023/07/resource/manifest.get.yaml - set: - $ref: /dsc/2023/07/resource/manifest.set.yaml - test: - $ref: /dsc/2023/07/resource/manifest.test.yaml - validate: - $ref: /dsc/2023/07/resource/manifest.validate.yaml - provider: - # I'm not clear on how this works in practice - $ref: /dsc/2023/07/resource/manifest.provider.yaml - exitCodes: - # This setting in the root of the schema implies exit codes must have the - # same meaning across all executions. What about implementations that - # support multiple executables? Should exitCodes be a key that exists on - # command/method objects too? - title: Exit Codes - description: >- - This property defines a map of valid exit codes for the DSC Resource. - DSC always interprets exit code `0` as a successful operation and any - other exit code as an error. Use this property to indicate human-readable - semantic meanings for the DSC Resource's exit codes. - type: object - propertyNames: - pattern: "^[0-9]+$" - patternProperties: - "^[0-9]+$": - type: string - examples: - - exitCodes: - "0": Success - "1": Invalid parameter - "2": Invalid input - "3": Registry error - "4": JSON serialization failed - schema: - $ref: /dsc/2023/07/resource/manifest.schema.yaml - -$defs: - https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.yaml - title: Executable Command Arguments - description: >- - The list of arguments to pass to the command. - type: array - items: - type: string - - https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.yaml - title: Executable Command Name - description: >- - The name of the command to run. - type: string - - https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.yaml - title: Executable Command Input Type - description: >- - Defines how DSC should pass input to the command, either as arguments or - JSON over stdin. - type: string - enum: - - args - - stdin - default: args - - https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml - title: DSC Resource fully qualified type name - description: | - The namespaced name of the DSC Resource, using the syntax: - - [.][.]/ - - For example: - - - Microsoft.SqlServer/Database - - Microsoft.SqlServer.Database/User - type: string - pattern: ^\w+(\.\w+){0,2}\/\w+$ - - https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.yaml - title: Return Kind - type: string - enum: - - state - - stateAndDiff - default: state - - https://schemas.microsoft.com/dsc/2023/07/definitions/semver.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/semver.yaml - type: string - title: Semantic Version - description: >- - A valid semantic version (semver) string. For reference, see https://semver.org/ - pattern: >- - ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ - - /dsc/2023/07/resource/manifest.get.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.yaml - title: Get Method - description: >- - Defines how DSC must call the DSC Resource to get the current state of an - instance. - type: object - required: - - executable - properties: - executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml - args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml - input: - $ref: /dsc/2023/07/definitions/inputKind.yaml - - https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.yaml - title: Provider - description: >- - Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider - enables users to manage resources that don't have their own manifests with - DSC. - type: object - required: - - list - - config - properties: - list: - title: List Command - description: >- - Defines how DSC must call the DSC Resource Provider to list its supported - DSC Resources. - type: object - required: - - executable - properties: - executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml - args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml - config: - title: Expected Configuration - description: >- - Defines whether the provider expects to receive a full and unprocessed - configuration as a single JSON blob over stdin or a sequence of JSON - Lines for each child resource's configurations. - type: string - enum: - - full - - sequence - - https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.yaml - title: Instance Schema - description: >- - Defines how DSC must validate a JSON blob representing an instance of the - DSC Resource. - type: object - oneOf: - - required: [command] - - required: [embedded] - properties: - command: - title: Instance Schema Command - description: >- - Defines how DSC must call the DSC Resource to get the JSON Schema for - validating a JSON blob representing an instance of the DSC Resource. - type: object - required: - - executable - properties: - executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml - args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml - embedded: - title: Embedded Instance Schema - description: >- - Defines the JSON Schema DSC must use to validate a JSON blob - representing an instance of the DSC Resource. - type: object - required: - - $schema - - $id - - properties - properties: - type: - const: object - $schema: - type: string - enum: - - https://json-schema.org/draft/2020-12/schema - - http://json-schema.org/draft-07/schema# - properties: - type: object - minProperties: 1 - unevaluatedProperties: - $ref: https://json-schema.org/draft/2020-12/schema - url: - title: Instance Schema URL - description: >- - Defines the URL to the DSC Resource's JSON schema for integrating tools. - type: string - format: uri - - https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.yaml - title: Set Method - description: >- - Defines how DSC must call the DSC Resource to set the desired state of - an instance and how to process the output from the DSC Resource. - type: object - required: - - executable - - input - properties: - executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml - args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml - input: - $ref: /dsc/2023/07/definitions/inputKind.yaml - preTest: - title: Resource Performs Pre-Test - description: >- - Defines whether the DSC Resource performs its own test to ensure - idempotency when calling the `set` command. Set this value to `true` - if the DSC Resource tests input before modifying system state. - type: boolean - default: false - return: - description: >- - Defines whether the command returns a JSON blob of the DSC Resource's - state after the set operation or the state and an array of the - properties the DSC Resource modified. - $ref: /dsc/2023/07/definitions/returnKind.yaml - - https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.yaml - title: Test Method - description: >- - Defines how DSC must call the DSC Resource to test if an instance is in - the desired state and how to process the output from the DSC Resource. - type: object - required: - - executable - - input - properties: - executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml - args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml - input: - $ref: /dsc/2023/07/definitions/inputKind.yaml - return: - title: Test Command Return Type - description: >- - Defines whether the command returns a JSON blob of the DSC Resource's current state or the - state and an array of the properties that are out of the desired state. - $ref: /dsc/2023/07/definitions/returnKind.yaml - - https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.yaml - title: Validate Method - description: >- - Defines how DSC must call the DSC Resource to validate the state of an - instance. This method is mandatory for DSC Group Resources. It's ignored for - all other DSC Resources. - type: object - required: - - executable - properties: - executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml - args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml diff --git a/docs/schemas/bundled/outputs.config.test.json b/docs/schemas/bundled/outputs.config.test.json deleted file mode 100644 index 4f4061f4b..000000000 --- a/docs/schemas/bundled/outputs.config.test.json +++ /dev/null @@ -1,157 +0,0 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.config.test.json", - "title": "DSC Configuration test command result", - "description": "Represents the data structure returned by the `dsc config test` command.", - "type": "object", - "required": [ - "results", - "messages", - "hadErrors" - ], - "properties": { - "results": { - "title": "Results", - "description": "The results of the `test` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", - "type": "array", - "items": { - "title": "Test Result", - "type": "object", - "required": [ - "name", - "type", - "result" - ], - "properties": { - "name": { - "$ref": "/dsc/2023/07/definitions/instanceName.json" - }, - "type": { - "$ref": "/dsc/2023/07/definitions/resourceType.json" - }, - "result": { - "$ref": "/dsc/2023/07/results/resource/test.json" - } - } - } - }, - "messages": { - "$ref": "/dsc/2023/07/definitions/messages.json" - }, - "hadErrors": { - "$ref": "/dsc/2023/07/definitions/hadErrors.json" - } - }, - "$defs": { - "https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.json", - "title": "Instance name", - "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", - "type": "string" - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json", - "title": "DSC Resource fully qualified type name", - "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", - "type": "string", - "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" - }, - "https://schemas.microsoft.com/dsc/2023/07/results/resource/test.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/results/resource/test.json", - "title": "dsc resource test result", - "description": "Describes the return data for a DSC Resource instance from the `dsc resource test` command.", - "type": "object", - "required": [ - "desiredState", - "actualState", - "inDesiredState", - "differingProperties" - ], - "properties": { - "desiredState": { - "title": "Desired state", - "description": "This property always represents the desired state of the DSC Resource instance as specified to DSC.", - "type": "object" - }, - "actualState": { - "title": "Actual state", - "description": "This property always represents the current state of the DSC Resource instance as returned by its `test` method or, if the DSC Resource doesn't define the `test` method, by its `get` method. DSC validates this return value against the DSC Resource's schema.", - "type": "object" - }, - "inDesiredState": { - "title": "Instance is in the desired state", - "description": "This property indicates whether the instance is in the desired state.", - "type": "boolean" - }, - "differingProperties": { - "title": "Differing properties", - "description": "This property always represents the list of property names for the DSC Resource instance that aren't in the desired state. When this property is an empty array, the instance is in the desired state.", - "type": "array", - "default": [], - "items": { - "type": "string" - } - } - } - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/messages.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/messages.json", - "title": "Messages", - "description": "A list of structured messages emitted by the DSC Resources during an operation.", - "type": "array", - "items": { - "$ref": "/dsc/2023/07/definitions/message.json" - } - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/hadErrors.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/hadErrors.json", - "title": "Had Errors", - "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", - "type": "boolean" - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/message.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/message.json", - "title": "Message", - "description": "A message emitted by a DSC Resource with associated metadata.", - "type": "object", - "required": [ - "name", - "type", - "message", - "level" - ], - "properties": { - "name": { - "title": "Message source instance name", - "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", - "type": "string" - }, - "type": { - "$ref": "/dsc/2023/07/definitions/resourceType.json" - }, - "message": { - "title": "Message content", - "description": "The actual content of the message as emitted by the DSC Resource.", - "type": "string", - "minLength": 1 - }, - "level": { - "title": "Message level", - "description": "Indicates the severity of the message.", - "type": "string", - "enum": [ - "Error", - "Warning", - "Information" - ] - } - } - } - } -} diff --git a/docs/schemas/bundled/outputs.config.validate.json b/docs/schemas/bundled/outputs.config.validate.json deleted file mode 100644 index b31375e5c..000000000 --- a/docs/schemas/bundled/outputs.config.validate.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.config.validate.json", - "$comment": "Not implemented yet.\n", - "title": "DSC Resource schema result", - "description": "Describes the return data for a DSC Resource from the `dsc config validate` command.", - "type": "object", - "$defs": {} -} diff --git a/docs/schemas/bundled/resource.manifest.vscode.json b/docs/schemas/bundled/resource.manifest.vscode.json deleted file mode 100644 index 4ecb719d9..000000000 --- a/docs/schemas/bundled/resource.manifest.vscode.json +++ /dev/null @@ -1,549 +0,0 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/resource.manifest.json", - "title": "Command-based DSC Resource Manifest", - "description": "Defines a valid command-based DSC Resource.", - "type": "object", - "required": [ - "manifestVersion", - "type", - "version", - "get" - ], - "properties": { - "manifestVersion": { - "title": "Manifest Version", - "description": "The semver of the DSC Resource manifest schema to validate this manifest with.", - "$ref": "#/$defs/dsc/2023/07/definitions/semver.json", - "enums": [ - "1.0" - ] - }, - "type": { - "$ref": "#/$defs/dsc/2023/07/definitions/resourceType.json" - }, - "version": { - "title": "Resource Semantic Version", - "description": "The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages.", - "$ref": "#/$defs/dsc/2023/07/definitions/semver.json" - }, - "description": { - "title": "Resource Description", - "description": "A short synopsis of the DSC Resource's purpose.", - "type": "string" - }, - "tags": { - "title": "Tags", - "description": "An array of short strings used to search for DSC Resources.", - "type": "array", - "uniqueItems": true, - "items": { - "type": "string", - "pattern": "^\\w+$" - } - }, - "get": { - "$ref": "#/$defs/dsc/2023/07/resource/manifest.get.json" - }, - "set": { - "$ref": "#/$defs/dsc/2023/07/resource/manifest.set.json" - }, - "test": { - "$ref": "#/$defs/dsc/2023/07/resource/manifest.test.json" - }, - "validate": { - "$ref": "#/$defs/dsc/2023/07/resource/manifest.validate.json" - }, - "provider": { - "$ref": "#/$defs/dsc/2023/07/resource/manifest.provider.json" - }, - "exitCodes": { - "title": "Exit Codes", - "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", - "type": "object", - "propertyNames": { - "pattern": "^[0-9]+$" - }, - "patternProperties": { - "^[0-9]+$": { - "type": "string" - } - }, - "examples": [ - { - "exitCodes": { - "0": "Success", - "1": "Invalid parameter", - "2": "Invalid input", - "3": "Registry error", - "4": "JSON serialization failed" - } - } - ] - }, - "schema": { - "$ref": "#/$defs/dsc/2023/07/resource/manifest.schema.json" - } - }, - "$defs": { - "dsc": { - "2023": { - "07": { - "definitions": { - "semver.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/semver.json", - "type": "string", - "title": "Semantic Version", - "description": "A valid semantic version (semver) string. For reference, see https://semver.org/", - "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", - "$comment": "This pattern comes from the semver website's FAQ:\n\nhttps://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n\nIt's the suggested regex pattern for JavaScript.\n\nThis is the same pattern, made multi-line for easier readability.\n\n```\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n" - }, - "resourceType.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json", - "title": "DSC Resource fully qualified type name", - "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", - "type": "string", - "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" - }, - "commandExecutable.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.json", - "title": "Executable Command Name", - "description": "The name of the command to run.", - "type": "string" - }, - "commandArgs.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.json", - "title": "Executable Command Arguments", - "description": "The list of arguments to pass to the command.", - "type": "array", - "items": { - "type": "string" - } - }, - "inputKind.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.json", - "title": "Executable Command Input Type", - "description": "Defines how DSC should pass input to the command, either as arguments or JSON over stdin.", - "type": "string", - "enum": [ - "args", - "stdin" - ], - "default": "args" - }, - "returnKind.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.json", - "title": "Return Kind", - "type": "string", - "enum": [ - "state", - "stateAndDiff" - ], - "default": "state", - "$comment": "While the enumeration for return kind is the same for the `set` and `test`\nmethod, the way it changes the behavior of the command isn't. The description\nkeyword isn't included here because the respective schemas for those methods\ndocument the behavior themselves." - } - }, - "resource": { - "manifest.get.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.json", - "title": "Get Method", - "description": "Defines how DSC must call the DSC Resource to get the current state of an instance.", - "type": "object", - "required": [ - "executable" - ], - "properties": { - "executable": { - "$ref": "#/$defs/dsc/2023/07/definitions/commandExecutable.json" - }, - "args": { - "$ref": "#/$defs/dsc/2023/07/definitions/commandArgs.json" - }, - "input": { - "$ref": "#/$defs/dsc/2023/07/definitions/inputKind.json" - } - }, - "examples": [ - { - "executable": "registry", - "args": [ - "config", - "get" - ], - "input": "stdin" - }, - { - "executable": "osinfo" - } - ] - }, - "manifest.set.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.json", - "title": "Set Method", - "description": "Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource.", - "type": "object", - "required": [ - "executable", - "input" - ], - "properties": { - "executable": { - "$ref": "#/$defs/dsc/2023/07/definitions/commandExecutable.json" - }, - "args": { - "$ref": "#/$defs/dsc/2023/07/definitions/commandArgs.json" - }, - "input": { - "$ref": "#/$defs/dsc/2023/07/definitions/inputKind.json" - }, - "preTest": { - "title": "Resource Performs Pre-Test", - "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", - "type": "boolean", - "default": false - }, - "return": { - "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", - "$ref": "#/$defs/dsc/2023/07/definitions/returnKind.json" - } - }, - "examples": [ - { - "executable": "registry", - "args": [ - "config", - "set" - ], - "input": "stdin", - "preTest": true, - "return": "state" - } - ] - }, - "manifest.test.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.json", - "title": "Test Method", - "description": "Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource.", - "type": "object", - "required": [ - "executable", - "input" - ], - "properties": { - "executable": { - "$ref": "#/$defs/dsc/2023/07/definitions/commandExecutable.json" - }, - "args": { - "$ref": "#/$defs/dsc/2023/07/definitions/commandArgs.json" - }, - "input": { - "$ref": "#/$defs/dsc/2023/07/definitions/inputKind.json" - }, - "return": { - "title": "Test Command Return Type", - "description": "Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state.", - "$ref": "#/$defs/dsc/2023/07/definitions/returnKind.json" - } - }, - "examples": [ - { - "executable": "registry", - "args": [ - "config", - "test" - ], - "input": "stdin", - "return": "state" - } - ] - }, - "manifest.validate.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.json", - "title": "Validate Method", - "description": "Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources.", - "type": "object", - "required": [ - "executable" - ], - "properties": { - "executable": { - "$ref": "#/$defs/dsc/2023/07/definitions/commandExecutable.json" - }, - "args": { - "$ref": "#/$defs/dsc/2023/07/definitions/commandArgs.json" - } - }, - "examples": [ - { - "executable": "dsc", - "args": [ - "config", - "validate" - ] - } - ] - }, - "manifest.provider.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.json", - "title": "Provider", - "description": "Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to manage resources that don't have their own manifests with DSC.", - "type": "object", - "required": [ - "list", - "config" - ], - "properties": { - "list": { - "title": "List Command", - "description": "Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.", - "type": "object", - "required": [ - "executable" - ], - "properties": { - "executable": { - "$ref": "#/$defs/dsc/2023/07/definitions/commandExecutable.json" - }, - "args": { - "$ref": "#/$defs/dsc/2023/07/definitions/commandArgs.json" - } - } - }, - "config": { - "title": "Expected Configuration", - "description": "Defines whether the provider expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations.", - "type": "string", - "enum": [ - "full", - "sequence" - ] - } - }, - "examples": [ - { - "config": "full", - "list": { - "executable": "pwsh", - "args": [ - "-NoLogo", - "-NonInteractive", - "-NoProfile", - "-Command", - "./powershellgroup.resource.ps1 List" - ] - } - } - ] - }, - "manifest.schema.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.json", - "title": "Instance Schema", - "description": "Defines how DSC must validate a JSON blob representing an instance of the DSC Resource.", - "type": "object", - "oneOf": [ - { - "required": [ - "command" - ] - }, - { - "required": [ - "embedded" - ] - } - ], - "properties": { - "command": { - "title": "Instance Schema Command", - "description": "Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource.", - "type": "object", - "required": [ - "executable" - ], - "properties": { - "executable": { - "$ref": "#/$defs/dsc/2023/07/definitions/commandExecutable.json" - }, - "args": { - "$ref": "#/$defs/dsc/2023/07/definitions/commandArgs.json" - } - } - }, - "embedded": { - "title": "Embedded Instance Schema", - "description": "Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource.", - "type": "object", - "required": [ - "$schema", - "type", - "properties" - ], - "properties": { - "type": { - "title": "Instance Type", - "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", - "const": "object" - }, - "$schema": { - "title": "DSC Resource instance schema dialect", - "description": "Defines which dialect of JSON Schema the DSC Resource is using to validate instances.", - "type": "string", - "format": "uri-reference", - "enum": [ - "https://json-schema.org/draft/2020-12/schema", - "https://json-schema.org/draft/2019-09/schema", - "http://json-schema.org/draft-07/schema#" - ] - }, - "$id": { - "title": "DSC Resource instance schema ID", - "description": "Defines the unique ID for the DSC Resource's instance schema.", - "type": "string", - "format": "uri-reference" - }, - "properties": { - "title": "Instance Properties", - "description": "Defines the schema for the DSC Resource's properties. Must define at least one property.", - "type": "object", - "minProperties": 1, - "unevaluatedProperties": { - "anyOf": [ - { - "$ref": "https://json-schema.org/draft/2020-12/schema" - }, - { - "$ref": "https://json-schema.org/draft/2019-09/schema" - }, - { - "$ref": "http://json-schema.org/draft-07/schema#" - } - ] - }, - "properties": { - "_ensure": { - "title": "Standard Property: _ensure", - "description": "Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums.", - "const": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json" - } - }, - "_inDesiredState": { - "title": "Standard Property: _inDesiredState", - "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", - "const": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json" - } - }, - "_purge": { - "title": "Standard Property: _purge", - "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", - "const": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json" - } - }, - "_rebootRequested": { - "title": "Standard property: _rebootRequested", - "description": "Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes.", - "const": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json" - } - } - } - } - } - }, - "url": { - "title": "Instance Schema URL", - "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", - "type": "string", - "format": "uri" - } - }, - "examples": [ - { - "command": { - "executable": "registry", - "args": [ - "schema" - ] - } - }, - { - "embedded": { - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "OSInfo", - "type": "object", - "required": [], - "properties": { - "$id": { - "type": "string" - }, - "architecture": { - "type": [ - "string", - "null" - ] - }, - "bitness": { - "$ref": "#/definitions/Bitness" - }, - "codename": { - "type": [ - "string", - "null" - ] - }, - "edition": { - "type": [ - "string", - "null" - ] - }, - "family": { - "$ref": "#/definitions/Family" - }, - "version": { - "type": "string" - } - }, - "additionalProperties": false, - "definitions": { - "Bitness": { - "type": "string", - "enum": [ - "32", - "64", - "unknown" - ] - }, - "Family": { - "type": "string", - "enum": [ - "Linux", - "macOS", - "Windows" - ] - } - } - } - } - ] - } - } - } - } - } - } -} diff --git a/docs/schemas/bundled/resource.manifest.vscode.yaml b/docs/schemas/bundled/resource.manifest.vscode.yaml deleted file mode 100644 index 55f8e53b9..000000000 --- a/docs/schemas/bundled/resource.manifest.vscode.yaml +++ /dev/null @@ -1,432 +0,0 @@ -$schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/bundled/resource.manifest.yaml -title: Command-based DSC Resource Manifest -description: Defines a valid command-based DSC Resource. -type: object -required: -- manifestVersion -- type -- version -- get -properties: - manifestVersion: - title: Manifest Version - description: The semver of the DSC Resource manifest schema to validate this manifest with. - $ref: '#/$defs/dsc/2023/07/definitions/semver.yaml' - enums: - - "1.0" - type: - $ref: '#/$defs/dsc/2023/07/definitions/resourceType.yaml' - version: - title: Resource Semantic Version - description: The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages. - $ref: '#/$defs/dsc/2023/07/definitions/semver.yaml' - description: - title: Resource Description - description: A short synopsis of the DSC Resource's purpose. - type: string - tags: - title: Tags - description: An array of short strings used to search for DSC Resources. - type: array - uniqueItems: true - items: - type: string - pattern: ^\w+$ - get: - $ref: '#/$defs/dsc/2023/07/resource/manifest.get.yaml' - set: - $ref: '#/$defs/dsc/2023/07/resource/manifest.set.yaml' - test: - $ref: '#/$defs/dsc/2023/07/resource/manifest.test.yaml' - validate: - $ref: '#/$defs/dsc/2023/07/resource/manifest.validate.yaml' - provider: - $ref: '#/$defs/dsc/2023/07/resource/manifest.provider.yaml' - exitCodes: - title: Exit Codes - description: This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes. - type: object - propertyNames: - pattern: ^[0-9]+$ - patternProperties: - ^[0-9]+$: - type: string - examples: - - exitCodes: - "0": Success - "1": Invalid parameter - "2": Invalid input - "3": Registry error - "4": JSON serialization failed - schema: - $ref: '#/$defs/dsc/2023/07/resource/manifest.schema.yaml' -$defs: - dsc: - "2023": - "07": - definitions: - semver.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/semver.yaml - type: string - title: Semantic Version - description: A valid semantic version (semver) string. For reference, see https://semver.org/ - pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ - $comment: > - This pattern comes from the semver website's FAQ: - - - https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string - - - It's the suggested regex pattern for JavaScript. - - - This is the same pattern, made multi-line for easier readability. - - - ``` - - ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*) - - (?:-( - (?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*) - (?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)) - *))? - - (?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ - - ``` - - - The first line matches the `major.minor.patch` components of the version. The middle lines match - - the pre-release components. The last line matches the build metadata component. - resourceType.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml - title: DSC Resource fully qualified type name - description: > - The namespaced name of the DSC Resource, using the syntax: - - - owner[.group][.area]/name - - - For example: - - - Microsoft.SqlServer/Database - - Microsoft.SqlServer.Database/User - type: string - pattern: ^\w+(\.\w+){0,2}\/\w+$ - commandExecutable.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.yaml - title: Executable Command Name - description: The name of the command to run. - type: string - commandArgs.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.yaml - title: Executable Command Arguments - description: The list of arguments to pass to the command. - type: array - items: - type: string - inputKind.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.yaml - title: Executable Command Input Type - description: Defines how DSC should pass input to the command, either as arguments or JSON over stdin. - type: string - enum: - - args - - stdin - default: args - returnKind.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.yaml - title: Return Kind - type: string - enum: - - state - - stateAndDiff - default: state - $comment: >- - While the enumeration for return kind is the same for the `set` and `test` - - method, the way it changes the behavior of the command isn't. The description - - keyword isn't included here because the respective schemas for those methods - - document the behavior themselves. - resource: - manifest.get.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.yaml - title: Get Method - description: Defines how DSC must call the DSC Resource to get the current state of an instance. - type: object - required: - - executable - properties: - executable: - $ref: '#/$defs/dsc/2023/07/definitions/commandExecutable.yaml' - args: - $ref: '#/$defs/dsc/2023/07/definitions/commandArgs.yaml' - input: - $ref: '#/$defs/dsc/2023/07/definitions/inputKind.yaml' - examples: - - executable: registry - args: - - config - - get - input: stdin - - executable: osinfo - manifest.set.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.yaml - title: Set Method - description: Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource. - type: object - required: - - executable - - input - properties: - executable: - $ref: '#/$defs/dsc/2023/07/definitions/commandExecutable.yaml' - args: - $ref: '#/$defs/dsc/2023/07/definitions/commandArgs.yaml' - input: - $ref: '#/$defs/dsc/2023/07/definitions/inputKind.yaml' - preTest: - title: Resource Performs Pre-Test - description: Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state. - type: boolean - default: false - return: - description: Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified. - $ref: '#/$defs/dsc/2023/07/definitions/returnKind.yaml' - examples: - - executable: registry - args: - - config - - set - input: stdin - preTest: true - return: state - manifest.test.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.yaml - title: Test Method - description: Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource. - type: object - required: - - executable - - input - properties: - executable: - $ref: '#/$defs/dsc/2023/07/definitions/commandExecutable.yaml' - args: - $ref: '#/$defs/dsc/2023/07/definitions/commandArgs.yaml' - input: - $ref: '#/$defs/dsc/2023/07/definitions/inputKind.yaml' - return: - title: Test Command Return Type - description: Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state. - $ref: '#/$defs/dsc/2023/07/definitions/returnKind.yaml' - examples: - - executable: registry - args: - - config - - test - input: stdin - return: state - manifest.validate.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.yaml - title: Validate Method - description: Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources. - type: object - required: - - executable - properties: - executable: - $ref: '#/$defs/dsc/2023/07/definitions/commandExecutable.yaml' - args: - $ref: '#/$defs/dsc/2023/07/definitions/commandArgs.yaml' - examples: - - executable: dsc - args: - - config - - validate - manifest.provider.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.yaml - title: Provider - description: Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to manage resources that don't have their own manifests with DSC. - type: object - required: - - list - - config - properties: - list: - title: List Command - description: Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources. - type: object - required: - - executable - properties: - executable: - $ref: '#/$defs/dsc/2023/07/definitions/commandExecutable.yaml' - args: - $ref: '#/$defs/dsc/2023/07/definitions/commandArgs.yaml' - config: - title: Expected Configuration - description: Defines whether the provider expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations. - type: string - enum: - - full - - sequence - examples: - - config: full - list: - executable: pwsh - args: - - -NoLogo - - -NonInteractive - - -NoProfile - - -Command - - ./powershellgroup.resource.ps1 List - manifest.schema.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.yaml - title: Instance Schema - description: Defines how DSC must validate a JSON blob representing an instance of the DSC Resource. - type: object - oneOf: - - required: - - command - - required: - - embedded - properties: - command: - title: Instance Schema Command - description: Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource. - type: object - required: - - executable - properties: - executable: - $ref: '#/$defs/dsc/2023/07/definitions/commandExecutable.yaml' - args: - $ref: '#/$defs/dsc/2023/07/definitions/commandArgs.yaml' - embedded: - title: Embedded Instance Schema - description: Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource. - type: object - required: - - $schema - - type - - properties - properties: - type: - title: Instance Type - description: Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type. - const: object - $schema: - title: DSC Resource instance schema dialect - description: Defines which dialect of JSON Schema the DSC Resource is using to validate instances. - type: string - format: uri-reference - enum: - - https://json-schema.org/draft/2020-12/schema - - https://json-schema.org/draft/2019-09/schema - - http://json-schema.org/draft-07/schema# - $id: - title: DSC Resource instance schema ID - description: Defines the unique ID for the DSC Resource's instance schema. - type: string - format: uri-reference - properties: - title: Instance Properties - description: Defines the schema for the DSC Resource's properties. Must define at least one property. - type: object - minProperties: 1 - unevaluatedProperties: - anyOf: - - $ref: https://json-schema.org/draft/2020-12/schema - - $ref: https://json-schema.org/draft/2019-09/schema - - $ref: http://json-schema.org/draft-07/schema# - properties: - _ensure: - title: 'Standard Property: _ensure' - description: Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums. - const: - $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.yaml - _inDesiredState: - title: 'Standard Property: _inDesiredState' - description: Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing. - const: - $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.yaml - _purge: - title: 'Standard Property: _purge' - description: Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values. - const: - $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.yaml - _rebootRequested: - title: 'Standard property: _rebootRequested' - description: Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes. - const: - $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.yaml - url: - title: Instance Schema URL - description: Defines the URL to the DSC Resource's JSON schema for integrating tools. - type: string - format: uri - examples: - - command: - executable: registry - args: - - schema - - embedded: - $schema: http://json-schema.org/draft-07/schema# - title: OSInfo - type: object - required: [] - properties: - $id: - type: string - architecture: - type: - - string - - "null" - bitness: - $ref: '#/definitions/Bitness' - codename: - type: - - string - - "null" - edition: - type: - - string - - "null" - family: - $ref: '#/definitions/Family' - version: - type: string - additionalProperties: false - definitions: - Bitness: - type: string - enum: - - "32" - - "64" - - unknown - Family: - type: string - enum: - - Linux - - macOS - - Windows diff --git a/docs/schemas/bundled/resource.manifest.yaml b/docs/schemas/bundled/resource.manifest.yaml deleted file mode 100644 index fff419b56..000000000 --- a/docs/schemas/bundled/resource.manifest.yaml +++ /dev/null @@ -1,463 +0,0 @@ -$schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/bundled/resource.manifest.yaml -title: Command-based DSC Resource Manifest -description: Defines a valid command-based DSC Resource. -type: object -required: -- manifestVersion -- type -- version -- get -properties: - manifestVersion: - title: Manifest Version - description: The semver of the DSC Resource manifest schema to validate this manifest with. - $ref: /dsc/2023/07/definitions/semver.yaml - enums: - - "1.0" - type: - $ref: /dsc/2023/07/definitions/resourceType.yaml - version: - title: Resource Semantic Version - description: The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages. - $ref: /dsc/2023/07/definitions/semver.yaml - description: - title: Resource Description - description: A short synopsis of the DSC Resource's purpose. - type: string - tags: - title: Tags - description: An array of short strings used to search for DSC Resources. - type: array - uniqueItems: true - items: - type: string - pattern: ^\w+$ - get: - $ref: /dsc/2023/07/resource/manifest.get.yaml - set: - $ref: /dsc/2023/07/resource/manifest.set.yaml - test: - $ref: /dsc/2023/07/resource/manifest.test.yaml - validate: - $ref: /dsc/2023/07/resource/manifest.validate.yaml - provider: - $ref: /dsc/2023/07/resource/manifest.provider.yaml - exitCodes: - title: Exit Codes - description: This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes. - type: object - propertyNames: - pattern: ^[0-9]+$ - patternProperties: - ^[0-9]+$: - type: string - examples: - - exitCodes: - "0": Success - "1": Invalid parameter - "2": Invalid input - "3": Registry error - "4": JSON serialization failed - schema: - $ref: /dsc/2023/07/resource/manifest.schema.yaml -$defs: - https://schemas.microsoft.com/dsc/2023/07/definitions/semver.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/semver.yaml - type: string - title: Semantic Version - description: A valid semantic version (semver) string. For reference, see https://semver.org/ - pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ - $comment: > - This pattern comes from the semver website's FAQ: - - - https://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string - - - It's the suggested regex pattern for JavaScript. - - - This is the same pattern, made multi-line for easier readability. - - - ``` - - ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*) - - (?:-( - (?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*) - (?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)) - *))? - - (?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ - - ``` - - - The first line matches the `major.minor.patch` components of the version. The middle lines match - - the pre-release components. The last line matches the build metadata component. - https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml - title: DSC Resource fully qualified type name - description: > - The namespaced name of the DSC Resource, using the syntax: - - - owner[.group][.area]/name - - - For example: - - - Microsoft.SqlServer/Database - - Microsoft.SqlServer.Database/User - type: string - pattern: ^\w+(\.\w+){0,2}\/\w+$ - https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.yaml - title: Get Method - description: Defines how DSC must call the DSC Resource to get the current state of an instance. - type: object - required: - - executable - properties: - executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml - args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml - input: - $ref: /dsc/2023/07/definitions/inputKind.yaml - examples: - - executable: registry - args: - - config - - get - input: stdin - - executable: osinfo - https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.yaml - title: Set Method - description: Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource. - type: object - required: - - executable - - input - properties: - executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml - args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml - input: - $ref: /dsc/2023/07/definitions/inputKind.yaml - preTest: - title: Resource Performs Pre-Test - description: Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state. - type: boolean - default: false - return: - description: Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified. - $ref: /dsc/2023/07/definitions/returnKind.yaml - examples: - - executable: registry - args: - - config - - set - input: stdin - preTest: true - return: state - https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.yaml - title: Test Method - description: Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource. - type: object - required: - - executable - - input - properties: - executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml - args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml - input: - $ref: /dsc/2023/07/definitions/inputKind.yaml - return: - title: Test Command Return Type - description: Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state. - $ref: /dsc/2023/07/definitions/returnKind.yaml - examples: - - executable: registry - args: - - config - - test - input: stdin - return: state - https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.yaml - title: Validate Method - description: Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources. - type: object - required: - - executable - properties: - executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml - args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml - examples: - - executable: dsc - args: - - config - - validate - https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.yaml - title: Provider - description: Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to manage resources that don't have their own manifests with DSC. - type: object - required: - - list - - config - properties: - list: - title: List Command - description: Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources. - type: object - required: - - executable - properties: - executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml - args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml - config: - title: Expected Configuration - description: Defines whether the provider expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations. - type: string - enum: - - full - - sequence - examples: - - config: full - list: - executable: pwsh - args: - - -NoLogo - - -NonInteractive - - -NoProfile - - -Command - - ./powershellgroup.resource.ps1 List - https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.yaml - title: Instance Schema - description: Defines how DSC must validate a JSON blob representing an instance of the DSC Resource. - type: object - oneOf: - - required: - - command - - required: - - embedded - properties: - command: - title: Instance Schema Command - description: Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource. - type: object - required: - - executable - properties: - executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml - args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml - embedded: - title: Embedded Instance Schema - description: Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource. - type: object - required: - - $schema - - type - - properties - properties: - type: - title: Instance Type - description: Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type. - const: object - $schema: - title: DSC Resource instance schema dialect - description: Defines which dialect of JSON Schema the DSC Resource is using to validate instances. - type: string - format: uri-reference - enum: - - https://json-schema.org/draft/2020-12/schema - - https://json-schema.org/draft/2019-09/schema - - http://json-schema.org/draft-07/schema# - $id: - title: DSC Resource instance schema ID - description: Defines the unique ID for the DSC Resource's instance schema. - type: string - format: uri-reference - properties: - title: Instance Properties - description: Defines the schema for the DSC Resource's properties. Must define at least one property. - type: object - minProperties: 1 - unevaluatedProperties: - anyOf: - - $ref: https://json-schema.org/draft/2020-12/schema - - $ref: https://json-schema.org/draft/2019-09/schema - - $ref: http://json-schema.org/draft-07/schema# - properties: - _ensure: - title: 'Standard Property: _ensure' - description: Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums. - const: - $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.yaml - _inDesiredState: - title: 'Standard Property: _inDesiredState' - description: Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing. - const: - $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.yaml - _purge: - title: 'Standard Property: _purge' - description: Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values. - const: - $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.yaml - _rebootRequested: - title: 'Standard property: _rebootRequested' - description: Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes. - const: - $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.yaml - url: - title: Instance Schema URL - description: Defines the URL to the DSC Resource's JSON schema for integrating tools. - type: string - format: uri - examples: - - command: - executable: registry - args: - - schema - - embedded: - $schema: http://json-schema.org/draft-07/schema# - title: OSInfo - type: object - required: [] - properties: - $id: - type: string - architecture: - type: - - string - - "null" - bitness: - $ref: '#/definitions/Bitness' - codename: - type: - - string - - "null" - edition: - type: - - string - - "null" - family: - $ref: '#/definitions/Family' - version: - type: string - additionalProperties: false - definitions: - Bitness: - type: string - enum: - - "32" - - "64" - - unknown - Family: - type: string - enum: - - Linux - - macOS - - Windows - https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.yaml - title: Executable Command Name - description: The name of the command to run. - type: string - https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.yaml - title: Executable Command Arguments - description: The list of arguments to pass to the command. - type: array - items: - type: string - https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.yaml - title: Executable Command Input Type - description: Defines how DSC should pass input to the command, either as arguments or JSON over stdin. - type: string - enum: - - args - - stdin - default: args - https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.yaml - title: Return Kind - type: string - enum: - - state - - stateAndDiff - default: state - $comment: >- - While the enumeration for return kind is the same for the `set` and `test` - - method, the way it changes the behavior of the command isn't. The description - - keyword isn't included here because the respective schemas for those methods - - document the behavior themselves. - https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.yaml - title: Ensure Existence - description: Indicates whether the DSC Resource instance should exist. - type: string - enum: - - Absent - - Present - https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.yaml - title: Instance is in the Desired State - description: Indicates whether the instance is in the desired state. This property is only returned by the `test` method. - type: - - boolean - - "null" - readOnly: true - https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.yaml - title: Purge - description: Indicates that only the components described in the DSC Resource should exist. If other components exist, the DSC Resource is out of the desired state. When enforcing desired state, the DSC Resource removes unmanaged components. - type: - - boolean - - "null" - writeOnly: true - https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.yaml: - $schema: https://json-schema.org/draft/2020-12/schema - $id: https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.yaml - title: Reboot Requested - description: Indicates that the set operation requires a reboot before it's fully complete. - type: - - boolean - - "null" - readOnly: true diff --git a/docs/schemas/outputs/config/validate.yaml b/docs/schemas/outputs/config/validate.yaml deleted file mode 100644 index 1e5108d35..000000000 --- a/docs/schemas/outputs/config/validate.yaml +++ /dev/null @@ -1,13 +0,0 @@ -# yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema -$schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/results/config/validate.yaml - -$comment: | - Not implemented yet. - -title: DSC Resource schema result -description: >- - Describes the return data for a DSC Resource from the `dsc config validate` - command. - -type: object diff --git a/schemas/2023/08/bundled/config/document.json b/schemas/2023/08/bundled/config/document.json new file mode 100644 index 000000000..e1d19672f --- /dev/null +++ b/schemas/2023/08/bundled/config/document.json @@ -0,0 +1,226 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", + "title": "DSC Configuration Document schema", + "description": "Describes a valid DSC Configuration Document.", + "type": "object", + "required": [ + "$schema", + "resources" + ], + "properties": { + "$schema": { + "title": "Schema", + "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "/PowerShell/DSC/main/schemas/2023/08/config/document.json" + ] + }, + "parameters": { + "title": "DSC Configuration document parameters", + "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "type": "object", + "additionalProperties": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" + } + }, + "variables": { + "title": "Configuration variables", + "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", + "type": "object" + }, + "resources": { + "title": "DSC Configuration document resources", + "description": "Defines a list of DSC Resource instances for the configuration to manage.", + "type": "array", + "minItems": 1, + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" + } + }, + "metadata": { + "title": "Configuration metadata", + "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", + "type": "object" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json", + "title": "Parameter", + "description": "Defines a runtime option for a DSC Configuration Document.", + "type": "object", + "required": "type", + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json" + }, + "defaultValue": { + "title": "Default value", + "description": "Defines the default value for the parameter.", + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" + }, + "allowedValues": { + "title": "Allowed values", + "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" + } + }, + "description": { + "title": "Parameter description", + "description": "Defines a synopsis for the parameter explaining its purpose.", + "type": "string" + }, + "metadata": { + "title": "Parameter metadata", + "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", + "type": "object" + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "minValue": { + "title": "Minimum value", + "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", + "type": "integer" + }, + "maxValue": { + "title": "Maximum value", + "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", + "type": "integer" + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + }, + { + "properties": { + "type": { + "const": "array" + } + } + } + ] + }, + "then": { + "minLength": { + "title": "Minimum length", + "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", + "type": "integer", + "minimum": 0 + }, + "maxLength": { + "title": "Maximum length", + "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", + "type": "integer", + "minimum": 0 + } + } + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json", + "title": "DSC Resource instance", + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "dependsOn": { + "title": "Instance depends on", + "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", + "type": "array", + "items": { + "type": "string", + "uniqueItems": true, + "pattern": "^\\[\\w+(\\.\\w+){0,2}\\/\\w+\\].+$" + } + }, + "properties": { + "title": "Managed instance properties", + "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", + "type": "object" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json", + "title": "Data Types", + "description": "Defines the data type for the value.", + "type": "string", + "enum": [ + "string", + "securestring", + "int", + "bool", + "object", + "secureobject", + "array" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json", + "type": [ + "string", + "integer", + "object", + "array", + "boolean" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" + } + } +} diff --git a/schemas/2023/08/bundled/config/document.vscode.json b/schemas/2023/08/bundled/config/document.vscode.json new file mode 100644 index 000000000..7335363de --- /dev/null +++ b/schemas/2023/08/bundled/config/document.vscode.json @@ -0,0 +1,244 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", + "title": "DSC Configuration Document schema", + "description": "Describes a valid DSC Configuration Document.", + "type": "object", + "required": [ + "$schema", + "resources" + ], + "properties": { + "$schema": { + "title": "Schema", + "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "/PowerShell/DSC/main/schemas/2023/08/config/document.json" + ] + }, + "parameters": { + "title": "DSC Configuration document parameters", + "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" + } + }, + "variables": { + "title": "Configuration variables", + "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", + "type": "object" + }, + "resources": { + "title": "DSC Configuration document resources", + "description": "Defines a list of DSC Resource instances for the configuration to manage.", + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" + } + }, + "metadata": { + "title": "Configuration metadata", + "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", + "type": "object" + } + }, + "$defs": { + "PowerShell": { + "DSC": { + "main": { + "schemas": { + "2023": { + "08": { + "config": { + "document.parameter.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json", + "title": "Parameter", + "description": "Defines a runtime option for a DSC Configuration Document.", + "type": "object", + "required": "type", + "properties": { + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json" + }, + "defaultValue": { + "title": "Default value", + "description": "Defines the default value for the parameter.", + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" + }, + "allowedValues": { + "title": "Allowed values", + "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" + } + }, + "description": { + "title": "Parameter description", + "description": "Defines a synopsis for the parameter explaining its purpose.", + "type": "string" + }, + "metadata": { + "title": "Parameter metadata", + "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", + "type": "object" + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "minValue": { + "title": "Minimum value", + "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", + "type": "integer" + }, + "maxValue": { + "title": "Maximum value", + "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", + "type": "integer" + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + }, + { + "properties": { + "type": { + "const": "array" + } + } + } + ] + }, + "then": { + "minLength": { + "title": "Minimum length", + "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", + "type": "integer", + "minimum": 0 + }, + "maxLength": { + "title": "Maximum length", + "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", + "type": "integer", + "minimum": 0 + } + } + } + ] + }, + "document.resource.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json", + "title": "DSC Resource instance", + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "name": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "dependsOn": { + "title": "Instance depends on", + "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", + "type": "array", + "items": { + "type": "string", + "uniqueItems": true, + "pattern": "^\\[\\w+(\\.\\w+){0,2}\\/\\w+\\].+$" + } + }, + "properties": { + "title": "Managed instance properties", + "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", + "type": "object" + } + } + } + }, + "definitions": { + "parameters": { + "dataTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json", + "title": "Data Types", + "description": "Defines the data type for the value.", + "type": "string", + "enum": [ + "string", + "securestring", + "int", + "bool", + "object", + "secureobject", + "array" + ] + }, + "validValueTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json", + "type": [ + "string", + "integer", + "object", + "array", + "boolean" + ] + } + }, + "resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" + } + } + } + } + } + } + } + } + } +} diff --git a/docs/schemas/bundled/outputs.config.get.json b/schemas/2023/08/bundled/outputs/config/get.json similarity index 58% rename from docs/schemas/bundled/outputs.config.get.json rename to schemas/2023/08/bundled/outputs/config/get.json index 528ddca0a..01e7b1b2b 100644 --- a/docs/schemas/bundled/outputs.config.get.json +++ b/schemas/2023/08/bundled/outputs/config/get.json @@ -1,135 +1,118 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.config.get.json", - "title": "DSC Configuration get command result", - "description": "Represents the data structure returned by the `dsc config get` command.", - "type": "object", - "required": [ - "results", - "messages", - "hadErrors" - ], - "properties": { - "results": { - "title": "Results", - "description": "The results of the `get` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", - "type": "array", - "items": { - "title": "Get Result", - "type": "object", - "required": [ - "name", - "type", - "result" - ], - "properties": { - "name": { - "$ref": "/dsc/2023/07/definitions/instanceName.json" - }, - "type": { - "$ref": "/dsc/2023/07/definitions/resourceType.json" - }, - "result": { - "$ref": "/dsc/2023/07/results/resource/get.json" - } - } - } - }, - "messages": { - "$ref": "/dsc/2023/07/definitions/messages.json" - }, - "hadErrors": { - "$ref": "/dsc/2023/07/definitions/hadErrors.json" - } - }, - "$defs": { - "https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.json", - "title": "Instance name", - "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", - "type": "string" - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json", - "title": "DSC Resource fully qualified type name", - "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", - "type": "string", - "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" - }, - "https://schemas.microsoft.com/dsc/2023/07/results/resource/get.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/results/resource/get.json", - "title": "dsc resource get result", - "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command.", - "type": "object", - "required": [ - "actualState" - ], - "properties": { - "actualState": { - "title": "Actual state", - "description": "This property always represents the current state of the DSC Resource instance as returned by its `get` method. DSC validates this return value against the DSC Resource's schema.", - "type": "object" - } - } - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/messages.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/messages.json", - "title": "Messages", - "description": "A list of structured messages emitted by the DSC Resources during an operation.", - "type": "array", - "items": { - "$ref": "/dsc/2023/07/definitions/message.json" - } - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/hadErrors.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/hadErrors.json", - "title": "Had Errors", - "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", - "type": "boolean" - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/message.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/message.json", - "title": "Message", - "description": "A message emitted by a DSC Resource with associated metadata.", - "type": "object", - "required": [ - "name", - "type", - "message", - "level" - ], - "properties": { - "name": { - "title": "Message source instance name", - "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", - "type": "string" - }, - "type": { - "$ref": "/dsc/2023/07/definitions/resourceType.json" - }, - "message": { - "title": "Message content", - "description": "The actual content of the message as emitted by the DSC Resource.", - "type": "string", - "minLength": 1 - }, - "level": { - "title": "Message level", - "description": "Indicates the severity of the message.", - "type": "string", - "enum": [ - "Error", - "Warning", - "Information" - ] - } - } - } - } +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/get.json", + "title": "DSC Configuration get command result", + "description": "Represents the data structure returned by the `dsc config get` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `get` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "title": "Get Result", + "type": "object", + "required": [ + "name", + "type", + "result" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/get.json" + } + } + } + }, + "messages": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/message.json" + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/message.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/message.json", + "title": "Message", + "description": "A message emitted by a DSC Resource with associated metadata.", + "type": "object", + "required": [ + "name", + "type", + "message", + "level" + ], + "properties": { + "name": { + "title": "Message source instance name", + "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", + "type": "string" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "message": { + "title": "Message content", + "description": "The actual content of the message as emitted by the DSC Resource.", + "type": "string", + "minLength": 1 + }, + "level": { + "title": "Message level", + "description": "Indicates the severity of the message.", + "type": "string", + "enum": [ + "Error", + "Warning", + "Information" + ] + } + } + } + } } diff --git a/docs/schemas/bundled/outputs.config.set.json b/schemas/2023/08/bundled/outputs/config/set.json similarity index 50% rename from docs/schemas/bundled/outputs.config.set.json rename to schemas/2023/08/bundled/outputs/config/set.json index 7c3cf6b35..4cda22cb0 100644 --- a/docs/schemas/bundled/outputs.config.set.json +++ b/schemas/2023/08/bundled/outputs/config/set.json @@ -1,151 +1,118 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.config.set.json", - "title": "DSC Configuration set command result", - "description": "Represents the data structure returned by the `dsc config set` command.", - "type": "object", - "required": [ - "results", - "messages", - "hadErrors" - ], - "properties": { - "results": { - "title": "Results", - "description": "The results of the `set` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", - "type": "array", - "items": { - "title": "Set Result", - "type": "object", - "required": [ - "name", - "type", - "result" - ], - "properties": { - "name": { - "$ref": "/dsc/2023/07/definitions/instanceName.json" - }, - "type": { - "$ref": "/dsc/2023/07/definitions/resourceType.json" - }, - "result": { - "$ref": "/dsc/2023/07/results/resource/set.json" - } - } - } - }, - "messages": { - "$ref": "/dsc/2023/07/definitions/messages.json" - }, - "hadErrors": { - "$ref": "/dsc/2023/07/definitions/hadErrors.json" - } - }, - "$defs": { - "https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.json", - "title": "Instance name", - "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", - "type": "string" - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json", - "title": "DSC Resource fully qualified type name", - "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", - "type": "string", - "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" - }, - "https://schemas.microsoft.com/dsc/2023/07/results/resource/set.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/results/resource/set.json", - "title": "dsc resource set result", - "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command.", - "type": "object", - "required": [ - "beforeState", - "afterState", - "changedProperties" - ], - "properties": { - "beforeState": { - "title": "State before enforcing", - "description": "This property always represents the desired state of the DSC Resource instance before the `set` method runs. DSC validates this return value against the DSC Resource's schema.", - "type": "object" - }, - "afterState": { - "title": "State after enforcing", - "description": "This property always represents the current state of the DSC Resource instance as returned by its `set` method after enforcing the desired state. DSC validates this return value against the DSC Resource's schema.", - "type": "object" - }, - "changedProperties": { - "title": "Changed properties", - "description": "This property always represents the list of property names for the DSC Resource instance that the `set` method modified. When this value is an empty array, the `set` method didn't enforce any properties for the instance.", - "type": "array", - "default": [], - "items": { - "type": "string" - } - } - } - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/messages.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/messages.json", - "title": "Messages", - "description": "A list of structured messages emitted by the DSC Resources during an operation.", - "type": "array", - "items": { - "$ref": "/dsc/2023/07/definitions/message.json" - } - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/hadErrors.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/hadErrors.json", - "title": "Had Errors", - "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", - "type": "boolean" - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/message.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/message.json", - "title": "Message", - "description": "A message emitted by a DSC Resource with associated metadata.", - "type": "object", - "required": [ - "name", - "type", - "message", - "level" - ], - "properties": { - "name": { - "title": "Message source instance name", - "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", - "type": "string" - }, - "type": { - "$ref": "/dsc/2023/07/definitions/resourceType.json" - }, - "message": { - "title": "Message content", - "description": "The actual content of the message as emitted by the DSC Resource.", - "type": "string", - "minLength": 1 - }, - "level": { - "title": "Message level", - "description": "Indicates the severity of the message.", - "type": "string", - "enum": [ - "Error", - "Warning", - "Information" - ] - } - } - } - } +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/set.json", + "title": "DSC Configuration set command result", + "description": "Represents the data structure returned by the `dsc config set` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `set` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "title": "Set Result", + "type": "object", + "required": [ + "name", + "type", + "result" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/set.json" + } + } + } + }, + "messages": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/message.json" + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/message.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/message.json", + "title": "Message", + "description": "A message emitted by a DSC Resource with associated metadata.", + "type": "object", + "required": [ + "name", + "type", + "message", + "level" + ], + "properties": { + "name": { + "title": "Message source instance name", + "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", + "type": "string" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "message": { + "title": "Message content", + "description": "The actual content of the message as emitted by the DSC Resource.", + "type": "string", + "minLength": 1 + }, + "level": { + "title": "Message level", + "description": "Indicates the severity of the message.", + "type": "string", + "enum": [ + "Error", + "Warning", + "Information" + ] + } + } + } + } } diff --git a/schemas/2023/08/bundled/outputs/config/test.json b/schemas/2023/08/bundled/outputs/config/test.json new file mode 100644 index 000000000..6c74c6720 --- /dev/null +++ b/schemas/2023/08/bundled/outputs/config/test.json @@ -0,0 +1,118 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/test.json", + "title": "DSC Configuration test command result", + "description": "Represents the data structure returned by the `dsc config test` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `test` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "title": "Test Result", + "type": "object", + "required": [ + "name", + "type", + "result" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/test.json" + } + } + } + }, + "messages": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/message.json" + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/message.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/message.json", + "title": "Message", + "description": "A message emitted by a DSC Resource with associated metadata.", + "type": "object", + "required": [ + "name", + "type", + "message", + "level" + ], + "properties": { + "name": { + "title": "Message source instance name", + "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", + "type": "string" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "message": { + "title": "Message content", + "description": "The actual content of the message as emitted by the DSC Resource.", + "type": "string", + "minLength": 1 + }, + "level": { + "title": "Message level", + "description": "Indicates the severity of the message.", + "type": "string", + "enum": [ + "Error", + "Warning", + "Information" + ] + } + } + } + } +} diff --git a/docs/schemas/bundled/outputs.resource.get.json b/schemas/2023/08/bundled/outputs/resource/get.json similarity index 84% rename from docs/schemas/bundled/outputs.resource.get.json rename to schemas/2023/08/bundled/outputs/resource/get.json index 57986c4e6..8ed6684d9 100644 --- a/docs/schemas/bundled/outputs.resource.get.json +++ b/schemas/2023/08/bundled/outputs/resource/get.json @@ -1,18 +1,18 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.resource.get.json", - "title": "dsc resource get result", - "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command.", - "type": "object", - "required": [ - "actualState" - ], - "properties": { - "actualState": { - "title": "Actual state", - "description": "This property always represents the current state of the DSC Resource instance as returned by its `get` method. DSC validates this return value against the DSC Resource's schema.", - "type": "object" - } - }, - "$defs": {} +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/get.json", + "title": "dsc resource get result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command.", + "type": "object", + "required": [ + "actualState" + ], + "properties": { + "actualState": { + "title": "Actual state", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + } + }, + "$defs": {} } diff --git a/docs/schemas/bundled/outputs.resource.list.json b/schemas/2023/08/bundled/outputs/resource/list.json similarity index 60% rename from docs/schemas/bundled/outputs.resource.list.json rename to schemas/2023/08/bundled/outputs/resource/list.json index 0e5c23c4e..18cd2107d 100644 --- a/docs/schemas/bundled/outputs.resource.list.json +++ b/schemas/2023/08/bundled/outputs/resource/list.json @@ -1,674 +1,518 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.resource.list.json", - "title": "dsc resource list result", - "description": "Describes the return data for a DSC Resource instance from the `dsc resource list` command.", - "type": "object", - "properties": { - "type": { - "$ref": "/dsc/2023/07/definitions/resourceType.json" - }, - "version": { - "$ref": "/dsc/2023/07/definitions/semver.json" - }, - "description": { - "title": "Resource Description", - "description": "A short synopsis of the DSC Resource's purpose.", - "type": "string" - }, - "path": { - "title": "Path", - "description": "Indicates the path to the DSC Resource on the file system.", - "type": "string" - }, - "directory": { - "title": "Directory", - "description": "Indicates the path to the folder containing the DSC Resource on the file system.", - "type": "string" - }, - "implementedAs": { - "title": "Implemented as", - "description": "Indicates how the DSC Resource was implemented. To specify a custom implementation, specify this value as an object with the `custom` property.", - "oneOf": [ - { - "title": "Standard implementation", - "description": "Indicates that the DSC Resource is implemented as one of the standard implementations built into DSC.", - "type": "string", - "enum": [ - "Command" - ] - }, - { - "title": "Custom implementation", - "description": "Indicates that the DSC Resource uses a custom implementation.", - "type": "object", - "required": [ - "custom" - ], - "properties": { - "custom": { - "title": "Custom implementation name", - "description": "The name of the custom implementation.", - "type": "string" - } - } - } - ] - }, - "author": { - "title": "Author", - "description": "Indicates the name of the person or organization that developed and maintains the DSC Resource.", - "type": [ - "string", - "null" - ] - }, - "properties": { - "title": "Properties", - "description": "Defines the DSC Resource's property names.", - "type": "array", - "items": { - "type": "string", - "pattern": "^\\w+$" - } - }, - "requires": { - "title": "Required DSC Resource Provider", - "description": "Defines the fully qualified type name of the DSC Resource Provider the DSC Resource depends on.", - "oneOf": [ - { - "$ref": "/dsc/2023/07/definitions/resourceType.json" - }, - { - "type": "null" - } - ] - }, - "manifest": { - "$ref": "/dsc/2023/07/resource/manifest.json" - } - }, - "$defs": { - "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json", - "title": "DSC Resource fully qualified type name", - "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", - "type": "string", - "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/semver.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/semver.json", - "type": "string", - "title": "Semantic Version", - "description": "A valid semantic version (semver) string. For reference, see https://semver.org/", - "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", - "$comment": "This pattern comes from the semver website's FAQ:\n\nhttps://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n\nIt's the suggested regex pattern for JavaScript.\n\nThis is the same pattern, made multi-line for easier readability.\n\n```\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n" - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.json", - "title": "Command-based DSC Resource Manifest", - "description": "Defines a valid command-based DSC Resource.", - "type": "object", - "required": [ - "manifestVersion", - "type", - "version", - "get" - ], - "properties": { - "manifestVersion": { - "title": "Manifest Version", - "description": "The semver of the DSC Resource manifest schema to validate this manifest with.", - "$ref": "/dsc/2023/07/definitions/semver.json", - "enums": [ - "1.0" - ] - }, - "type": { - "$ref": "/dsc/2023/07/definitions/resourceType.json" - }, - "version": { - "title": "Resource Semantic Version", - "description": "The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages.", - "$ref": "/dsc/2023/07/definitions/semver.json" - }, - "description": { - "title": "Resource Description", - "description": "A short synopsis of the DSC Resource's purpose.", - "type": "string" - }, - "tags": { - "title": "Tags", - "description": "An array of short strings used to search for DSC Resources.", - "type": "array", - "uniqueItems": true, - "items": { - "type": "string", - "pattern": "^\\w+$" - } - }, - "get": { - "$ref": "/dsc/2023/07/resource/manifest.get.json" - }, - "set": { - "$ref": "/dsc/2023/07/resource/manifest.set.json" - }, - "test": { - "$ref": "/dsc/2023/07/resource/manifest.test.json" - }, - "validate": { - "$ref": "/dsc/2023/07/resource/manifest.validate.json" - }, - "provider": { - "$ref": "/dsc/2023/07/resource/manifest.provider.json" - }, - "exitCodes": { - "title": "Exit Codes", - "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", - "type": "object", - "propertyNames": { - "pattern": "^[0-9]+$" - }, - "patternProperties": { - "^[0-9]+$": { - "type": "string" - } - }, - "examples": [ - { - "exitCodes": { - "0": "Success", - "1": "Invalid parameter", - "2": "Invalid input", - "3": "Registry error", - "4": "JSON serialization failed" - } - } - ] - }, - "schema": { - "$ref": "/dsc/2023/07/resource/manifest.schema.json" - } - } - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.json", - "title": "Get Method", - "description": "Defines how DSC must call the DSC Resource to get the current state of an instance.", - "type": "object", - "required": [ - "executable" - ], - "properties": { - "executable": { - "$ref": "/dsc/2023/07/definitions/commandExecutable.json" - }, - "args": { - "$ref": "/dsc/2023/07/definitions/commandArgs.json" - }, - "input": { - "$ref": "/dsc/2023/07/definitions/inputKind.json" - } - }, - "examples": [ - { - "executable": "registry", - "args": [ - "config", - "get" - ], - "input": "stdin" - }, - { - "executable": "osinfo" - } - ] - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.json", - "title": "Set Method", - "description": "Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource.", - "type": "object", - "required": [ - "executable", - "input" - ], - "properties": { - "executable": { - "$ref": "/dsc/2023/07/definitions/commandExecutable.json" - }, - "args": { - "$ref": "/dsc/2023/07/definitions/commandArgs.json" - }, - "input": { - "$ref": "/dsc/2023/07/definitions/inputKind.json" - }, - "preTest": { - "title": "Resource Performs Pre-Test", - "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", - "type": "boolean", - "default": false - }, - "return": { - "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", - "$ref": "/dsc/2023/07/definitions/returnKind.json" - } - }, - "examples": [ - { - "executable": "registry", - "args": [ - "config", - "set" - ], - "input": "stdin", - "preTest": true, - "return": "state" - } - ] - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.json", - "title": "Test Method", - "description": "Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource.", - "type": "object", - "required": [ - "executable", - "input" - ], - "properties": { - "executable": { - "$ref": "/dsc/2023/07/definitions/commandExecutable.json" - }, - "args": { - "$ref": "/dsc/2023/07/definitions/commandArgs.json" - }, - "input": { - "$ref": "/dsc/2023/07/definitions/inputKind.json" - }, - "return": { - "title": "Test Command Return Type", - "description": "Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state.", - "$ref": "/dsc/2023/07/definitions/returnKind.json" - } - }, - "examples": [ - { - "executable": "registry", - "args": [ - "config", - "test" - ], - "input": "stdin", - "return": "state" - } - ] - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.json", - "title": "Validate Method", - "description": "Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources.", - "type": "object", - "required": [ - "executable" - ], - "properties": { - "executable": { - "$ref": "/dsc/2023/07/definitions/commandExecutable.json" - }, - "args": { - "$ref": "/dsc/2023/07/definitions/commandArgs.json" - } - }, - "examples": [ - { - "executable": "dsc", - "args": [ - "config", - "validate" - ] - } - ] - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.json", - "title": "Provider", - "description": "Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to manage resources that don't have their own manifests with DSC.", - "type": "object", - "required": [ - "list", - "config" - ], - "properties": { - "list": { - "title": "List Command", - "description": "Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.", - "type": "object", - "required": [ - "executable" - ], - "properties": { - "executable": { - "$ref": "/dsc/2023/07/definitions/commandExecutable.json" - }, - "args": { - "$ref": "/dsc/2023/07/definitions/commandArgs.json" - } - } - }, - "config": { - "title": "Expected Configuration", - "description": "Defines whether the provider expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations.", - "type": "string", - "enum": [ - "full", - "sequence" - ] - } - }, - "examples": [ - { - "config": "full", - "list": { - "executable": "pwsh", - "args": [ - "-NoLogo", - "-NonInteractive", - "-NoProfile", - "-Command", - "./powershellgroup.resource.ps1 List" - ] - } - } - ] - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.json", - "title": "Instance Schema", - "description": "Defines how DSC must validate a JSON blob representing an instance of the DSC Resource.", - "type": "object", - "oneOf": [ - { - "required": [ - "command" - ] - }, - { - "required": [ - "embedded" - ] - } - ], - "properties": { - "command": { - "title": "Instance Schema Command", - "description": "Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource.", - "type": "object", - "required": [ - "executable" - ], - "properties": { - "executable": { - "$ref": "/dsc/2023/07/definitions/commandExecutable.json" - }, - "args": { - "$ref": "/dsc/2023/07/definitions/commandArgs.json" - } - } - }, - "embedded": { - "title": "Embedded Instance Schema", - "description": "Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource.", - "type": "object", - "required": [ - "$schema", - "type", - "properties" - ], - "properties": { - "type": { - "title": "Instance Type", - "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", - "const": "object" - }, - "$schema": { - "title": "DSC Resource instance schema dialect", - "description": "Defines which dialect of JSON Schema the DSC Resource is using to validate instances.", - "type": "string", - "format": "uri-reference", - "enum": [ - "https://json-schema.org/draft/2020-12/schema", - "https://json-schema.org/draft/2019-09/schema", - "http://json-schema.org/draft-07/schema#" - ] - }, - "$id": { - "title": "DSC Resource instance schema ID", - "description": "Defines the unique ID for the DSC Resource's instance schema.", - "type": "string", - "format": "uri-reference" - }, - "properties": { - "title": "Instance Properties", - "description": "Defines the schema for the DSC Resource's properties. Must define at least one property.", - "type": "object", - "minProperties": 1, - "unevaluatedProperties": { - "anyOf": [ - { - "$ref": "https://json-schema.org/draft/2020-12/schema" - }, - { - "$ref": "https://json-schema.org/draft/2019-09/schema" - }, - { - "$ref": "http://json-schema.org/draft-07/schema#" - } - ] - }, - "properties": { - "_ensure": { - "title": "Standard Property: _ensure", - "description": "Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums.", - "const": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json" - } - }, - "_inDesiredState": { - "title": "Standard Property: _inDesiredState", - "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", - "const": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json" - } - }, - "_purge": { - "title": "Standard Property: _purge", - "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", - "const": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json" - } - }, - "_rebootRequested": { - "title": "Standard property: _rebootRequested", - "description": "Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes.", - "const": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json" - } - } - } - } - } - }, - "url": { - "title": "Instance Schema URL", - "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", - "type": "string", - "format": "uri" - } - }, - "examples": [ - { - "command": { - "executable": "registry", - "args": [ - "schema" - ] - } - }, - { - "embedded": { - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "OSInfo", - "type": "object", - "required": [], - "properties": { - "$id": { - "type": "string" - }, - "architecture": { - "type": [ - "string", - "null" - ] - }, - "bitness": { - "$ref": "#/definitions/Bitness" - }, - "codename": { - "type": [ - "string", - "null" - ] - }, - "edition": { - "type": [ - "string", - "null" - ] - }, - "family": { - "$ref": "#/definitions/Family" - }, - "version": { - "type": "string" - } - }, - "additionalProperties": false, - "definitions": { - "Bitness": { - "type": "string", - "enum": [ - "32", - "64", - "unknown" - ] - }, - "Family": { - "type": "string", - "enum": [ - "Linux", - "macOS", - "Windows" - ] - } - } - } - } - ] - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.json", - "title": "Executable Command Name", - "description": "The name of the command to run.", - "type": "string" - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.json", - "title": "Executable Command Arguments", - "description": "The list of arguments to pass to the command.", - "type": "array", - "items": { - "type": "string" - } - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.json", - "title": "Executable Command Input Type", - "description": "Defines how DSC should pass input to the command, either as arguments or JSON over stdin.", - "type": "string", - "enum": [ - "args", - "stdin" - ], - "default": "args" - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.json", - "title": "Return Kind", - "type": "string", - "enum": [ - "state", - "stateAndDiff" - ], - "default": "state", - "$comment": "While the enumeration for return kind is the same for the `set` and `test`\nmethod, the way it changes the behavior of the command isn't. The description\nkeyword isn't included here because the respective schemas for those methods\ndocument the behavior themselves." - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json", - "title": "Ensure Existence", - "description": "Indicates whether the DSC Resource instance should exist.", - "type": "string", - "enum": [ - "Absent", - "Present" - ] - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json", - "title": "Instance is in the Desired State", - "description": "Indicates whether the instance is in the desired state. This property is only returned by the `test` method.", - "type": [ - "boolean", - "null" - ], - "readOnly": true - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json", - "title": "Purge", - "description": "Indicates that only the components described in the DSC Resource should exist. If other components exist, the DSC Resource is out of the desired state. When enforcing desired state, the DSC Resource removes unmanaged components.", - "type": [ - "boolean", - "null" - ], - "writeOnly": true - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json", - "title": "Reboot Requested", - "description": "Indicates that the set operation requires a reboot before it's fully complete.", - "type": [ - "boolean", - "null" - ], - "readOnly": true - } - } +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/list.json", + "title": "dsc resource list result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource list` command.", + "type": "object", + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "version": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "path": { + "title": "Path", + "description": "Indicates the path to the DSC Resource on the file system.", + "type": "string" + }, + "directory": { + "title": "Directory", + "description": "Indicates the path to the folder containing the DSC Resource on the file system.", + "type": "string" + }, + "implementedAs": { + "title": "Implemented as", + "description": "Indicates how the DSC Resource was implemented.", + "oneOf": [ + { + "title": "Standard implementation", + "description": "Indicates that the DSC Resource is implemented as one of the standard implementations built into DSC.", + "type": "string", + "enum": [ + "Command" + ] + }, + { + "title": "Custom implementation", + "description": "Indicates that the DSC Resource uses a custom implementation.", + "type": "object", + "required": [ + "custom" + ], + "properties": { + "custom": { + "title": "Custom implementation name", + "description": "The name of the custom implementation.", + "type": "string" + } + } + } + ] + }, + "author": { + "title": "Author", + "description": "Indicates the name of the person or organization that developed and maintains the DSC Resource.", + "type": [ + "string", + "null" + ] + }, + "properties": { + "title": "Properties", + "description": "Defines the DSC Resource's property names.", + "type": "array", + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "requires": { + "title": "Required DSC Resource Provider", + "description": "Defines the fully qualified type name of the DSC Resource Provider the DSC Resource depends on.", + "oneOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + { + "type": "null" + } + ] + }, + "manifest": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "type": "string", + "title": "Semantic Version", + "description": "A valid semantic version (semver) string. For reference, see https://semver.org/", + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json", + "title": "Command-based DSC Resource Manifest", + "description": "Defines a valid command-based DSC Resource.", + "type": "object", + "required": [ + "manifestVersion", + "type", + "version", + "get" + ], + "properties": { + "manifestVersion": { + "title": "Manifest Version", + "description": "The semver of the DSC Resource manifest schema to validate this manifest with.", + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "enums": "1.0" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "version": { + "title": "Resource Semantic Version", + "description": "The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages.", + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "tags": { + "title": "Tags", + "description": "An array of short strings used to search for DSC Resources.", + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "get": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json" + }, + "set": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json" + }, + "test": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json" + }, + "validate": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json" + }, + "provider": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json" + }, + "exitCodes": { + "title": "Exit Codes", + "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", + "type": "object", + "propertyNames": { + "pattern": "^[0-9]+$" + }, + "patternProperties": { + "^[0-9]+$": { + "type": "string" + } + } + }, + "schema": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json", + "title": "Get Method", + "description": "Defines how DSC must call the DSC Resource to get the current state of an instance.", + "type": "object", + "required": "executable", + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json", + "title": "Set Method", + "description": "Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + }, + "preTest": { + "title": "Resource Performs Pre-Test", + "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", + "type": "boolean", + "default": false + }, + "return": { + "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json", + "title": "Test Method", + "description": "Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + }, + "return": { + "title": "Test Command Return Type", + "description": "Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state.", + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json", + "title": "Validate Method", + "description": "Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources.", + "type": "object", + "required": "executable", + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json", + "title": "Provider", + "description": "Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to manage resources that don't have their own manifests with DSC.", + "type": "object", + "required": [ + "list", + "config" + ], + "properties": { + "list": { + "title": "List Command", + "description": "Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.", + "type": "object", + "required": "executable", + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "config": { + "title": "Expected Configuration", + "description": "Defines whether the provider expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations.", + "type": "string", + "enum": [ + "full", + "sequence" + ] + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json", + "title": "Instance Schema", + "description": "Defines how DSC must validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "oneOf": [ + { + "required": "command" + }, + { + "required": "embedded" + } + ], + "properties": { + "command": { + "title": "Instance Schema Command", + "description": "Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": "executable", + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "embedded": { + "title": "Embedded Instance Schema", + "description": "Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": [ + "$schema", + "type", + "properties" + ], + "properties": { + "type": { + "title": "Instance Type", + "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", + "const": "object" + }, + "$schema": { + "title": "DSC Resource instance schema dialect", + "description": "Defines which dialect of JSON Schema the DSC Resource is using to validate instances.", + "type": "string", + "format": "uri-reference", + "enum": [ + "https://json-schema.org/draft/2020-12/schema", + "https://json-schema.org/draft/2019-09/schema", + "http://json-schema.org/draft-07/schema#" + ] + }, + "$id": { + "title": "DSC Resource instance schema ID", + "description": "Defines the unique ID for the DSC Resource's instance schema.", + "type": "string", + "format": "uri-reference" + }, + "properties": { + "title": "Instance Properties", + "description": "Defines the schema for the DSC Resource's properties. Must define at least one property.", + "type": "object", + "minProperties": 1, + "unevaluatedProperties": { + "anyOf": [ + { + "$ref": "https://json-schema.org/draft/2020-12/schema" + }, + { + "$ref": "https://json-schema.org/draft/2019-09/schema" + }, + { + "$ref": "http://json-schema.org/draft-07/schema#" + } + ] + }, + "properties": { + "_ensure": { + "title": "Standard Property: _ensure", + "description": "Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json" + } + }, + "_inDesiredState": { + "title": "Standard Property: _inDesiredState", + "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json" + } + }, + "_purge": { + "title": "Standard Property: _purge", + "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json" + } + }, + "_rebootRequested": { + "title": "Standard property: _rebootRequested", + "description": "Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" + } + } + } + } + } + }, + "url": { + "title": "Instance Schema URL", + "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", + "type": "string", + "format": "uri" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "title": "Executable Command Name", + "description": "The name of the command to run.", + "type": "string" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "title": "Executable Command Arguments", + "description": "The list of arguments to pass to the command.", + "type": "array", + "items": { + "type": "string" + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", + "title": "Executable Command Input Type", + "description": "Defines how DSC should pass input to the command, either as arguments or JSON over stdin.", + "type": "string", + "enum": [ + "args", + "stdin" + ], + "default": "args" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json", + "title": "Return Kind", + "type": "string", + "enum": [ + "state", + "stateAndDiff" + ], + "default": "state" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json", + "title": "Ensure Existence", + "description": "Indicates whether the DSC Resource instance should exist.", + "type": "string", + "enum": [ + "Absent", + "Present" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json", + "title": "Instance is in the Desired State", + "description": "Indicates whether the instance is in the desired state. This property is only returned by the `test` method.", + "type": [ + "boolean", + "null" + ], + "readOnly": true + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json", + "title": "Purge", + "description": "Indicates that only the components described in the DSC Resource should exist. If other components exist, the DSC Resource is out of the desired state. When enforcing desired state, the DSC Resource removes unmanaged components.", + "type": [ + "boolean", + "null" + ], + "writeOnly": true + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json", + "title": "Reboot Requested", + "description": "Indicates that the set operation requires a reboot before it's fully complete.", + "type": [ + "boolean", + "null" + ], + "readOnly": true + } + } } diff --git a/docs/schemas/bundled/outputs.resource.schema.json b/schemas/2023/08/bundled/outputs/resource/schema.json similarity index 73% rename from docs/schemas/bundled/outputs.resource.schema.json rename to schemas/2023/08/bundled/outputs/resource/schema.json index 0978bbf4d..dbe44ccd9 100644 --- a/docs/schemas/bundled/outputs.resource.schema.json +++ b/schemas/2023/08/bundled/outputs/resource/schema.json @@ -1,8 +1,8 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.resource.schema.json", - "title": "DSC Resource schema result", - "description": "Describes the return data for a DSC Resource from the `dsc resource schema` command. This command always returns the DSC Resource's JSON schema document.", - "type": "object", - "$defs": {} +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/schema.json", + "title": "DSC Resource schema result", + "description": "Describes the return data for a DSC Resource from the `dsc resource schema` command. This command always returns the DSC Resource's JSON schema document.", + "type": "object", + "$defs": {} } diff --git a/docs/schemas/bundled/outputs.resource.set.json b/schemas/2023/08/bundled/outputs/resource/set.json similarity index 91% rename from docs/schemas/bundled/outputs.resource.set.json rename to schemas/2023/08/bundled/outputs/resource/set.json index 9863e4551..c6b67bf1a 100644 --- a/docs/schemas/bundled/outputs.resource.set.json +++ b/schemas/2023/08/bundled/outputs/resource/set.json @@ -1,34 +1,34 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.resource.set.json", - "title": "dsc resource set result", - "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command.", - "type": "object", - "required": [ - "beforeState", - "afterState", - "changedProperties" - ], - "properties": { - "beforeState": { - "title": "State before enforcing", - "description": "This property always represents the desired state of the DSC Resource instance before the `set` method runs. DSC validates this return value against the DSC Resource's schema.", - "type": "object" - }, - "afterState": { - "title": "State after enforcing", - "description": "This property always represents the current state of the DSC Resource instance as returned by its `set` method after enforcing the desired state. DSC validates this return value against the DSC Resource's schema.", - "type": "object" - }, - "changedProperties": { - "title": "Changed properties", - "description": "This property always represents the list of property names for the DSC Resource instance that the `set` method modified. When this value is an empty array, the `set` method didn't enforce any properties for the instance.", - "type": "array", - "default": [], - "items": { - "type": "string" - } - } - }, - "$defs": {} +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/set.json", + "title": "dsc resource set result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command.", + "type": "object", + "required": [ + "beforeState", + "afterState", + "changedProperties" + ], + "properties": { + "beforeState": { + "title": "State before enforcing", + "description": "This property always represents the desired state of the DSC Resource instance before the `set` method runs. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "afterState": { + "title": "State after enforcing", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `set` method after enforcing the desired state. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "changedProperties": { + "title": "Changed properties", + "description": "This property always represents the list of property names for the DSC Resource instance that the `set` method modified. When this value is an empty array, the `set` method didn't enforce any properties for the instance.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } + }, + "$defs": {} } diff --git a/docs/schemas/bundled/outputs.resource.test.json b/schemas/2023/08/bundled/outputs/resource/test.json similarity index 92% rename from docs/schemas/bundled/outputs.resource.test.json rename to schemas/2023/08/bundled/outputs/resource/test.json index 028056c4f..6e584bca4 100644 --- a/docs/schemas/bundled/outputs.resource.test.json +++ b/schemas/2023/08/bundled/outputs/resource/test.json @@ -1,40 +1,40 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.resource.test.json", - "title": "dsc resource test result", - "description": "Describes the return data for a DSC Resource instance from the `dsc resource test` command.", - "type": "object", - "required": [ - "desiredState", - "actualState", - "inDesiredState", - "differingProperties" - ], - "properties": { - "desiredState": { - "title": "Desired state", - "description": "This property always represents the desired state of the DSC Resource instance as specified to DSC.", - "type": "object" - }, - "actualState": { - "title": "Actual state", - "description": "This property always represents the current state of the DSC Resource instance as returned by its `test` method or, if the DSC Resource doesn't define the `test` method, by its `get` method. DSC validates this return value against the DSC Resource's schema.", - "type": "object" - }, - "inDesiredState": { - "title": "Instance is in the desired state", - "description": "This property indicates whether the instance is in the desired state.", - "type": "boolean" - }, - "differingProperties": { - "title": "Differing properties", - "description": "This property always represents the list of property names for the DSC Resource instance that aren't in the desired state. When this property is an empty array, the instance is in the desired state.", - "type": "array", - "default": [], - "items": { - "type": "string" - } - } - }, - "$defs": {} +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/test.json", + "title": "dsc resource test result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource test` command.", + "type": "object", + "required": [ + "desiredState", + "actualState", + "inDesiredState", + "differingProperties" + ], + "properties": { + "desiredState": { + "title": "Desired state", + "description": "This property always represents the desired state of the DSC Resource instance as specified to DSC.", + "type": "object" + }, + "actualState": { + "title": "Actual state", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `test` method or, if the DSC Resource doesn't define the `test` method, by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "inDesiredState": { + "title": "Instance is in the desired state", + "description": "This property indicates whether the instance is in the desired state.", + "type": "boolean" + }, + "differingProperties": { + "title": "Differing properties", + "description": "This property always represents the list of property names for the DSC Resource instance that aren't in the desired state. When this property is an empty array, the instance is in the desired state.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } + }, + "$defs": {} } diff --git a/docs/schemas/bundled/outputs.schema.json b/schemas/2023/08/bundled/outputs/schema.json similarity index 73% rename from docs/schemas/bundled/outputs.schema.json rename to schemas/2023/08/bundled/outputs/schema.json index 8188f79f5..e5b2d2310 100644 --- a/docs/schemas/bundled/outputs.schema.json +++ b/schemas/2023/08/bundled/outputs/schema.json @@ -1,8 +1,8 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/outputs.schema.json", - "title": "DSC Resource schema result", - "description": "Describes the return data for a DSC Resource from the `dsc schema` command. This command always returns a JSON schema document.", - "type": "object", - "$defs": {} +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/schema.json", + "title": "DSC Resource schema result", + "description": "Describes the return data for a DSC Resource from the `dsc schema` command. This command always returns a JSON schema document.", + "type": "object", + "$defs": {} } diff --git a/docs/schemas/bundled/resource.manifest.json b/schemas/2023/08/bundled/resource/manifest.json similarity index 58% rename from docs/schemas/bundled/resource.manifest.json rename to schemas/2023/08/bundled/resource/manifest.json index ffad7c948..6ebcc1d01 100644 --- a/docs/schemas/bundled/resource.manifest.json +++ b/schemas/2023/08/bundled/resource/manifest.json @@ -1,583 +1,440 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/bundled/resource.manifest.json", - "title": "Command-based DSC Resource Manifest", - "description": "Defines a valid command-based DSC Resource.", - "type": "object", - "required": [ - "manifestVersion", - "type", - "version", - "get" - ], - "properties": { - "manifestVersion": { - "title": "Manifest Version", - "description": "The semver of the DSC Resource manifest schema to validate this manifest with.", - "$ref": "/dsc/2023/07/definitions/semver.json", - "enums": [ - "1.0" - ] - }, - "type": { - "$ref": "/dsc/2023/07/definitions/resourceType.json" - }, - "version": { - "title": "Resource Semantic Version", - "description": "The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages.", - "$ref": "/dsc/2023/07/definitions/semver.json" - }, - "description": { - "title": "Resource Description", - "description": "A short synopsis of the DSC Resource's purpose.", - "type": "string" - }, - "tags": { - "title": "Tags", - "description": "An array of short strings used to search for DSC Resources.", - "type": "array", - "uniqueItems": true, - "items": { - "type": "string", - "pattern": "^\\w+$" - } - }, - "get": { - "$ref": "/dsc/2023/07/resource/manifest.get.json" - }, - "set": { - "$ref": "/dsc/2023/07/resource/manifest.set.json" - }, - "test": { - "$ref": "/dsc/2023/07/resource/manifest.test.json" - }, - "validate": { - "$ref": "/dsc/2023/07/resource/manifest.validate.json" - }, - "provider": { - "$ref": "/dsc/2023/07/resource/manifest.provider.json" - }, - "exitCodes": { - "title": "Exit Codes", - "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", - "type": "object", - "propertyNames": { - "pattern": "^[0-9]+$" - }, - "patternProperties": { - "^[0-9]+$": { - "type": "string" - } - }, - "examples": [ - { - "exitCodes": { - "0": "Success", - "1": "Invalid parameter", - "2": "Invalid input", - "3": "Registry error", - "4": "JSON serialization failed" - } - } - ] - }, - "schema": { - "$ref": "/dsc/2023/07/resource/manifest.schema.json" - } - }, - "$defs": { - "https://schemas.microsoft.com/dsc/2023/07/definitions/semver.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/semver.json", - "type": "string", - "title": "Semantic Version", - "description": "A valid semantic version (semver) string. For reference, see https://semver.org/", - "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", - "$comment": "This pattern comes from the semver website's FAQ:\n\nhttps://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n\nIt's the suggested regex pattern for JavaScript.\n\nThis is the same pattern, made multi-line for easier readability.\n\n```\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n" - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.json", - "title": "DSC Resource fully qualified type name", - "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", - "type": "string", - "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.json", - "title": "Get Method", - "description": "Defines how DSC must call the DSC Resource to get the current state of an instance.", - "type": "object", - "required": [ - "executable" - ], - "properties": { - "executable": { - "$ref": "/dsc/2023/07/definitions/commandExecutable.json" - }, - "args": { - "$ref": "/dsc/2023/07/definitions/commandArgs.json" - }, - "input": { - "$ref": "/dsc/2023/07/definitions/inputKind.json" - } - }, - "examples": [ - { - "executable": "registry", - "args": [ - "config", - "get" - ], - "input": "stdin" - }, - { - "executable": "osinfo" - } - ] - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.json", - "title": "Set Method", - "description": "Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource.", - "type": "object", - "required": [ - "executable", - "input" - ], - "properties": { - "executable": { - "$ref": "/dsc/2023/07/definitions/commandExecutable.json" - }, - "args": { - "$ref": "/dsc/2023/07/definitions/commandArgs.json" - }, - "input": { - "$ref": "/dsc/2023/07/definitions/inputKind.json" - }, - "preTest": { - "title": "Resource Performs Pre-Test", - "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", - "type": "boolean", - "default": false - }, - "return": { - "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", - "$ref": "/dsc/2023/07/definitions/returnKind.json" - } - }, - "examples": [ - { - "executable": "registry", - "args": [ - "config", - "set" - ], - "input": "stdin", - "preTest": true, - "return": "state" - } - ] - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.json", - "title": "Test Method", - "description": "Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource.", - "type": "object", - "required": [ - "executable", - "input" - ], - "properties": { - "executable": { - "$ref": "/dsc/2023/07/definitions/commandExecutable.json" - }, - "args": { - "$ref": "/dsc/2023/07/definitions/commandArgs.json" - }, - "input": { - "$ref": "/dsc/2023/07/definitions/inputKind.json" - }, - "return": { - "title": "Test Command Return Type", - "description": "Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state.", - "$ref": "/dsc/2023/07/definitions/returnKind.json" - } - }, - "examples": [ - { - "executable": "registry", - "args": [ - "config", - "test" - ], - "input": "stdin", - "return": "state" - } - ] - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.json", - "title": "Validate Method", - "description": "Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources.", - "type": "object", - "required": [ - "executable" - ], - "properties": { - "executable": { - "$ref": "/dsc/2023/07/definitions/commandExecutable.json" - }, - "args": { - "$ref": "/dsc/2023/07/definitions/commandArgs.json" - } - }, - "examples": [ - { - "executable": "dsc", - "args": [ - "config", - "validate" - ] - } - ] - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.json", - "title": "Provider", - "description": "Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to manage resources that don't have their own manifests with DSC.", - "type": "object", - "required": [ - "list", - "config" - ], - "properties": { - "list": { - "title": "List Command", - "description": "Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.", - "type": "object", - "required": [ - "executable" - ], - "properties": { - "executable": { - "$ref": "/dsc/2023/07/definitions/commandExecutable.json" - }, - "args": { - "$ref": "/dsc/2023/07/definitions/commandArgs.json" - } - } - }, - "config": { - "title": "Expected Configuration", - "description": "Defines whether the provider expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations.", - "type": "string", - "enum": [ - "full", - "sequence" - ] - } - }, - "examples": [ - { - "config": "full", - "list": { - "executable": "pwsh", - "args": [ - "-NoLogo", - "-NonInteractive", - "-NoProfile", - "-Command", - "./powershellgroup.resource.ps1 List" - ] - } - } - ] - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.json", - "title": "Instance Schema", - "description": "Defines how DSC must validate a JSON blob representing an instance of the DSC Resource.", - "type": "object", - "oneOf": [ - { - "required": [ - "command" - ] - }, - { - "required": [ - "embedded" - ] - } - ], - "properties": { - "command": { - "title": "Instance Schema Command", - "description": "Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource.", - "type": "object", - "required": [ - "executable" - ], - "properties": { - "executable": { - "$ref": "/dsc/2023/07/definitions/commandExecutable.json" - }, - "args": { - "$ref": "/dsc/2023/07/definitions/commandArgs.json" - } - } - }, - "embedded": { - "title": "Embedded Instance Schema", - "description": "Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource.", - "type": "object", - "required": [ - "$schema", - "type", - "properties" - ], - "properties": { - "type": { - "title": "Instance Type", - "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", - "const": "object" - }, - "$schema": { - "title": "DSC Resource instance schema dialect", - "description": "Defines which dialect of JSON Schema the DSC Resource is using to validate instances.", - "type": "string", - "format": "uri-reference", - "enum": [ - "https://json-schema.org/draft/2020-12/schema", - "https://json-schema.org/draft/2019-09/schema", - "http://json-schema.org/draft-07/schema#" - ] - }, - "$id": { - "title": "DSC Resource instance schema ID", - "description": "Defines the unique ID for the DSC Resource's instance schema.", - "type": "string", - "format": "uri-reference" - }, - "properties": { - "title": "Instance Properties", - "description": "Defines the schema for the DSC Resource's properties. Must define at least one property.", - "type": "object", - "minProperties": 1, - "unevaluatedProperties": { - "anyOf": [ - { - "$ref": "https://json-schema.org/draft/2020-12/schema" - }, - { - "$ref": "https://json-schema.org/draft/2019-09/schema" - }, - { - "$ref": "http://json-schema.org/draft-07/schema#" - } - ] - }, - "properties": { - "_ensure": { - "title": "Standard Property: _ensure", - "description": "Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums.", - "const": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json" - } - }, - "_inDesiredState": { - "title": "Standard Property: _inDesiredState", - "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", - "const": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json" - } - }, - "_purge": { - "title": "Standard Property: _purge", - "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", - "const": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json" - } - }, - "_rebootRequested": { - "title": "Standard property: _rebootRequested", - "description": "Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes.", - "const": { - "$ref": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json" - } - } - } - } - } - }, - "url": { - "title": "Instance Schema URL", - "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", - "type": "string", - "format": "uri" - } - }, - "examples": [ - { - "command": { - "executable": "registry", - "args": [ - "schema" - ] - } - }, - { - "embedded": { - "$schema": "http://json-schema.org/draft-07/schema#", - "title": "OSInfo", - "type": "object", - "required": [], - "properties": { - "$id": { - "type": "string" - }, - "architecture": { - "type": [ - "string", - "null" - ] - }, - "bitness": { - "$ref": "#/definitions/Bitness" - }, - "codename": { - "type": [ - "string", - "null" - ] - }, - "edition": { - "type": [ - "string", - "null" - ] - }, - "family": { - "$ref": "#/definitions/Family" - }, - "version": { - "type": "string" - } - }, - "additionalProperties": false, - "definitions": { - "Bitness": { - "type": "string", - "enum": [ - "32", - "64", - "unknown" - ] - }, - "Family": { - "type": "string", - "enum": [ - "Linux", - "macOS", - "Windows" - ] - } - } - } - } - ] - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.json", - "title": "Executable Command Name", - "description": "The name of the command to run.", - "type": "string" - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.json", - "title": "Executable Command Arguments", - "description": "The list of arguments to pass to the command.", - "type": "array", - "items": { - "type": "string" - } - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.json", - "title": "Executable Command Input Type", - "description": "Defines how DSC should pass input to the command, either as arguments or JSON over stdin.", - "type": "string", - "enum": [ - "args", - "stdin" - ], - "default": "args" - }, - "https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.json", - "title": "Return Kind", - "type": "string", - "enum": [ - "state", - "stateAndDiff" - ], - "default": "state", - "$comment": "While the enumeration for return kind is the same for the `set` and `test`\nmethod, the way it changes the behavior of the command isn't. The description\nkeyword isn't included here because the respective schemas for those methods\ndocument the behavior themselves." - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.json", - "title": "Ensure Existence", - "description": "Indicates whether the DSC Resource instance should exist.", - "type": "string", - "enum": [ - "Absent", - "Present" - ] - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.json", - "title": "Instance is in the Desired State", - "description": "Indicates whether the instance is in the desired state. This property is only returned by the `test` method.", - "type": [ - "boolean", - "null" - ], - "readOnly": true - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.json", - "title": "Purge", - "description": "Indicates that only the components described in the DSC Resource should exist. If other components exist, the DSC Resource is out of the desired state. When enforcing desired state, the DSC Resource removes unmanaged components.", - "type": [ - "boolean", - "null" - ], - "writeOnly": true - }, - "https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.json", - "title": "Reboot Requested", - "description": "Indicates that the set operation requires a reboot before it's fully complete.", - "type": [ - "boolean", - "null" - ], - "readOnly": true - } - } +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json", + "title": "Command-based DSC Resource Manifest", + "description": "Defines a valid command-based DSC Resource.", + "type": "object", + "required": [ + "manifestVersion", + "type", + "version", + "get" + ], + "properties": { + "manifestVersion": { + "title": "Manifest Version", + "description": "The semver of the DSC Resource manifest schema to validate this manifest with.", + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "enums": [ + "1.0" + ] + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "version": { + "title": "Resource Semantic Version", + "description": "The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages.", + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "tags": { + "title": "Tags", + "description": "An array of short strings used to search for DSC Resources.", + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "get": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json" + }, + "set": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json" + }, + "test": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json" + }, + "validate": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json" + }, + "provider": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json" + }, + "exitCodes": { + "title": "Exit Codes", + "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", + "type": "object", + "propertyNames": { + "pattern": "^[0-9]+$" + }, + "patternProperties": { + "^[0-9]+$": { + "type": "string" + } + }, + "examples": [ + { + "exitCodes": { + "0": "Success", + "1": "Invalid parameter", + "2": "Invalid input", + "3": "Registry error", + "4": "JSON serialization failed" + } + } + ] + }, + "schema": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "type": "string", + "title": "Semantic Version", + "description": "A valid semantic version (semver) string. For reference, see https://semver.org/", + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json", + "title": "Get Method", + "description": "Defines how DSC must call the DSC Resource to get the current state of an instance.", + "type": "object", + "required": "executable", + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json", + "title": "Set Method", + "description": "Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + }, + "preTest": { + "title": "Resource Performs Pre-Test", + "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", + "type": "boolean", + "default": false + }, + "return": { + "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json", + "title": "Test Method", + "description": "Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + }, + "return": { + "title": "Test Command Return Type", + "description": "Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state.", + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json", + "title": "Validate Method", + "description": "Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources.", + "type": "object", + "required": "executable", + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json", + "title": "Provider", + "description": "Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to manage resources that don't have their own manifests with DSC.", + "type": "object", + "required": [ + "list", + "config" + ], + "properties": { + "list": { + "title": "List Command", + "description": "Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.", + "type": "object", + "required": "executable", + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "config": { + "title": "Expected Configuration", + "description": "Defines whether the provider expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations.", + "type": "string", + "enum": [ + "full", + "sequence" + ] + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json", + "title": "Instance Schema", + "description": "Defines how DSC must validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "oneOf": [ + { + "required": "command" + }, + { + "required": "embedded" + } + ], + "properties": { + "command": { + "title": "Instance Schema Command", + "description": "Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": "executable", + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "embedded": { + "title": "Embedded Instance Schema", + "description": "Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": [ + "$schema", + "type", + "properties" + ], + "properties": { + "type": { + "title": "Instance Type", + "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", + "const": "object" + }, + "$schema": { + "title": "DSC Resource instance schema dialect", + "description": "Defines which dialect of JSON Schema the DSC Resource is using to validate instances.", + "type": "string", + "format": "uri-reference", + "enum": [ + "https://json-schema.org/draft/2020-12/schema", + "https://json-schema.org/draft/2019-09/schema", + "http://json-schema.org/draft-07/schema#" + ] + }, + "$id": { + "title": "DSC Resource instance schema ID", + "description": "Defines the unique ID for the DSC Resource's instance schema.", + "type": "string", + "format": "uri-reference" + }, + "properties": { + "title": "Instance Properties", + "description": "Defines the schema for the DSC Resource's properties. Must define at least one property.", + "type": "object", + "minProperties": 1, + "unevaluatedProperties": { + "anyOf": [ + { + "$ref": "https://json-schema.org/draft/2020-12/schema" + }, + { + "$ref": "https://json-schema.org/draft/2019-09/schema" + }, + { + "$ref": "http://json-schema.org/draft-07/schema#" + } + ] + }, + "properties": { + "_ensure": { + "title": "Standard Property: _ensure", + "description": "Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json" + } + }, + "_inDesiredState": { + "title": "Standard Property: _inDesiredState", + "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json" + } + }, + "_purge": { + "title": "Standard Property: _purge", + "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json" + } + }, + "_rebootRequested": { + "title": "Standard property: _rebootRequested", + "description": "Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" + } + } + } + } + } + }, + "url": { + "title": "Instance Schema URL", + "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", + "type": "string", + "format": "uri" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "title": "Executable Command Name", + "description": "The name of the command to run.", + "type": "string" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "title": "Executable Command Arguments", + "description": "The list of arguments to pass to the command.", + "type": "array", + "items": { + "type": "string" + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", + "title": "Executable Command Input Type", + "description": "Defines how DSC should pass input to the command, either as arguments or JSON over stdin.", + "type": "string", + "enum": [ + "args", + "stdin" + ], + "default": "args" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json", + "title": "Return Kind", + "type": "string", + "enum": [ + "state", + "stateAndDiff" + ], + "default": "state" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json", + "title": "Ensure Existence", + "description": "Indicates whether the DSC Resource instance should exist.", + "type": "string", + "enum": [ + "Absent", + "Present" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json", + "title": "Instance is in the Desired State", + "description": "Indicates whether the instance is in the desired state. This property is only returned by the `test` method.", + "type": [ + "boolean", + "null" + ], + "readOnly": true + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json", + "title": "Purge", + "description": "Indicates that only the components described in the DSC Resource should exist. If other components exist, the DSC Resource is out of the desired state. When enforcing desired state, the DSC Resource removes unmanaged components.", + "type": [ + "boolean", + "null" + ], + "writeOnly": true + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json", + "title": "Reboot Requested", + "description": "Indicates that the set operation requires a reboot before it's fully complete.", + "type": [ + "boolean", + "null" + ], + "readOnly": true + } + } } diff --git a/schemas/2023/08/bundled/resource/manifest.vscode.json b/schemas/2023/08/bundled/resource/manifest.vscode.json new file mode 100644 index 000000000..d9e6cdc0f --- /dev/null +++ b/schemas/2023/08/bundled/resource/manifest.vscode.json @@ -0,0 +1,412 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json", + "title": "Command-based DSC Resource Manifest", + "description": "Defines a valid command-based DSC Resource.", + "type": "object", + "required": [ + "manifestVersion", + "type", + "version", + "get" + ], + "properties": { + "manifestVersion": { + "title": "Manifest Version", + "description": "The semver of the DSC Resource manifest schema to validate this manifest with.", + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "enums": [ + "1.0" + ] + }, + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "version": { + "title": "Resource Semantic Version", + "description": "The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages.", + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "tags": { + "title": "Tags", + "description": "An array of short strings used to search for DSC Resources.", + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "get": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json" + }, + "set": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json" + }, + "test": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json" + }, + "validate": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json" + }, + "provider": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json" + }, + "exitCodes": { + "title": "Exit Codes", + "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", + "type": "object", + "propertyNames": { + "pattern": "^[0-9]+$" + }, + "patternProperties": { + "^[0-9]+$": { + "type": "string" + } + }, + "examples": [ + { + "exitCodes": { + "0": "Success", + "1": "Invalid parameter", + "2": "Invalid input", + "3": "Registry error", + "4": "JSON serialization failed" + } + } + ] + }, + "schema": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json" + } + }, + "$defs": { + "PowerShell": { + "DSC": { + "main": { + "schemas": { + "2023": { + "08": { + "definitions": { + "semver.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "type": "string", + "title": "Semantic Version", + "description": "A valid semantic version (semver) string. For reference, see https://semver.org/", + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$" + }, + "resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "commandExecutable.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "title": "Executable Command Name", + "description": "The name of the command to run.", + "type": "string" + }, + "commandArgs.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "title": "Executable Command Arguments", + "description": "The list of arguments to pass to the command.", + "type": "array", + "items": { + "type": "string" + } + }, + "inputKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", + "title": "Executable Command Input Type", + "description": "Defines how DSC should pass input to the command, either as arguments or JSON over stdin.", + "type": "string", + "enum": [ + "args", + "stdin" + ], + "default": "args" + }, + "returnKind.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json", + "title": "Return Kind", + "type": "string", + "enum": [ + "state", + "stateAndDiff" + ], + "default": "state" + } + }, + "resource": { + "manifest.get.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json", + "title": "Get Method", + "description": "Defines how DSC must call the DSC Resource to get the current state of an instance.", + "type": "object", + "required": "executable", + "properties": { + "executable": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + } + } + }, + "manifest.set.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json", + "title": "Set Method", + "description": "Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + }, + "preTest": { + "title": "Resource Performs Pre-Test", + "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", + "type": "boolean", + "default": false + }, + "return": { + "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" + } + } + }, + "manifest.test.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json", + "title": "Test Method", + "description": "Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + }, + "return": { + "title": "Test Command Return Type", + "description": "Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state.", + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" + } + } + }, + "manifest.validate.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json", + "title": "Validate Method", + "description": "Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources.", + "type": "object", + "required": "executable", + "properties": { + "executable": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "manifest.provider.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json", + "title": "Provider", + "description": "Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to manage resources that don't have their own manifests with DSC.", + "type": "object", + "required": [ + "list", + "config" + ], + "properties": { + "list": { + "title": "List Command", + "description": "Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.", + "type": "object", + "required": "executable", + "properties": { + "executable": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "config": { + "title": "Expected Configuration", + "description": "Defines whether the provider expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations.", + "type": "string", + "enum": [ + "full", + "sequence" + ] + } + } + }, + "manifest.schema.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json", + "title": "Instance Schema", + "description": "Defines how DSC must validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "oneOf": [ + { + "required": "command" + }, + { + "required": "embedded" + } + ], + "properties": { + "command": { + "title": "Instance Schema Command", + "description": "Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": "executable", + "properties": { + "executable": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "embedded": { + "title": "Embedded Instance Schema", + "description": "Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": [ + "$schema", + "type", + "properties" + ], + "properties": { + "type": { + "title": "Instance Type", + "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", + "const": "object" + }, + "$schema": { + "title": "DSC Resource instance schema dialect", + "description": "Defines which dialect of JSON Schema the DSC Resource is using to validate instances.", + "type": "string", + "format": "uri-reference", + "enum": [ + "https://json-schema.org/draft/2020-12/schema", + "https://json-schema.org/draft/2019-09/schema", + "http://json-schema.org/draft-07/schema#" + ] + }, + "$id": { + "title": "DSC Resource instance schema ID", + "description": "Defines the unique ID for the DSC Resource's instance schema.", + "type": "string", + "format": "uri-reference" + }, + "properties": { + "title": "Instance Properties", + "description": "Defines the schema for the DSC Resource's properties. Must define at least one property.", + "type": "object", + "minProperties": 1, + "unevaluatedProperties": { + "anyOf": [ + { + "$ref": "https://json-schema.org/draft/2020-12/schema" + }, + { + "$ref": "https://json-schema.org/draft/2019-09/schema" + }, + { + "$ref": "http://json-schema.org/draft-07/schema#" + } + ] + }, + "properties": { + "_ensure": { + "title": "Standard Property: _ensure", + "description": "Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json" + } + }, + "_inDesiredState": { + "title": "Standard Property: _inDesiredState", + "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json" + } + }, + "_purge": { + "title": "Standard Property: _purge", + "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json" + } + }, + "_rebootRequested": { + "title": "Standard property: _rebootRequested", + "description": "Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" + } + } + } + } + } + }, + "url": { + "title": "Instance Schema URL", + "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", + "type": "string", + "format": "uri" + } + } + } + } + } + } + } + } + } + } + } +} diff --git a/schemas/2023/08/config/document.json b/schemas/2023/08/config/document.json new file mode 100644 index 000000000..3be3f9c7e --- /dev/null +++ b/schemas/2023/08/config/document.json @@ -0,0 +1,49 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", + "title": "DSC Configuration Document schema", + "description": "Describes a valid DSC Configuration Document.", + "type": "object", + "required": [ + "$schema", + "resources" + ], + "properties": { + "$schema": { + "title": "Schema", + "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "/PowerShell/DSC/main/schemas/2023/08/config/document.json" + ] + }, + "parameters": { + "title": "DSC Configuration document parameters", + "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "type": "object", + "additionalProperties": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" + } + }, + "variables": { + "title": "Configuration variables", + "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", + "type": "object" + }, + "resources": { + "title": "DSC Configuration document resources", + "description": "Defines a list of DSC Resource instances for the configuration to manage.", + "type": "array", + "minItems": 1, + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" + } + }, + "metadata": { + "title": "Configuration metadata", + "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", + "type": "object" + } + } +} diff --git a/schemas/2023/08/config/document.parameter.json b/schemas/2023/08/config/document.parameter.json new file mode 100644 index 000000000..26b606a1e --- /dev/null +++ b/schemas/2023/08/config/document.parameter.json @@ -0,0 +1,102 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json", + "title": "Parameter", + "description": "Defines a runtime option for a DSC Configuration Document.", + "type": "object", + "required": [ + "type" + ], + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json" + }, + "defaultValue": { + "title": "Default value", + "description": "Defines the default value for the parameter.", + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" + }, + "allowedValues": { + "title": "Allowed values", + "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" + } + }, + "description": { + "title": "Parameter description", + "description": "Defines a synopsis for the parameter explaining its purpose.", + "type": "string" + }, + "metadata": { + "title": "Parameter metadata", + "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", + "type": "object" + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "minValue": { + "title": "Minimum value", + "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", + "type": "integer" + }, + "maxValue": { + "title": "Maximum value", + "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", + "type": "integer" + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + }, + { + "properties": { + "type": { + "const": "array" + } + } + } + ] + }, + "then": { + "minLength": { + "title": "Minimum length", + "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", + "type": "integer", + "minimum": 0 + }, + "maxLength": { + "title": "Maximum length", + "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", + "type": "integer", + "minimum": 0 + } + } + } + ] +} diff --git a/schemas/2023/08/config/document.resource.json b/schemas/2023/08/config/document.resource.json new file mode 100644 index 000000000..4a0bebb9f --- /dev/null +++ b/schemas/2023/08/config/document.resource.json @@ -0,0 +1,33 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json", + "title": "DSC Resource instance", + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "dependsOn": { + "title": "Instance depends on", + "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", + "type": "array", + "items": { + "type": "string", + "uniqueItems": true, + "pattern": "^\\[\\w+(\\.\\w+){0,2}\\/\\w+\\].+$" + } + }, + "properties": { + "title": "Managed instance properties", + "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", + "type": "object" + } + } +} diff --git a/schemas/2023/08/definitions/commandArgs.json b/schemas/2023/08/definitions/commandArgs.json new file mode 100644 index 000000000..67af70e06 --- /dev/null +++ b/schemas/2023/08/definitions/commandArgs.json @@ -0,0 +1,10 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json", + "title": "Executable Command Arguments", + "description": "The list of arguments to pass to the command.", + "type": "array", + "items": { + "type": "string" + } +} diff --git a/schemas/2023/08/definitions/commandExecutable.json b/schemas/2023/08/definitions/commandExecutable.json new file mode 100644 index 000000000..408eb9289 --- /dev/null +++ b/schemas/2023/08/definitions/commandExecutable.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json", + "title": "Executable Command Name", + "description": "The name of the command to run.", + "type": "string" +} diff --git a/schemas/2023/08/definitions/hadErrors.json b/schemas/2023/08/definitions/hadErrors.json new file mode 100644 index 000000000..6ea65bfec --- /dev/null +++ b/schemas/2023/08/definitions/hadErrors.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json", + "title": "Had Errors", + "description": "Indicates whether any of the DSC Resources returned a non-zero exit code.", + "type": "boolean" +} diff --git a/schemas/2023/08/definitions/inputKind.json b/schemas/2023/08/definitions/inputKind.json new file mode 100644 index 000000000..c6305bd52 --- /dev/null +++ b/schemas/2023/08/definitions/inputKind.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json", + "title": "Executable Command Input Type", + "description": "Defines how DSC should pass input to the command, either as arguments or JSON over stdin.", + "type": "string", + "enum": [ + "args", + "stdin" + ], + "default": "args" +} diff --git a/schemas/2023/08/definitions/instanceName.json b/schemas/2023/08/definitions/instanceName.json new file mode 100644 index 000000000..ba86a225a --- /dev/null +++ b/schemas/2023/08/definitions/instanceName.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" +} diff --git a/schemas/2023/08/definitions/message.json b/schemas/2023/08/definitions/message.json new file mode 100644 index 000000000..48be4a2e7 --- /dev/null +++ b/schemas/2023/08/definitions/message.json @@ -0,0 +1,39 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/message.json", + "title": "Message", + "description": "A message emitted by a DSC Resource with associated metadata.", + "type": "object", + "required": [ + "name", + "type", + "message", + "level" + ], + "properties": { + "name": { + "title": "Message source instance name", + "description": "The short, human-readable name for the instance that emitted the message, as defined in the DSC Configuration Document.", + "type": "string" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "message": { + "title": "Message content", + "description": "The actual content of the message as emitted by the DSC Resource.", + "type": "string", + "minLength": 1 + }, + "level": { + "title": "Message level", + "description": "Indicates the severity of the message.", + "type": "string", + "enum": [ + "Error", + "Warning", + "Information" + ] + } + } +} diff --git a/schemas/2023/08/definitions/messages.json b/schemas/2023/08/definitions/messages.json new file mode 100644 index 000000000..a8cf65986 --- /dev/null +++ b/schemas/2023/08/definitions/messages.json @@ -0,0 +1,10 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json", + "title": "Messages", + "description": "A list of structured messages emitted by the DSC Resources during an operation.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/message.json" + } +} diff --git a/schemas/2023/08/definitions/parameters/dataTypes.json b/schemas/2023/08/definitions/parameters/dataTypes.json new file mode 100644 index 000000000..0a3951dc7 --- /dev/null +++ b/schemas/2023/08/definitions/parameters/dataTypes.json @@ -0,0 +1,16 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json", + "title": "Data Types", + "description": "Defines the data type for the value.", + "type": "string", + "enum": [ + "string", + "securestring", + "int", + "bool", + "object", + "secureobject", + "array" + ] +} diff --git a/schemas/2023/08/definitions/parameters/validValueTypes.json b/schemas/2023/08/definitions/parameters/validValueTypes.json new file mode 100644 index 000000000..ac2f7b14d --- /dev/null +++ b/schemas/2023/08/definitions/parameters/validValueTypes.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json", + "$comment": "This schema fragment makes it a little easier to compose the valid properties\nfor DSC Configuration document parameters. As-written, values must be one of\nthose on this list - the schema definition for dataType excludes `null` and\nnumbers with fractional parts, like `3.5`.\n", + "type": [ + "string", + "integer", + "object", + "array", + "boolean" + ] +} diff --git a/schemas/2023/08/definitions/resourceType.json b/schemas/2023/08/definitions/resourceType.json new file mode 100644 index 000000000..41ae13554 --- /dev/null +++ b/schemas/2023/08/definitions/resourceType.json @@ -0,0 +1,8 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" +} diff --git a/schemas/2023/08/definitions/returnKind.json b/schemas/2023/08/definitions/returnKind.json new file mode 100644 index 000000000..12de48fa8 --- /dev/null +++ b/schemas/2023/08/definitions/returnKind.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json", + "title": "Return Kind", + "type": "string", + "enum": [ + "state", + "stateAndDiff" + ], + "default": "state", + "$comment": "While the enumeration for return kind is the same for the `set` and `test`\nmethod, the way it changes the behavior of the command isn't. The description\nkeyword isn't included here because the respective schemas for those methods\ndocument the behavior themselves." +} diff --git a/schemas/2023/08/definitions/semver.json b/schemas/2023/08/definitions/semver.json new file mode 100644 index 000000000..6e19aa651 --- /dev/null +++ b/schemas/2023/08/definitions/semver.json @@ -0,0 +1,9 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "type": "string", + "title": "Semantic Version", + "description": "A valid semantic version (semver) string. For reference, see https://semver.org/", + "pattern": "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)(?:-((?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$", + "$comment": "This pattern comes from the semver website's FAQ:\n\nhttps://semver.org/#is-there-a-suggested-regular-expression-regex-to-check-a-semver-string\n\nIt's the suggested regex pattern for JavaScript.\n\nThis is the same pattern, made multi-line for easier readability.\n\n```\n^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\n(?:-(\n (?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*)\n (?:\\.(?:0|[1-9]\\d*|\\d*[a-zA-Z-][0-9a-zA-Z-]*))\n*))?\n(?:\\+([0-9a-zA-Z-]+(?:\\.[0-9a-zA-Z-]+)*))?$\n```\n\nThe first line matches the `major.minor.patch` components of the version. The middle lines match\nthe pre-release components. The last line matches the build metadata component.\n" +} diff --git a/schemas/2023/08/outputs/config/get.json b/schemas/2023/08/outputs/config/get.json new file mode 100644 index 000000000..9c5de7d64 --- /dev/null +++ b/schemas/2023/08/outputs/config/get.json @@ -0,0 +1,45 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/get.json", + "title": "DSC Configuration get command result", + "description": "Represents the data structure returned by the `dsc config get` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `get` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "title": "Get Result", + "type": "object", + "required": [ + "name", + "type", + "result" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/get.json" + } + } + } + }, + "messages": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json" + } + } +} diff --git a/schemas/2023/08/outputs/config/set.json b/schemas/2023/08/outputs/config/set.json new file mode 100644 index 000000000..450eb783e --- /dev/null +++ b/schemas/2023/08/outputs/config/set.json @@ -0,0 +1,45 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/set.json", + "title": "DSC Configuration set command result", + "description": "Represents the data structure returned by the `dsc config set` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `set` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "title": "Set Result", + "type": "object", + "required": [ + "name", + "type", + "result" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/set.json" + } + } + } + }, + "messages": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json" + } + } +} diff --git a/schemas/2023/08/outputs/config/test.json b/schemas/2023/08/outputs/config/test.json new file mode 100644 index 000000000..964c98fd8 --- /dev/null +++ b/schemas/2023/08/outputs/config/test.json @@ -0,0 +1,45 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/config/test.json", + "title": "DSC Configuration test command result", + "description": "Represents the data structure returned by the `dsc config test` command.", + "type": "object", + "required": [ + "results", + "messages", + "hadErrors" + ], + "properties": { + "results": { + "title": "Results", + "description": "The results of the `test` method for every DSC Resource instance in the DSC Configuration Document with the instance's name and type.", + "type": "array", + "items": { + "title": "Test Result", + "type": "object", + "required": [ + "name", + "type", + "result" + ], + "properties": { + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "result": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/results/resource/test.json" + } + } + } + }, + "messages": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/messages.json" + }, + "hadErrors": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/hadErrors.json" + } + } +} diff --git a/schemas/2023/08/outputs/resource/get.json b/schemas/2023/08/outputs/resource/get.json new file mode 100644 index 000000000..00a306026 --- /dev/null +++ b/schemas/2023/08/outputs/resource/get.json @@ -0,0 +1,17 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/get.json", + "title": "dsc resource get result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource get` command.", + "type": "object", + "required": [ + "actualState" + ], + "properties": { + "actualState": { + "title": "Actual state", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + } + } +} diff --git a/schemas/2023/08/outputs/resource/list.json b/schemas/2023/08/outputs/resource/list.json new file mode 100644 index 000000000..13b4a5094 --- /dev/null +++ b/schemas/2023/08/outputs/resource/list.json @@ -0,0 +1,91 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/list.json", + "title": "dsc resource list result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource list` command.", + "type": "object", + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "version": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "path": { + "title": "Path", + "description": "Indicates the path to the DSC Resource on the file system.", + "type": "string" + }, + "directory": { + "title": "Directory", + "description": "Indicates the path to the folder containing the DSC Resource on the file system.", + "type": "string" + }, + "implementedAs": { + "title": "Implemented as", + "description": "Indicates how the DSC Resource was implemented.", + "oneOf": [ + { + "title": "Standard implementation", + "description": "Indicates that the DSC Resource is implemented as one of the standard implementations built into DSC.", + "type": "string", + "enum": [ + "Command" + ] + }, + { + "title": "Custom implementation", + "description": "Indicates that the DSC Resource uses a custom implementation.", + "type": "object", + "required": [ + "custom" + ], + "properties": { + "custom": { + "title": "Custom implementation name", + "description": "The name of the custom implementation.", + "type": "string" + } + } + } + ] + }, + "author": { + "title": "Author", + "description": "Indicates the name of the person or organization that developed and maintains the DSC Resource.", + "type": [ + "string", + "null" + ] + }, + "properties": { + "title": "Properties", + "description": "Defines the DSC Resource's property names.", + "type": "array", + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "requires": { + "title": "Required DSC Resource Provider", + "description": "Defines the fully qualified type name of the DSC Resource Provider the DSC Resource depends on.", + "oneOf": [ + { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + { + "type": "null" + } + ] + }, + "manifest": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json" + } + } +} diff --git a/schemas/2023/08/outputs/resource/schema.json b/schemas/2023/08/outputs/resource/schema.json new file mode 100644 index 000000000..fd430dd71 --- /dev/null +++ b/schemas/2023/08/outputs/resource/schema.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/schema.json", + "title": "DSC Resource schema result", + "description": "Describes the return data for a DSC Resource from the `dsc resource schema` command. This command always returns the DSC Resource's JSON schema document.", + "type": "object" +} diff --git a/schemas/2023/08/outputs/resource/set.json b/schemas/2023/08/outputs/resource/set.json new file mode 100644 index 000000000..ce8776378 --- /dev/null +++ b/schemas/2023/08/outputs/resource/set.json @@ -0,0 +1,33 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/set.json", + "title": "dsc resource set result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource set` command.", + "type": "object", + "required": [ + "beforeState", + "afterState", + "changedProperties" + ], + "properties": { + "beforeState": { + "title": "State before enforcing", + "description": "This property always represents the desired state of the DSC Resource instance before the `set` method runs. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "afterState": { + "title": "State after enforcing", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `set` method after enforcing the desired state. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "changedProperties": { + "title": "Changed properties", + "description": "This property always represents the list of property names for the DSC Resource instance that the `set` method modified. When this value is an empty array, the `set` method didn't enforce any properties for the instance.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } + } +} diff --git a/schemas/2023/08/outputs/resource/test.json b/schemas/2023/08/outputs/resource/test.json new file mode 100644 index 000000000..e64a9d5dd --- /dev/null +++ b/schemas/2023/08/outputs/resource/test.json @@ -0,0 +1,39 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/resource/test.json", + "title": "dsc resource test result", + "description": "Describes the return data for a DSC Resource instance from the `dsc resource test` command.", + "type": "object", + "required": [ + "desiredState", + "actualState", + "inDesiredState", + "differingProperties" + ], + "properties": { + "desiredState": { + "title": "Desired state", + "description": "This property always represents the desired state of the DSC Resource instance as specified to DSC.", + "type": "object" + }, + "actualState": { + "title": "Actual state", + "description": "This property always represents the current state of the DSC Resource instance as returned by its `test` method or, if the DSC Resource doesn't define the `test` method, by its `get` method. DSC validates this return value against the DSC Resource's schema.", + "type": "object" + }, + "inDesiredState": { + "title": "Instance is in the desired state", + "description": "This property indicates whether the instance is in the desired state.", + "type": "boolean" + }, + "differingProperties": { + "title": "Differing properties", + "description": "This property always represents the list of property names for the DSC Resource instance that aren't in the desired state. When this property is an empty array, the instance is in the desired state.", + "type": "array", + "default": [], + "items": { + "type": "string" + } + } + } +} diff --git a/schemas/2023/08/outputs/schema.json b/schemas/2023/08/outputs/schema.json new file mode 100644 index 000000000..f3142e294 --- /dev/null +++ b/schemas/2023/08/outputs/schema.json @@ -0,0 +1,7 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/outputs/schema.json", + "title": "DSC Resource schema result", + "description": "Describes the return data for a DSC Resource from the `dsc schema` command. This command always returns a JSON schema document.", + "type": "object" +} diff --git a/schemas/2023/08/resource/manifest.get.json b/schemas/2023/08/resource/manifest.get.json new file mode 100644 index 000000000..351aa81dd --- /dev/null +++ b/schemas/2023/08/resource/manifest.get.json @@ -0,0 +1,34 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json", + "title": "Get Method", + "description": "Defines how DSC must call the DSC Resource to get the current state of an instance.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "get" + ], + "input": "stdin" + }, + { + "executable": "osinfo" + } + ] +} diff --git a/schemas/2023/08/resource/manifest.json b/schemas/2023/08/resource/manifest.json new file mode 100644 index 000000000..07f125eb7 --- /dev/null +++ b/schemas/2023/08/resource/manifest.json @@ -0,0 +1,88 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.json", + "title": "Command-based DSC Resource Manifest", + "description": "Defines a valid command-based DSC Resource.", + "type": "object", + "required": [ + "manifestVersion", + "type", + "version", + "get" + ], + "properties": { + "manifestVersion": { + "title": "Manifest Version", + "description": "The semver of the DSC Resource manifest schema to validate this manifest with.", + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json", + "enums": [ + "1.0" + ] + }, + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "version": { + "title": "Resource Semantic Version", + "description": "The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages.", + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/semver.json" + }, + "description": { + "title": "Resource Description", + "description": "A short synopsis of the DSC Resource's purpose.", + "type": "string" + }, + "tags": { + "title": "Tags", + "description": "An array of short strings used to search for DSC Resources.", + "type": "array", + "uniqueItems": true, + "items": { + "type": "string", + "pattern": "^\\w+$" + } + }, + "get": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.get.json" + }, + "set": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json" + }, + "test": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json" + }, + "validate": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json" + }, + "provider": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json" + }, + "exitCodes": { + "title": "Exit Codes", + "description": "This property defines a map of valid exit codes for the DSC Resource. DSC always interprets exit code `0` as a successful operation and any other exit code as an error. Use this property to indicate human-readable semantic meanings for the DSC Resource's exit codes.", + "type": "object", + "propertyNames": { + "pattern": "^[0-9]+$" + }, + "patternProperties": { + "^[0-9]+$": { + "type": "string" + } + }, + "examples": [ + { + "exitCodes": { + "0": "Success", + "1": "Invalid parameter", + "2": "Invalid input", + "3": "Registry error", + "4": "JSON serialization failed" + } + } + ] + }, + "schema": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json" + } + } +} diff --git a/schemas/2023/08/resource/manifest.provider.json b/schemas/2023/08/resource/manifest.provider.json new file mode 100644 index 000000000..efbcbcf3a --- /dev/null +++ b/schemas/2023/08/resource/manifest.provider.json @@ -0,0 +1,53 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.provider.json", + "title": "Provider", + "description": "Defines the DSC Resource as a DSC Resource Provider. A DSC Resource Provider enables users to manage resources that don't have their own manifests with DSC.", + "type": "object", + "required": [ + "list", + "config" + ], + "properties": { + "list": { + "title": "List Command", + "description": "Defines how DSC must call the DSC Resource Provider to list its supported DSC Resources.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "config": { + "title": "Expected Configuration", + "description": "Defines whether the provider expects to receive a full and unprocessed configuration as a single JSON blob over stdin or a sequence of JSON Lines for each child resource's configurations.", + "type": "string", + "enum": [ + "full", + "sequence" + ] + } + }, + "examples": [ + { + "config": "full", + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "./powershellgroup.resource.ps1 List" + ] + } + } + ] +} diff --git a/schemas/2023/08/resource/manifest.schema.json b/schemas/2023/08/resource/manifest.schema.json new file mode 100644 index 000000000..11145f7ee --- /dev/null +++ b/schemas/2023/08/resource/manifest.schema.json @@ -0,0 +1,195 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.schema.json", + "title": "Instance Schema", + "description": "Defines how DSC must validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "oneOf": [ + { + "required": [ + "command" + ] + }, + { + "required": [ + "embedded" + ] + } + ], + "properties": { + "command": { + "title": "Instance Schema Command", + "description": "Defines how DSC must call the DSC Resource to get the JSON Schema for validating a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + } + }, + "embedded": { + "title": "Embedded Instance Schema", + "description": "Defines the JSON Schema DSC must use to validate a JSON blob representing an instance of the DSC Resource.", + "type": "object", + "required": [ + "$schema", + "type", + "properties" + ], + "properties": { + "type": { + "title": "Instance Type", + "description": "Defines the JSON type for an instance of the DSC Resource. DSC Resource instances always have the `object` type.", + "const": "object" + }, + "$schema": { + "title": "DSC Resource instance schema dialect", + "description": "Defines which dialect of JSON Schema the DSC Resource is using to validate instances.", + "type": "string", + "format": "uri-reference", + "enum": [ + "https://json-schema.org/draft/2020-12/schema", + "https://json-schema.org/draft/2019-09/schema", + "http://json-schema.org/draft-07/schema#" + ] + }, + "$id": { + "title": "DSC Resource instance schema ID", + "description": "Defines the unique ID for the DSC Resource's instance schema.", + "type": "string", + "format": "uri-reference" + }, + "properties": { + "title": "Instance Properties", + "description": "Defines the schema for the DSC Resource's properties. Must define at least one property.", + "type": "object", + "minProperties": 1, + "unevaluatedProperties": { + "anyOf": [ + { + "$ref": "https://json-schema.org/draft/2020-12/schema" + }, + { + "$ref": "https://json-schema.org/draft/2019-09/schema" + }, + { + "$ref": "http://json-schema.org/draft-07/schema#" + } + ] + }, + "properties": { + "_ensure": { + "title": "Standard Property: _ensure", + "description": "Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json" + } + }, + "_inDesiredState": { + "title": "Standard Property: _inDesiredState", + "description": "Indicates that the DSC Resource returns this value for it's own `test` method. This property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json" + } + }, + "_purge": { + "title": "Standard Property: _purge", + "description": "Indicates that the DSC Resource uses the standard `_purge` property to specify whether the DSC Resource should remove all non-specified members when it manages an array of members or values.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json" + } + }, + "_rebootRequested": { + "title": "Standard property: _rebootRequested", + "description": "Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes.", + "const": { + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json" + } + } + } + } + } + }, + "url": { + "title": "Instance Schema URL", + "description": "Defines the URL to the DSC Resource's JSON schema for integrating tools.", + "type": "string", + "format": "uri" + } + }, + "examples": [ + { + "command": { + "executable": "registry", + "args": [ + "schema" + ] + } + }, + { + "embedded": { + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "OSInfo", + "type": "object", + "required": [], + "properties": { + "$id": { + "type": "string" + }, + "architecture": { + "type": [ + "string", + "null" + ] + }, + "bitness": { + "$ref": "#/definitions/Bitness" + }, + "codename": { + "type": [ + "string", + "null" + ] + }, + "edition": { + "type": [ + "string", + "null" + ] + }, + "family": { + "$ref": "#/definitions/Family" + }, + "version": { + "type": "string" + } + }, + "additionalProperties": false, + "definitions": { + "Bitness": { + "type": "string", + "enum": [ + "32", + "64", + "unknown" + ] + }, + "Family": { + "type": "string", + "enum": [ + "Linux", + "macOS", + "Windows" + ] + } + } + } + } + ] +} diff --git a/schemas/2023/08/resource/manifest.set.json b/schemas/2023/08/resource/manifest.set.json new file mode 100644 index 000000000..37adb350f --- /dev/null +++ b/schemas/2023/08/resource/manifest.set.json @@ -0,0 +1,44 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.set.json", + "title": "Set Method", + "description": "Defines how DSC must call the DSC Resource to set the desired state of an instance and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + }, + "preTest": { + "title": "Resource Performs Pre-Test", + "description": "Defines whether the DSC Resource performs its own test to ensure idempotency when calling the `set` command. Set this value to `true` if the DSC Resource tests input before modifying system state.", + "type": "boolean", + "default": false + }, + "return": { + "description": "Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified.", + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "set" + ], + "input": "stdin", + "preTest": true, + "return": "state" + } + ] +} diff --git a/schemas/2023/08/resource/manifest.test.json b/schemas/2023/08/resource/manifest.test.json new file mode 100644 index 000000000..c503d5704 --- /dev/null +++ b/schemas/2023/08/resource/manifest.test.json @@ -0,0 +1,38 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.test.json", + "title": "Test Method", + "description": "Defines how DSC must call the DSC Resource to test if an instance is in the desired state and how to process the output from the DSC Resource.", + "type": "object", + "required": [ + "executable", + "input" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + }, + "input": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/inputKind.json" + }, + "return": { + "title": "Test Command Return Type", + "description": "Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state.", + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/returnKind.json" + } + }, + "examples": [ + { + "executable": "registry", + "args": [ + "config", + "test" + ], + "input": "stdin", + "return": "state" + } + ] +} diff --git a/schemas/2023/08/resource/manifest.validate.json b/schemas/2023/08/resource/manifest.validate.json new file mode 100644 index 000000000..b646ae487 --- /dev/null +++ b/schemas/2023/08/resource/manifest.validate.json @@ -0,0 +1,27 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/manifest.validate.json", + "title": "Validate Method", + "description": "Defines how DSC must call the DSC Resource to validate the state of an instance. This method is mandatory for DSC Group Resources. It's ignored for all other DSC Resources.", + "type": "object", + "required": [ + "executable" + ], + "properties": { + "executable": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandExecutable.json" + }, + "args": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/commandArgs.json" + } + }, + "examples": [ + { + "executable": "dsc", + "args": [ + "config", + "validate" + ] + } + ] +} diff --git a/schemas/2023/08/resource/properties/ensure.json b/schemas/2023/08/resource/properties/ensure.json new file mode 100644 index 000000000..46575b94f --- /dev/null +++ b/schemas/2023/08/resource/properties/ensure.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/ensure.json", + "title": "Ensure Existence", + "description": "Indicates whether the DSC Resource instance should exist.", + "type": "string", + "enum": [ + "Absent", + "Present" + ] +} diff --git a/schemas/2023/08/resource/properties/inDesiredState.json b/schemas/2023/08/resource/properties/inDesiredState.json new file mode 100644 index 000000000..dcbb3888f --- /dev/null +++ b/schemas/2023/08/resource/properties/inDesiredState.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/inDesiredState.json", + "title": "Instance is in the Desired State", + "description": "Indicates whether the instance is in the desired state. This property is only returned by the `test` method.", + "type": [ + "boolean", + "null" + ], + "readOnly": true +} diff --git a/schemas/2023/08/resource/properties/purge.json b/schemas/2023/08/resource/properties/purge.json new file mode 100644 index 000000000..d91cd908a --- /dev/null +++ b/schemas/2023/08/resource/properties/purge.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/purge.json", + "title": "Purge", + "description": "Indicates that only the components described in the DSC Resource should exist. If other components exist, the DSC Resource is out of the desired state. When enforcing desired state, the DSC Resource removes unmanaged components.", + "type": [ + "boolean", + "null" + ], + "writeOnly": true +} diff --git a/schemas/2023/08/resource/properties/rebootRequested.json b/schemas/2023/08/resource/properties/rebootRequested.json new file mode 100644 index 000000000..3ec4824c4 --- /dev/null +++ b/schemas/2023/08/resource/properties/rebootRequested.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/resource/properties/rebootRequested.json", + "title": "Reboot Requested", + "description": "Indicates that the set operation requires a reboot before it's fully complete.", + "type": [ + "boolean", + "null" + ], + "readOnly": true +} diff --git a/docs/schemas/build.ps1 b/schemas/build.ps1 similarity index 76% rename from docs/schemas/build.ps1 rename to schemas/build.ps1 index 709feaca1..bd0261a2b 100644 --- a/docs/schemas/build.ps1 +++ b/schemas/build.ps1 @@ -8,7 +8,7 @@ using namespace System.Collections [cmdletbinding(DefaultParameterSetName='ByConfig')] param( [string] - $OutputDirectory = "$PSScriptRoot/bundled", + $OutputDirectory = "$PSScriptRoot", [Parameter(ParameterSetName='ByPath')] [string[]] @@ -32,10 +32,27 @@ begin { [Generic.List[Specialized.OrderedDictionary]] $List + [string]$SchemaHost + [string]$SchemaPrefix + [string]$SchemaVersion + LocalJsonSchemaRegistry() { $this.Map = [Specialized.OrderedDictionary]::new() $this.List = [Generic.List[Specialized.OrderedDictionary]]::new() } + + LocalJsonSchemaRegistry( + [string]$SchemaHost, + [string]$SchemaPrefix, + [string]$SchemaVersion + ) { + $this.SchemaHost = $SchemaHost + $this.SchemaPrefix = $SchemaPrefix + $this.SchemaVersion = $SchemaVersion + $this.Map = [Specialized.OrderedDictionary]::new() + $this.List = [Generic.List[Specialized.OrderedDictionary]]::new() + } + } function Remove-JsonSchemaKey { @@ -97,20 +114,19 @@ begin { param( [switch]$WithoutExamples, [switch]$WithoutComments, - [string[]]$SchemaDirectories = @( - "$PSScriptRoot/config" - "$PSScriptRoot/definitions" - "$PSScriptRoot/outputs" - "$PSScriptRoot/resource" - ) + [string[]]$SchemaDirectories = @(), + [string]$SchemaHost = 'https://raw.githubusercontent.com', + [string]$SchemaPrefix = 'PowerShell/DSC/main', + [string]$SchemaVersion = '2023/08' ) begin { - $Info = [LocalJsonSchemaRegistry]::new() + $Info = [LocalJsonSchemaRegistry]::new($SchemaHost, $SchemaPrefix, $SchemaVersion) } process { - Get-ChildItem -Path $SchemaDirectories -Recurse -File -Filter *.yaml + Get-ChildItem -Path $SchemaDirectories -Recurse -File + | Where-Object -Property Extension -in -Value @('.json', '.yaml', '.yml') | ForEach-Object -process { $Schema = Get-Content $_ -Raw | yayaml\ConvertFrom-Yaml if ($AddDocsUrl) { @@ -126,7 +142,7 @@ begin { $Schema = Remove-JsonSchemaKey -Schema $Schema -KeyName 'examples' } if ($SchemaID = $Schema.'$id') { - $SchemaRefID = $SchemaID -replace 'https://schemas.microsoft.com', '' + $SchemaRefID = $SchemaID -replace $SchemaHost, '' $Info.List.Add($Schema) $Info.Map.Add($SchemaID, $Schema) $Info.Map.Add($SchemaRefID, $Schema) @@ -264,6 +280,8 @@ begin { } } + $ID = $Schema.'$id' + $MergedSchema = $Schema | yayaml\ConvertTo-Yaml -Depth 99 | yayaml\ConvertFrom-Yaml $References = Get-JsonSchemaReference -Schema $Schema -SchemaRegistry $SchemaRegistry @@ -276,12 +294,12 @@ begin { foreach ($Reference in $References) { $ReferenceSchema = $SchemaRegistry.Map.$Reference if ($null -eq $ReferenceSchema -and $Reference -match '#\/') { - Write-Verbose "Skipping local reference '$Reference'" + Write-Verbose "$ID`n`tSkipping local reference: '$Reference'" continue } if ($null -eq $ReferenceSchema -or $Reference -match '^https?:\/\/') { - Write-Verbose "Skipping apparent remote reference '$Reference'" + Write-Verbose "$ID`n`tSkipping apparent remote reference: '$Reference'" continue } @@ -342,17 +360,17 @@ begin { foreach ($Reference in $References) { $ReferenceSchema = $SchemaRegistry.Map.$Reference if ($null -eq $ReferenceSchema -and $Reference -match '^#\/') { - Write-Verbose "Skipping local reference '$Reference'" + Write-Verbose "$ID`n`tSkipping local reference: '$Reference'" continue } if ($null -eq $ReferenceSchema) { - Write-Verbose "Skipping apparent remote reference '$Reference'" + Write-Verbose "$ID`n`tSkipping apparent remote reference: '$Reference'" continue } if ($Reference -notin $Schema.'$defs'.Keys) { - Write-Verbose "Adding reference '$Reference' to `$defs" + Write-Verbose "$ID`n`tAdding reference to `$defs: '$Reference'" $MergedSchema.'$defs'.Add($ReferenceSchema.'$id', $ReferenceSchema) } } @@ -392,14 +410,18 @@ begin { $InputObject, [Parameter(Mandatory)] [string] - $BundledName + $BundledName, + [string] + $SchemaHost = 'https://raw.githubusercontent.com', + [string] + $SchemaPrefix = 'PowerShell/DSC/main' ) begin { $ReplaceIDPattern = @( '^' '(' - [regex]::Escape('https://schemas.microsoft.com/dsc/') + [regex]::Escape("$SchemaHost/$SchemaPrefix") '\d+\/\d+\/' ')' '.+\.yaml' @@ -430,15 +452,17 @@ begin { [ValidateSet('Json', 'JsonVSCode', 'Yaml', 'YamlVSCode')] $OutputFormat = @( 'Json' - 'JsonVSCode' - 'Yaml' - 'YamlVSCode' - ) + ), + + [LocalJsonSchemaRegistry] $SchemaRegistry ) begin { $MergeForNormal = $OutputFormat.Where({$_ -notmatch 'VSCode'}).Count -gt 0 $MergeForVSCode = $OutputFormat.Where({$_ -match 'VSCode'}).Count -gt 0 + if (-not (Test-Path -Path $OutputDirectory)) { + $null = New-Item -Path $OutputDirectory -ItemType Directory -Force + } } process { @@ -448,36 +472,45 @@ begin { } $OutputPathPrefix = "$OutputDirectory/$Name" + + $SharedMergeParams = @{ + Path = $ConfigFilePath + SchemaRegistry = $SchemaRegistry + } if ($MergeForNormal) { - $Bundled = Merge-JsonSchema -Path $ConfigFilePath + $Bundled = Merge-JsonSchema @SharedMergeParams | Set-BundledSchemaID -BundledName $Name if ($OutputFormat -contains 'json') { $Bundled | ConvertTo-MergedAndMungedJson + | ForEach-Object { $_ -replace '\r\n', "`n" } | Out-File -FilePath "$OutputPathPrefix.json" } if ($OutputFormat -contains 'yaml') { $Bundled | yayaml\ConvertTo-Yaml -Depth 99 + | ForEach-Object { $_ -replace '\r\n', "`n" } | Out-File -FilePath "$OutputPathPrefix.yaml" } } if ($MergeForVSCode) { - $Bundled = Merge-JsonSchema -Path $ConfigFilePath -ForVSCode + $Bundled = Merge-JsonSchema @SharedMergeParams -ForVSCode | Set-BundledSchemaID -BundledName $Name if ($OutputFormat -contains 'jsonVSCode') { $Bundled | ConvertTo-MergedAndMungedJson + | ForEach-Object { $_ -replace '\r\n', "`n" } | Out-File -FilePath "$OutputPathPrefix.vscode.json" } if ($OutputFormat -contains 'yamlVSCode') { $Bundled | yayaml\ConvertTo-Yaml -Depth 99 + | ForEach-Object { $_ -replace '\r\n', "`n" } | Out-File -FilePath "$OutputPathPrefix.vscode.yaml" -Force:$Force } } @@ -486,73 +519,79 @@ begin { } process { + $Config = Get-Content -Path $PSScriptRoot/schemas.config.yaml | yayaml\ConvertFrom-Yaml + + if (-not $PSBoundParameters.ContainsKey('OutputDirectory')) { + $OutputDirectory = "$PSScriptRoot/$($Config.version)" + } - $Bundles = Get-Content -Path $PSScriptRoot/bundle.config.yaml - | yayaml\ConvertFrom-Yaml - | ForEach-Object -Process { $_.bundle_schemas } - | ForEach-Object -Process { - [hashtable]$Bundle = $_ - $Bundle.ConfigFilePath = "$PSScriptRoot/$($Bundle.ConfigFilePath)" + if (-not (Test-Path -Path $OutputDirectory)) { + $null = New-Item -Path $OutputDirectory -ItemType Directory -Force + } + + Get-ChildItem -Path $PSScriptRoot/src -Filter *.yaml -Recurse | ForEach-Object -Process { + $SchemaContent = Get-Content -Path $_.FullName -Raw + $SchemaContent = $SchemaContent -replace '', $Config.host + $SchemaContent = $SchemaContent -replace '', $Config.prefix + $SchemaContent = $SchemaContent -replace '', $Config.version + $SchemaContent = $SchemaContent -replace '(?m)\.yaml$"?,?', '.json' + $SchemaPath = $_.FullName -replace 'src', $Config.version + $SchemaFolder = Split-Path -Parent $SchemaPath + if (-not (Test-Path -Path ($SchemaFolder))) { + $null = New-Item -Path $SchemaFolder -ItemType Directory -Force + } + + $SchemaContent + | yayaml\ConvertFrom-Yaml + | ConvertTo-Json -Depth 99 + | ForEach-Object { $_ -replace '\r\n', "`n" } + | Out-File -FilePath ($SchemaPath -replace '\.yaml$', '.json') -Force + } + + $RegistryParameters = @{ + SchemaDirectories = @( + "$OutputDirectory/config" + "$OutputDirectory/definitions" + "$OutputDirectory/outputs" + "$OutputDirectory/resource" + ) + SchemaHost = $Config.host + SchemaPrefix = $Config.prefix + SchemaVersion = $Config.version + WithoutExamples = $true + WithoutComments = $true + } + $SchemaRegistry = Get-LocalJsonSchemaRegistry @RegistryParameters + + $SchemaRegistry + + $Bundles = $Config.bundle_schemas | ForEach-Object -Process { + [hashtable]$Bundle = $_ + $Bundle.ConfigFilePath = "$OutputDirectory/$($Bundle.ConfigFilePath)" $Bundle } - if ($ConfigFilePath.Count -ne 0) { + if ($Bundles.Count -eq 0) { $Bundles = @( - { ConfigFilePath = "$PSScriptRoot/config/document.yaml" } - { ConfigFilePath = "$PSScriptRoot/resource/manifest.yaml" } + { ConfigFilePath = "$OutputDirectory/config/document.json" } + { ConfigFilePath = "$OutputDirectory/resource/manifest.json" } ) } foreach ($BundleToExport in $Bundles) { if ($null -eq $BundleToExport.OutputDirectory) { - $BundleToExport.OutputDirectory = $OutputDirectory + $BundleToExport.OutputDirectory = "$OutputDirectory/bundled" + } else { + $BundleToExport.OutputDirectory = "$OutputDirectory/$($BundleToExport.OutputDirectory)" } if ($null -eq $BundleToExport.OutputFormat) { $BundleToExport.OutputFormat = $OutputFormat } - - # $ExportParameters = @{ - # ConfigFilePath = $ConfigFile - # OutputDirectory = $OutputDirectory - # OutputFormat = $OutputFormat - # } Write-Verbose "Exporting: $($BundleToExport | ConvertTo-Json)" - Export-MergedJsonSchema @BundleToExport -ErrorAction Stop - - # $ConfigFileInfo = Get-Item -Path $ConfigFile - # $OutputPathPrefix = "$OutputDirectory/$($ConfigFileInfo.BaseName)" - - # if ($MergeForNormal) { - # $Bundled = Merge-JsonSchema -Path $ConfigFile - - # if ($OutputFormat -contains 'json') { - # ($Bundled | ConvertTo-Json -Depth 99) -replace '\b(\w+\.)yaml', '$1json' - # | Out-File -FilePath "$OutputPathPrefix.json" - # } - - # if ($OutputFormat -contains 'yaml') { - # $Bundled - # | yayaml\ConvertTo-Yaml -Depth 99 - # | Out-File -FilePath "$OutputPathPrefix.yaml" - # } - # } - # if ($MergeForVSCode) { - # $Bundled = Merge-JsonSchema -Path $ConfigFile -ForVSCode - - # if ($OutputFormat -contains 'jsonVSCode') { - # ($Bundled | ConvertTo-Json -Depth 99) -replace '\b(\w+\.)yaml', '$1json' - # | Out-File -FilePath "$OutputPathPrefix.vscode.json" - # } - - # if ($OutputFormat -contains 'yamlVSCode') { - # $Bundled - # | yayaml\ConvertTo-Yaml -Depth 99 - # | Out-File -FilePath "$OutputPathPrefix.vscode.yaml" -Force:$Force - # } - # } + Export-MergedJsonSchema @BundleToExport -SchemaRegistry $SchemaRegistry -ErrorAction Stop } } end { -} \ No newline at end of file +} diff --git a/schemas/examples/foo.dsc.resource.json b/schemas/examples/foo.dsc.resource.json new file mode 100644 index 000000000..e0a2361c3 --- /dev/null +++ b/schemas/examples/foo.dsc.resource.json @@ -0,0 +1,40 @@ +{ + "$schema": "../2023/08/bundled/resource.manifest.vscode.json", + "type": "Example/Resource", + "description": "An example resource using the schema.", + "version": "0.1.0", + "tags": [ + "Example" + ], + "manifestVersion": "1.0.0", + "get": { + "executable": "foo", + "args": [ + "get" + ], + "input": "stdin" + }, + "set": { + "executable": "foo", + "args": [ + "set" + ], + "input": "stdin", + "preTest": false, + "return": "state" + }, + "schema": { + "embedded": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "bar": { + "type": "string" + }, + "baz": { + "type": "integer" + } + } + } + } +} diff --git a/schemas/examples/foo.dsc.resource.yaml b/schemas/examples/foo.dsc.resource.yaml new file mode 100644 index 000000000..1c35b9225 --- /dev/null +++ b/schemas/examples/foo.dsc.resource.yaml @@ -0,0 +1,20 @@ +# For testing outside of the repository, set the schema in the yaml server directive to: +# https://raw.githubusercontent.com/PowerShell/DSC/main/2023/08/resource/manifest.json +# +# yaml-language-server: $schema=../2023/08/bundled/resource.manifest.vscode.json +manifestVersion: 1.0.0 +type: Example/Foo +version: 0.1.0 +description: An example resource to manage the foo application. +tags: + - foo +get: + executable: foo + args: + - get + input: stdin +set: + executable: foo + input: stdin + preTest: false + return: state diff --git a/schemas/schemas.config.yaml b/schemas/schemas.config.yaml new file mode 100644 index 000000000..6b8404117 --- /dev/null +++ b/schemas/schemas.config.yaml @@ -0,0 +1,61 @@ +host: https://raw.githubusercontent.com +prefix: PowerShell/DSC/main/schemas +version: 2023/08 +bundle_schemas: + # Resource manifest bundle + - ConfigFilePath: resource/manifest.json + Name: manifest + OutputDirectory: bundled/resource + OutputFormat: ['Json', 'JsonVSCode'] + + # Configuration document bundle + - ConfigFilePath: config/document.json + Name: document + OutputDirectory: bundled/config + OutputFormat: ['Json', 'JsonVSCode'] + + # Output schema bundles + - ConfigFilePath: outputs/schema.json + Name: schema + OutputDirectory: bundled/outputs + OutputFormat: ['Json'] + + - ConfigFilePath: outputs/config/get.json + Name: get + OutputDirectory: bundled/outputs/config + OutputFormat: ['Json'] + + - ConfigFilePath: outputs/config/set.json + Name: set + OutputDirectory: bundled/outputs/config + OutputFormat: ['Json'] + + - ConfigFilePath: outputs/config/test.json + Name: test + OutputDirectory: bundled/outputs/config + OutputFormat: ['Json'] + + - ConfigFilePath: outputs/resource/get.json + Name: get + OutputDirectory: bundled/outputs/resource + OutputFormat: ['Json'] + + - ConfigFilePath: outputs/resource/list.json + Name: list + OutputDirectory: bundled/outputs/resource + OutputFormat: ['Json'] + + - ConfigFilePath: outputs/resource/schema.json + Name: schema + OutputDirectory: bundled/outputs/resource + OutputFormat: ['Json'] + + - ConfigFilePath: outputs/resource/set.json + Name: set + OutputDirectory: bundled/outputs/resource + OutputFormat: ['Json'] + + - ConfigFilePath: outputs/resource/test.json + Name: test + OutputDirectory: bundled/outputs/resource + OutputFormat: ['Json'] diff --git a/docs/schemas/config/document.parameter.yaml b/schemas/src/config/document.parameter.yaml similarity index 89% rename from docs/schemas/config/document.parameter.yaml rename to schemas/src/config/document.parameter.yaml index 61976b8b7..892edaa62 100644 --- a/docs/schemas/config/document.parameter.yaml +++ b/schemas/src/config/document.parameter.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/config/document.parameter.yaml +$id: ///config/document.parameter.yaml title: Parameter description: Defines a runtime option for a DSC Configuration Document. @@ -9,12 +9,12 @@ required: - type properties: type: - $ref: /dsc/2023/07/definitions/parameters/dataTypes.yaml + $ref: ///definitions/parameters/dataTypes.yaml defaultValue: title: Default value description: >- Defines the default value for the parameter. - $ref: /dsc/2023/07/definitions/parameters/validValueTypes.yaml + $ref: ///definitions/parameters/validValueTypes.yaml allowedValues: title: Allowed values description: >- @@ -22,7 +22,7 @@ properties: parameter is defined with any other values, it's invalid. type: array items: - $ref: /dsc/2023/07/definitions/parameters/validValueTypes.yaml + $ref: ///definitions/parameters/validValueTypes.yaml description: title: Parameter description description: >- diff --git a/docs/schemas/config/document.resource.yaml b/schemas/src/config/document.resource.yaml similarity index 83% rename from docs/schemas/config/document.resource.yaml rename to schemas/src/config/document.resource.yaml index b14b604de..f2eb57c93 100644 --- a/docs/schemas/config/document.resource.yaml +++ b/schemas/src/config/document.resource.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/config/document.resource.yaml +$id: ///config/document.resource.yaml title: DSC Resource instance type: object @@ -9,9 +9,9 @@ required: - name properties: type: - $ref: /dsc/2023/07/definitions/resourceType.yaml + $ref: ///definitions/resourceType.yaml name: - $ref: /dsc/2023/07/definitions/instanceName.yaml + $ref: ///definitions/instanceName.yaml dependsOn: title: Instance depends on description: >- diff --git a/docs/schemas/config/document.yaml b/schemas/src/config/document.yaml similarity index 85% rename from docs/schemas/config/document.yaml rename to schemas/src/config/document.yaml index a4320a797..373a6a47f 100644 --- a/docs/schemas/config/document.yaml +++ b/schemas/src/config/document.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/config/document.yaml +$id: ///config/document.yaml title: DSC Configuration Document schema description: >- @@ -19,7 +19,7 @@ properties: type: string format: uri enum: - - https://schemas.microsoft.com/dsc/2023/07/config/document.yaml + - ///config/document.yaml parameters: title: DSC Configuration document parameters @@ -29,7 +29,7 @@ properties: configuration. type: object additionalProperties: - $ref: /dsc/2023/07/config/document.parameters.yaml + $ref: ///config/document.parameter.yaml variables: title: Configuration variables @@ -46,7 +46,7 @@ properties: type: array minItems: 1 items: - $ref: /dsc/2023/07/config/document.resource.yaml + $ref: ///config/document.resource.yaml metadata: title: Configuration metadata diff --git a/docs/schemas/definitions/commandArgs.yaml b/schemas/src/definitions/commandArgs.yaml similarity index 76% rename from docs/schemas/definitions/commandArgs.yaml rename to schemas/src/definitions/commandArgs.yaml index 4d8a6f170..815f746ab 100644 --- a/docs/schemas/definitions/commandArgs.yaml +++ b/schemas/src/definitions/commandArgs.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandArgs.yaml +$id: ///definitions/commandArgs.yaml title: Executable Command Arguments description: >- diff --git a/docs/schemas/definitions/commandExecutable.yaml b/schemas/src/definitions/commandExecutable.yaml similarity index 72% rename from docs/schemas/definitions/commandExecutable.yaml rename to schemas/src/definitions/commandExecutable.yaml index e6e1da717..18f8c3b69 100644 --- a/docs/schemas/definitions/commandExecutable.yaml +++ b/schemas/src/definitions/commandExecutable.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/definitions/commandExecutable.yaml +$id: ///definitions/commandExecutable.yaml title: Executable Command Name description: >- diff --git a/docs/schemas/definitions/hadErrors.yaml b/schemas/src/definitions/hadErrors.yaml similarity index 77% rename from docs/schemas/definitions/hadErrors.yaml rename to schemas/src/definitions/hadErrors.yaml index 02979d065..f5ab2b407 100644 --- a/docs/schemas/definitions/hadErrors.yaml +++ b/schemas/src/definitions/hadErrors.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/definitions/hadErrors.yaml +$id: ///definitions/hadErrors.yaml title: Had Errors description: >- diff --git a/docs/schemas/definitions/inputKind.yaml b/schemas/src/definitions/inputKind.yaml similarity index 80% rename from docs/schemas/definitions/inputKind.yaml rename to schemas/src/definitions/inputKind.yaml index be7d7f6dd..f907d2160 100644 --- a/docs/schemas/definitions/inputKind.yaml +++ b/schemas/src/definitions/inputKind.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/definitions/inputKind.yaml +$id: ///definitions/inputKind.yaml title: Executable Command Input Type description: >- diff --git a/docs/schemas/definitions/instanceName.yaml b/schemas/src/definitions/instanceName.yaml similarity index 78% rename from docs/schemas/definitions/instanceName.yaml rename to schemas/src/definitions/instanceName.yaml index b99ec13a9..82710e233 100644 --- a/docs/schemas/definitions/instanceName.yaml +++ b/schemas/src/definitions/instanceName.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/definitions/instanceName.yaml +$id: ///definitions/instanceName.yaml title: Instance name description: >- diff --git a/docs/schemas/definitions/message.yaml b/schemas/src/definitions/message.yaml similarity index 87% rename from docs/schemas/definitions/message.yaml rename to schemas/src/definitions/message.yaml index ccb43e16d..249bbc26f 100644 --- a/docs/schemas/definitions/message.yaml +++ b/schemas/src/definitions/message.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/definitions/message.yaml +$id: ///definitions/message.yaml title: Message description: >- @@ -20,7 +20,7 @@ properties: as defined in the DSC Configuration Document. type: string type: - $ref: /dsc/2023/07/definitions/resourceType.yaml + $ref: ///definitions/resourceType.yaml message: title: Message content description: >- diff --git a/docs/schemas/definitions/messages.yaml b/schemas/src/definitions/messages.yaml similarity index 69% rename from docs/schemas/definitions/messages.yaml rename to schemas/src/definitions/messages.yaml index 7d14142a2..24663794f 100644 --- a/docs/schemas/definitions/messages.yaml +++ b/schemas/src/definitions/messages.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/definitions/messages.yaml +$id: ///definitions/messages.yaml title: Messages description: >- @@ -9,4 +9,4 @@ description: >- type: array items: - $ref: /dsc/2023/07/definitions/message.yaml + $ref: ///definitions/message.yaml diff --git a/docs/schemas/definitions/parameters/dataTypes.yaml b/schemas/src/definitions/parameters/dataTypes.yaml similarity index 78% rename from docs/schemas/definitions/parameters/dataTypes.yaml rename to schemas/src/definitions/parameters/dataTypes.yaml index db8a0c28b..0f8715a5a 100644 --- a/docs/schemas/definitions/parameters/dataTypes.yaml +++ b/schemas/src/definitions/parameters/dataTypes.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/dataTypes.yaml +$id: ///definitions/parameters/dataTypes.yaml title: Data Types description: >- diff --git a/docs/schemas/definitions/parameters/validValueTypes.yaml b/schemas/src/definitions/parameters/validValueTypes.yaml similarity index 83% rename from docs/schemas/definitions/parameters/validValueTypes.yaml rename to schemas/src/definitions/parameters/validValueTypes.yaml index e56f91ede..d6419fdef 100644 --- a/docs/schemas/definitions/parameters/validValueTypes.yaml +++ b/schemas/src/definitions/parameters/validValueTypes.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/definitions/parameters/validValueTypes.yaml +$id: ///definitions/parameters/validValueTypes.yaml $comment: | This schema fragment makes it a little easier to compose the valid properties diff --git a/docs/schemas/definitions/resourceType.yaml b/schemas/src/definitions/resourceType.yaml similarity index 84% rename from docs/schemas/definitions/resourceType.yaml rename to schemas/src/definitions/resourceType.yaml index 5f39f0f00..cd6fdc0f6 100644 --- a/docs/schemas/definitions/resourceType.yaml +++ b/schemas/src/definitions/resourceType.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/definitions/resourceType.yaml +$id: ///definitions/resourceType.yaml title: DSC Resource fully qualified type name description: | diff --git a/docs/schemas/definitions/returnKind.yaml b/schemas/src/definitions/returnKind.yaml similarity index 86% rename from docs/schemas/definitions/returnKind.yaml rename to schemas/src/definitions/returnKind.yaml index 98b5ca974..30085de24 100644 --- a/docs/schemas/definitions/returnKind.yaml +++ b/schemas/src/definitions/returnKind.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/definitions/returnKind.yaml +$id: ///definitions/returnKind.yaml title: Return Kind type: string diff --git a/docs/schemas/definitions/semver.yaml b/schemas/src/definitions/semver.yaml similarity index 93% rename from docs/schemas/definitions/semver.yaml rename to schemas/src/definitions/semver.yaml index 73f05f013..36ad62280 100644 --- a/docs/schemas/definitions/semver.yaml +++ b/schemas/src/definitions/semver.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/definitions/semver.yaml +$id: ///definitions/semver.yaml type: string title: Semantic Version diff --git a/docs/schemas/outputs/config/get.yaml b/schemas/src/outputs/config/get.yaml similarity index 67% rename from docs/schemas/outputs/config/get.yaml rename to schemas/src/outputs/config/get.yaml index ad3e7afc1..491d0b785 100644 --- a/docs/schemas/outputs/config/get.yaml +++ b/schemas/src/outputs/config/get.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/results/config/get.yaml +$id: ///outputs/config/get.yaml title: DSC Configuration get command result description: >- @@ -27,12 +27,12 @@ properties: - result properties: name: - $ref: /dsc/2023/07/definitions/instanceName.yaml + $ref: ///definitions/instanceName.yaml type: - $ref: /dsc/2023/07/definitions/resourceType.yaml + $ref: ///definitions/resourceType.yaml result: - $ref: /dsc/2023/07/results/resource/get.yaml + $ref: ///results/resource/get.yaml messages: - $ref: /dsc/2023/07/definitions/messages.yaml + $ref: ///definitions/messages.yaml hadErrors: - $ref: /dsc/2023/07/definitions/hadErrors.yaml + $ref: ///definitions/hadErrors.yaml diff --git a/docs/schemas/outputs/config/set.yaml b/schemas/src/outputs/config/set.yaml similarity index 67% rename from docs/schemas/outputs/config/set.yaml rename to schemas/src/outputs/config/set.yaml index 53973ff44..d6e97abea 100644 --- a/docs/schemas/outputs/config/set.yaml +++ b/schemas/src/outputs/config/set.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/results/config/set.yaml +$id: ///outputs/config/set.yaml title: DSC Configuration set command result description: >- @@ -27,12 +27,12 @@ properties: - result properties: name: - $ref: /dsc/2023/07/definitions/instanceName.yaml + $ref: ///definitions/instanceName.yaml type: - $ref: /dsc/2023/07/definitions/resourceType.yaml + $ref: ///definitions/resourceType.yaml result: - $ref: /dsc/2023/07/results/resource/set.yaml + $ref: ///results/resource/set.yaml messages: - $ref: /dsc/2023/07/definitions/messages.yaml + $ref: ///definitions/messages.yaml hadErrors: - $ref: /dsc/2023/07/definitions/hadErrors.yaml + $ref: ///definitions/hadErrors.yaml diff --git a/docs/schemas/outputs/config/test.yaml b/schemas/src/outputs/config/test.yaml similarity index 67% rename from docs/schemas/outputs/config/test.yaml rename to schemas/src/outputs/config/test.yaml index f8c4256dd..ba79b7402 100644 --- a/docs/schemas/outputs/config/test.yaml +++ b/schemas/src/outputs/config/test.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/results/config/test.yaml +$id: ///outputs/config/test.yaml title: DSC Configuration test command result description: >- @@ -27,12 +27,12 @@ properties: - result properties: name: - $ref: /dsc/2023/07/definitions/instanceName.yaml + $ref: ///definitions/instanceName.yaml type: - $ref: /dsc/2023/07/definitions/resourceType.yaml + $ref: ///definitions/resourceType.yaml result: - $ref: /dsc/2023/07/results/resource/test.yaml + $ref: ///results/resource/test.yaml messages: - $ref: /dsc/2023/07/definitions/messages.yaml + $ref: ///definitions/messages.yaml hadErrors: - $ref: /dsc/2023/07/definitions/hadErrors.yaml + $ref: ///definitions/hadErrors.yaml diff --git a/docs/schemas/outputs/resource/get.yaml b/schemas/src/outputs/resource/get.yaml similarity index 88% rename from docs/schemas/outputs/resource/get.yaml rename to schemas/src/outputs/resource/get.yaml index 2cc1c9a90..831043855 100644 --- a/docs/schemas/outputs/resource/get.yaml +++ b/schemas/src/outputs/resource/get.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/results/resource/get.yaml +$id: ///outputs/resource/get.yaml title: dsc resource get result description: >- diff --git a/docs/schemas/outputs/resource/list.yaml b/schemas/src/outputs/resource/list.yaml similarity index 90% rename from docs/schemas/outputs/resource/list.yaml rename to schemas/src/outputs/resource/list.yaml index 77511b54a..f6a09bc9d 100644 --- a/docs/schemas/outputs/resource/list.yaml +++ b/schemas/src/outputs/resource/list.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/results/resource/list.yaml +$id: ///outputs/resource/list.yaml title: dsc resource list result description: >- @@ -14,10 +14,10 @@ properties: # resources don't follow that pattern - their type name is just a name, # no prefix. Should we have a different schema for those, or should this # be relaxed? - $ref: /dsc/2023/07/definitions/resourceType.yaml + $ref: ///definitions/resourceType.yaml version: # Only the Test* resources seem to have this field populated. - $ref: /dsc/2023/07/definitions/semver.yaml + $ref: ///definitions/semver.yaml description: title: Resource Description description: >- @@ -87,7 +87,7 @@ properties: Defines the fully qualified type name of the DSC Resource Provider the DSC Resource depends on. oneOf: - - $ref: /dsc/2023/07/definitions/resourceType.yaml + - $ref: ///definitions/resourceType.yaml - type: 'null' manifest: - $ref: /dsc/2023/07/resource/manifest.yaml \ No newline at end of file + $ref: ///resource/manifest.yaml \ No newline at end of file diff --git a/docs/schemas/outputs/resource/schema.yaml b/schemas/src/outputs/resource/schema.yaml similarity index 81% rename from docs/schemas/outputs/resource/schema.yaml rename to schemas/src/outputs/resource/schema.yaml index c37702908..d010ff516 100644 --- a/docs/schemas/outputs/resource/schema.yaml +++ b/schemas/src/outputs/resource/schema.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/results/resource/schema.yaml +$id: ///outputs/resource/schema.yaml title: DSC Resource schema result description: >- diff --git a/docs/schemas/outputs/resource/set.yaml b/schemas/src/outputs/resource/set.yaml similarity index 94% rename from docs/schemas/outputs/resource/set.yaml rename to schemas/src/outputs/resource/set.yaml index 27410b8a1..1e4751a90 100644 --- a/docs/schemas/outputs/resource/set.yaml +++ b/schemas/src/outputs/resource/set.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/results/resource/set.yaml +$id: ///outputs/resource/set.yaml title: dsc resource set result description: >- diff --git a/docs/schemas/outputs/resource/test.yaml b/schemas/src/outputs/resource/test.yaml similarity index 94% rename from docs/schemas/outputs/resource/test.yaml rename to schemas/src/outputs/resource/test.yaml index fdd8a70d9..de0cb5503 100644 --- a/docs/schemas/outputs/resource/test.yaml +++ b/schemas/src/outputs/resource/test.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/results/resource/test.yaml +$id: ///outputs/resource/test.yaml title: dsc resource test result description: >- diff --git a/docs/schemas/outputs/schema.yaml b/schemas/src/outputs/schema.yaml similarity index 82% rename from docs/schemas/outputs/schema.yaml rename to schemas/src/outputs/schema.yaml index a4260c636..dd4d9a8ef 100644 --- a/docs/schemas/outputs/schema.yaml +++ b/schemas/src/outputs/schema.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/results/schema.yaml +$id: ///outputs/schema.yaml title: DSC Resource schema result description: >- diff --git a/docs/schemas/resource/manifest.get.yaml b/schemas/src/resource/manifest.get.yaml similarity index 65% rename from docs/schemas/resource/manifest.get.yaml rename to schemas/src/resource/manifest.get.yaml index c0ad3be13..fd10844cf 100644 --- a/docs/schemas/resource/manifest.get.yaml +++ b/schemas/src/resource/manifest.get.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.get.yaml +$id: ///resource/manifest.get.yaml title: Get Method description: >- @@ -12,11 +12,11 @@ required: - executable properties: executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml + $ref: ///definitions/commandExecutable.yaml args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml + $ref: ///definitions/commandArgs.yaml input: - $ref: /dsc/2023/07/definitions/inputKind.yaml + $ref: ///definitions/inputKind.yaml examples: - executable: registry diff --git a/docs/schemas/resource/manifest.provider.yaml b/schemas/src/resource/manifest.provider.yaml similarity index 85% rename from docs/schemas/resource/manifest.provider.yaml rename to schemas/src/resource/manifest.provider.yaml index 9c8b5fe1f..a79b96acf 100644 --- a/docs/schemas/resource/manifest.provider.yaml +++ b/schemas/src/resource/manifest.provider.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.provider.yaml +$id: ///resource/manifest.provider.yaml title: Provider description: >- @@ -23,9 +23,9 @@ properties: - executable properties: executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml + $ref: ///definitions/commandExecutable.yaml args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml + $ref: ///definitions/commandArgs.yaml config: title: Expected Configuration description: >- diff --git a/docs/schemas/resource/manifest.schema.yaml b/schemas/src/resource/manifest.schema.yaml similarity index 90% rename from docs/schemas/resource/manifest.schema.yaml rename to schemas/src/resource/manifest.schema.yaml index 784cfaf41..76b4144e6 100644 --- a/docs/schemas/resource/manifest.schema.yaml +++ b/schemas/src/resource/manifest.schema.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.schema.yaml +$id: ///resource/manifest.schema.yaml title: Instance Schema description: >- @@ -27,9 +27,9 @@ properties: - executable properties: executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml + $ref: ///definitions/commandExecutable.yaml args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml + $ref: ///definitions/commandArgs.yaml embedded: title: Embedded Instance Schema description: >- @@ -88,7 +88,7 @@ properties: Indicates that the DSC Resource uses the standard `_ensure` property to specify whether an instance should exist with the `Present` and `Absent` enums. const: - $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.yaml + $ref: ///resource/properties/ensure.yaml _inDesiredState: title: 'Standard Property: _inDesiredState' description: >- @@ -96,7 +96,7 @@ properties: property is mandatory when the manifest defines the `test` property. It shouldn't be included if the DSC Resource relies on DSC's synthetic testing. const: - $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.yaml + $ref: ///resource/properties/inDesiredState.yaml _purge: title: 'Standard Property: _purge' description: >- @@ -104,14 +104,14 @@ properties: whether the DSC Resource should remove all non-specified members when it manages an array of members or values. const: - $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.yaml + $ref: ///resource/properties/purge.yaml _rebootRequested: title: 'Standard property: _rebootRequested' description: >- Indicates that the DSC Resource uses the standard `_rebootRequested` property to report whether the machine should be rebooted after the `set` method executes. const: - $ref: https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.yaml + $ref: ///resource/properties/rebootRequested.yaml url: title: Instance Schema URL description: >- diff --git a/docs/schemas/resource/manifest.set.yaml b/schemas/src/resource/manifest.set.yaml similarity index 77% rename from docs/schemas/resource/manifest.set.yaml rename to schemas/src/resource/manifest.set.yaml index 8f8852b54..f6684d1f1 100644 --- a/docs/schemas/resource/manifest.set.yaml +++ b/schemas/src/resource/manifest.set.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.set.yaml +$id: ///resource/manifest.set.yaml title: Set Method description: >- @@ -13,11 +13,11 @@ required: - input properties: executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml + $ref: ///definitions/commandExecutable.yaml args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml + $ref: ///definitions/commandArgs.yaml input: - $ref: /dsc/2023/07/definitions/inputKind.yaml + $ref: ///definitions/inputKind.yaml preTest: title: Resource Performs Pre-Test description: >- @@ -31,7 +31,7 @@ properties: Defines whether the command returns a JSON blob of the DSC Resource's state after the set operation or the state and an array of the properties the DSC Resource modified. - $ref: /dsc/2023/07/definitions/returnKind.yaml + $ref: ///definitions/returnKind.yaml examples: - executable: registry diff --git a/docs/schemas/resource/manifest.test.yaml b/schemas/src/resource/manifest.test.yaml similarity index 71% rename from docs/schemas/resource/manifest.test.yaml rename to schemas/src/resource/manifest.test.yaml index e26d22503..3796aaed4 100644 --- a/docs/schemas/resource/manifest.test.yaml +++ b/schemas/src/resource/manifest.test.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.test.yaml +$id: ///resource/manifest.test.yaml title: Test Method description: >- @@ -13,17 +13,17 @@ required: - input properties: executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml + $ref: ///definitions/commandExecutable.yaml args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml + $ref: ///definitions/commandArgs.yaml input: - $ref: /dsc/2023/07/definitions/inputKind.yaml + $ref: ///definitions/inputKind.yaml return: title: Test Command Return Type description: >- Defines whether the command returns a JSON blob of the DSC Resource's current state or the state and an array of the properties that are out of the desired state. - $ref: /dsc/2023/07/definitions/returnKind.yaml + $ref: ///definitions/returnKind.yaml examples: - executable: registry diff --git a/docs/schemas/resource/manifest.validate.yaml b/schemas/src/resource/manifest.validate.yaml similarity index 71% rename from docs/schemas/resource/manifest.validate.yaml rename to schemas/src/resource/manifest.validate.yaml index c270b03d3..34b439700 100644 --- a/docs/schemas/resource/manifest.validate.yaml +++ b/schemas/src/resource/manifest.validate.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.validate.yaml +$id: ///resource/manifest.validate.yaml title: Validate Method description: >- @@ -12,9 +12,9 @@ required: - executable properties: executable: - $ref: /dsc/2023/07/definitions/commandExecutable.yaml + $ref: ///definitions/commandExecutable.yaml args: - $ref: /dsc/2023/07/definitions/commandArgs.yaml + $ref: ///definitions/commandArgs.yaml examples: - executable: dsc diff --git a/docs/schemas/resource/manifest.yaml b/schemas/src/resource/manifest.yaml similarity index 78% rename from docs/schemas/resource/manifest.yaml rename to schemas/src/resource/manifest.yaml index c49a9c1d3..a6d80959c 100644 --- a/docs/schemas/resource/manifest.yaml +++ b/schemas/src/resource/manifest.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/resource/manifest.yaml +$id: ///resource/manifest.yaml title: Command-based DSC Resource Manifest description: >- @@ -18,18 +18,18 @@ properties: description: >- The semver of the DSC Resource manifest schema to validate this manifest with. - $ref: /dsc/2023/07/definitions/semver.yaml + $ref: ///definitions/semver.yaml enums: - '1.0' type: - $ref: /dsc/2023/07/definitions/resourceType.yaml + $ref: ///definitions/resourceType.yaml version: title: Resource Semantic Version description: >- The semantic version (semver) of the DSC Resource. This version identifies the DSC Resource, not the version of the application it manages. - $ref: /dsc/2023/07/definitions/semver.yaml + $ref: ///definitions/semver.yaml description: title: Resource Description description: >- @@ -46,16 +46,16 @@ properties: type: string pattern: ^\w+$ get: - $ref: /dsc/2023/07/resource/manifest.get.yaml + $ref: ///resource/manifest.get.yaml set: - $ref: /dsc/2023/07/resource/manifest.set.yaml + $ref: ///resource/manifest.set.yaml test: - $ref: /dsc/2023/07/resource/manifest.test.yaml + $ref: ///resource/manifest.test.yaml validate: - $ref: /dsc/2023/07/resource/manifest.validate.yaml + $ref: ///resource/manifest.validate.yaml provider: # I'm not clear on how this works in practice - $ref: /dsc/2023/07/resource/manifest.provider.yaml + $ref: ///resource/manifest.provider.yaml exitCodes: # This setting in the root of the schema implies exit codes must have the # same meaning across all executions. What about implementations that @@ -81,4 +81,4 @@ properties: "3": Registry error "4": JSON serialization failed schema: - $ref: /dsc/2023/07/resource/manifest.schema.yaml + $ref: ///resource/manifest.schema.yaml diff --git a/docs/schemas/resource/properties/ensure.yaml b/schemas/src/resource/properties/ensure.yaml similarity index 76% rename from docs/schemas/resource/properties/ensure.yaml rename to schemas/src/resource/properties/ensure.yaml index 03667f7c7..da9c60fd2 100644 --- a/docs/schemas/resource/properties/ensure.yaml +++ b/schemas/src/resource/properties/ensure.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/resource/properties/ensure.yaml +$id: ///resource/properties/ensure.yaml title: Ensure Existence description: >- diff --git a/docs/schemas/resource/properties/inDesiredState.yaml b/schemas/src/resource/properties/inDesiredState.yaml similarity index 79% rename from docs/schemas/resource/properties/inDesiredState.yaml rename to schemas/src/resource/properties/inDesiredState.yaml index 015c43ee3..ec4d9bf64 100644 --- a/docs/schemas/resource/properties/inDesiredState.yaml +++ b/schemas/src/resource/properties/inDesiredState.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/resource/properties/inDesiredState.yaml +$id: ///resource/properties/inDesiredState.yaml title: Instance is in the Desired State description: >- diff --git a/docs/schemas/resource/properties/purge.yaml b/schemas/src/resource/properties/purge.yaml similarity index 84% rename from docs/schemas/resource/properties/purge.yaml rename to schemas/src/resource/properties/purge.yaml index 9168461ee..db99424b4 100644 --- a/docs/schemas/resource/properties/purge.yaml +++ b/schemas/src/resource/properties/purge.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/resource/properties/purge.yaml +$id: ///resource/properties/purge.yaml title: Purge description: >- diff --git a/docs/schemas/resource/properties/rebootRequested.yaml b/schemas/src/resource/properties/rebootRequested.yaml similarity index 76% rename from docs/schemas/resource/properties/rebootRequested.yaml rename to schemas/src/resource/properties/rebootRequested.yaml index 32b173111..013e056d7 100644 --- a/docs/schemas/resource/properties/rebootRequested.yaml +++ b/schemas/src/resource/properties/rebootRequested.yaml @@ -1,6 +1,6 @@ # yaml-language-server: $schema=https://json-schema.org/draft/2020-12/schema $schema: https://json-schema.org/draft/2020-12/schema -$id: https://schemas.microsoft.com/dsc/2023/07/resource/properties/rebootRequested.yaml +$id: ///resource/properties/rebootRequested.yaml title: Reboot Requested description: >- From 5e273ae4cae4796cffe9cf6e1548caa561b3ee87 Mon Sep 17 00:00:00 2001 From: "Mikey Lombardi (He/Him)" Date: Fri, 4 Aug 2023 08:45:37 -0500 Subject: [PATCH 10/11] Apply suggestions from review Co-authored-by: JohnMcPMS --- docs/reference/schemas/config/document.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/reference/schemas/config/document.md b/docs/reference/schemas/config/document.md index 1891f901a..7905cde11 100644 --- a/docs/reference/schemas/config/document.md +++ b/docs/reference/schemas/config/document.md @@ -19,7 +19,7 @@ configuration document uses parameters and variables to pass to a set of one or define a desired state. A configuration document can be defined as either YAML or JSON. For ease of authoring, Microsoft -recommneds drafting configuration documents in YAML. +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`. @@ -116,7 +116,7 @@ in a configuration, see [DSC Configuration resources][06] and ```yaml Type: array -Required: false +Required: true Minimum Item Count: 1 Valid Item Schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json ``` From 0ee8248b617272d2f218320e577e1d8b95e2c80d Mon Sep 17 00:00:00 2001 From: "Mikey Lombardi (He/Him)" Date: Fri, 4 Aug 2023 12:01:55 -0500 Subject: [PATCH 11/11] Apply suggestions from review Fix URI for `$schema` in config document enum --- schemas/2023/08/bundled/config/document.json | 450 ++++++++-------- .../08/bundled/config/document.vscode.json | 486 +++++++++--------- schemas/2023/08/config/document.json | 96 ++-- schemas/src/config/document.yaml | 2 +- 4 files changed, 517 insertions(+), 517 deletions(-) diff --git a/schemas/2023/08/bundled/config/document.json b/schemas/2023/08/bundled/config/document.json index e1d19672f..55b7b4676 100644 --- a/schemas/2023/08/bundled/config/document.json +++ b/schemas/2023/08/bundled/config/document.json @@ -1,226 +1,226 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", - "title": "DSC Configuration Document schema", - "description": "Describes a valid DSC Configuration Document.", - "type": "object", - "required": [ - "$schema", - "resources" - ], - "properties": { - "$schema": { - "title": "Schema", - "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", - "type": "string", - "format": "uri", - "enum": [ - "/PowerShell/DSC/main/schemas/2023/08/config/document.json" - ] - }, - "parameters": { - "title": "DSC Configuration document parameters", - "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", - "type": "object", - "additionalProperties": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" - } - }, - "variables": { - "title": "Configuration variables", - "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", - "type": "object" - }, - "resources": { - "title": "DSC Configuration document resources", - "description": "Defines a list of DSC Resource instances for the configuration to manage.", - "type": "array", - "minItems": 1, - "items": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" - } - }, - "metadata": { - "title": "Configuration metadata", - "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", - "type": "object" - } - }, - "$defs": { - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json", - "title": "Parameter", - "description": "Defines a runtime option for a DSC Configuration Document.", - "type": "object", - "required": "type", - "properties": { - "type": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json" - }, - "defaultValue": { - "title": "Default value", - "description": "Defines the default value for the parameter.", - "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" - }, - "allowedValues": { - "title": "Allowed values", - "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", - "type": "array", - "items": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" - } - }, - "description": { - "title": "Parameter description", - "description": "Defines a synopsis for the parameter explaining its purpose.", - "type": "string" - }, - "metadata": { - "title": "Parameter metadata", - "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", - "type": "object" - } - }, - "allOf": [ - { - "if": { - "properties": { - "type": { - "const": "int" - } - } - }, - "then": { - "minValue": { - "title": "Minimum value", - "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", - "type": "integer" - }, - "maxValue": { - "title": "Maximum value", - "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", - "type": "integer" - } - } - }, - { - "if": { - "oneOf": [ - { - "properties": { - "type": { - "const": "string" - } - } - }, - { - "properties": { - "type": { - "const": "securestring" - } - } - }, - { - "properties": { - "type": { - "const": "array" - } - } - } - ] - }, - "then": { - "minLength": { - "title": "Minimum length", - "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", - "type": "integer", - "minimum": 0 - }, - "maxLength": { - "title": "Maximum length", - "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", - "type": "integer", - "minimum": 0 - } - } - } - ] - }, - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json", - "title": "DSC Resource instance", - "type": "object", - "required": [ - "type", - "name" - ], - "properties": { - "type": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" - }, - "name": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" - }, - "dependsOn": { - "title": "Instance depends on", - "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", - "type": "array", - "items": { - "type": "string", - "uniqueItems": true, - "pattern": "^\\[\\w+(\\.\\w+){0,2}\\/\\w+\\].+$" - } - }, - "properties": { - "title": "Managed instance properties", - "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", - "type": "object" - } - } - }, - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json", - "title": "Data Types", - "description": "Defines the data type for the value.", - "type": "string", - "enum": [ - "string", - "securestring", - "int", - "bool", - "object", - "secureobject", - "array" - ] - }, - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json", - "type": [ - "string", - "integer", - "object", - "array", - "boolean" - ] - }, - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", - "title": "DSC Resource fully qualified type name", - "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", - "type": "string", - "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" - }, - "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", - "title": "Instance name", - "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", - "type": "string" - } - } +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", + "title": "DSC Configuration Document schema", + "description": "Describes a valid DSC Configuration Document.", + "type": "object", + "required": [ + "$schema", + "resources" + ], + "properties": { + "$schema": { + "title": "Schema", + "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" + ] + }, + "parameters": { + "title": "DSC Configuration document parameters", + "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "type": "object", + "additionalProperties": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" + } + }, + "variables": { + "title": "Configuration variables", + "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", + "type": "object" + }, + "resources": { + "title": "DSC Configuration document resources", + "description": "Defines a list of DSC Resource instances for the configuration to manage.", + "type": "array", + "minItems": 1, + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" + } + }, + "metadata": { + "title": "Configuration metadata", + "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", + "type": "object" + } + }, + "$defs": { + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json", + "title": "Parameter", + "description": "Defines a runtime option for a DSC Configuration Document.", + "type": "object", + "required": "type", + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json" + }, + "defaultValue": { + "title": "Default value", + "description": "Defines the default value for the parameter.", + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" + }, + "allowedValues": { + "title": "Allowed values", + "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", + "type": "array", + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" + } + }, + "description": { + "title": "Parameter description", + "description": "Defines a synopsis for the parameter explaining its purpose.", + "type": "string" + }, + "metadata": { + "title": "Parameter metadata", + "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", + "type": "object" + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "minValue": { + "title": "Minimum value", + "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", + "type": "integer" + }, + "maxValue": { + "title": "Maximum value", + "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", + "type": "integer" + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + }, + { + "properties": { + "type": { + "const": "array" + } + } + } + ] + }, + "then": { + "minLength": { + "title": "Minimum length", + "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", + "type": "integer", + "minimum": 0 + }, + "maxLength": { + "title": "Maximum length", + "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", + "type": "integer", + "minimum": 0 + } + } + } + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json", + "title": "DSC Resource instance", + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "name": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "dependsOn": { + "title": "Instance depends on", + "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", + "type": "array", + "items": { + "type": "string", + "uniqueItems": true, + "pattern": "^\\[\\w+(\\.\\w+){0,2}\\/\\w+\\].+$" + } + }, + "properties": { + "title": "Managed instance properties", + "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", + "type": "object" + } + } + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json", + "title": "Data Types", + "description": "Defines the data type for the value.", + "type": "string", + "enum": [ + "string", + "securestring", + "int", + "bool", + "object", + "secureobject", + "array" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json", + "type": [ + "string", + "integer", + "object", + "array", + "boolean" + ] + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" + } + } } diff --git a/schemas/2023/08/bundled/config/document.vscode.json b/schemas/2023/08/bundled/config/document.vscode.json index 7335363de..1006c4d86 100644 --- a/schemas/2023/08/bundled/config/document.vscode.json +++ b/schemas/2023/08/bundled/config/document.vscode.json @@ -1,244 +1,244 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", - "title": "DSC Configuration Document schema", - "description": "Describes a valid DSC Configuration Document.", - "type": "object", - "required": [ - "$schema", - "resources" - ], - "properties": { - "$schema": { - "title": "Schema", - "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", - "type": "string", - "format": "uri", - "enum": [ - "/PowerShell/DSC/main/schemas/2023/08/config/document.json" - ] - }, - "parameters": { - "title": "DSC Configuration document parameters", - "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", - "type": "object", - "additionalProperties": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" - } - }, - "variables": { - "title": "Configuration variables", - "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", - "type": "object" - }, - "resources": { - "title": "DSC Configuration document resources", - "description": "Defines a list of DSC Resource instances for the configuration to manage.", - "type": "array", - "minItems": 1, - "items": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" - } - }, - "metadata": { - "title": "Configuration metadata", - "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", - "type": "object" - } - }, - "$defs": { - "PowerShell": { - "DSC": { - "main": { - "schemas": { - "2023": { - "08": { - "config": { - "document.parameter.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json", - "title": "Parameter", - "description": "Defines a runtime option for a DSC Configuration Document.", - "type": "object", - "required": "type", - "properties": { - "type": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json" - }, - "defaultValue": { - "title": "Default value", - "description": "Defines the default value for the parameter.", - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" - }, - "allowedValues": { - "title": "Allowed values", - "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", - "type": "array", - "items": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" - } - }, - "description": { - "title": "Parameter description", - "description": "Defines a synopsis for the parameter explaining its purpose.", - "type": "string" - }, - "metadata": { - "title": "Parameter metadata", - "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", - "type": "object" - } - }, - "allOf": [ - { - "if": { - "properties": { - "type": { - "const": "int" - } - } - }, - "then": { - "minValue": { - "title": "Minimum value", - "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", - "type": "integer" - }, - "maxValue": { - "title": "Maximum value", - "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", - "type": "integer" - } - } - }, - { - "if": { - "oneOf": [ - { - "properties": { - "type": { - "const": "string" - } - } - }, - { - "properties": { - "type": { - "const": "securestring" - } - } - }, - { - "properties": { - "type": { - "const": "array" - } - } - } - ] - }, - "then": { - "minLength": { - "title": "Minimum length", - "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", - "type": "integer", - "minimum": 0 - }, - "maxLength": { - "title": "Maximum length", - "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", - "type": "integer", - "minimum": 0 - } - } - } - ] - }, - "document.resource.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json", - "title": "DSC Resource instance", - "type": "object", - "required": [ - "type", - "name" - ], - "properties": { - "type": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" - }, - "name": { - "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" - }, - "dependsOn": { - "title": "Instance depends on", - "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", - "type": "array", - "items": { - "type": "string", - "uniqueItems": true, - "pattern": "^\\[\\w+(\\.\\w+){0,2}\\/\\w+\\].+$" - } - }, - "properties": { - "title": "Managed instance properties", - "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", - "type": "object" - } - } - } - }, - "definitions": { - "parameters": { - "dataTypes.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json", - "title": "Data Types", - "description": "Defines the data type for the value.", - "type": "string", - "enum": [ - "string", - "securestring", - "int", - "bool", - "object", - "secureobject", - "array" - ] - }, - "validValueTypes.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json", - "type": [ - "string", - "integer", - "object", - "array", - "boolean" - ] - } - }, - "resourceType.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", - "title": "DSC Resource fully qualified type name", - "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", - "type": "string", - "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" - }, - "instanceName.json": { - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", - "title": "Instance name", - "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", - "type": "string" - } - } - } - } - } - } - } - } - } +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", + "title": "DSC Configuration Document schema", + "description": "Describes a valid DSC Configuration Document.", + "type": "object", + "required": [ + "$schema", + "resources" + ], + "properties": { + "$schema": { + "title": "Schema", + "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" + ] + }, + "parameters": { + "title": "DSC Configuration document parameters", + "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "type": "object", + "additionalProperties": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" + } + }, + "variables": { + "title": "Configuration variables", + "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", + "type": "object" + }, + "resources": { + "title": "DSC Configuration document resources", + "description": "Defines a list of DSC Resource instances for the configuration to manage.", + "type": "array", + "minItems": 1, + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" + } + }, + "metadata": { + "title": "Configuration metadata", + "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", + "type": "object" + } + }, + "$defs": { + "PowerShell": { + "DSC": { + "main": { + "schemas": { + "2023": { + "08": { + "config": { + "document.parameter.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json", + "title": "Parameter", + "description": "Defines a runtime option for a DSC Configuration Document.", + "type": "object", + "required": "type", + "properties": { + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json" + }, + "defaultValue": { + "title": "Default value", + "description": "Defines the default value for the parameter.", + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" + }, + "allowedValues": { + "title": "Allowed values", + "description": "Defines a list of valid values for the parameter. If the parameter is defined with any other values, it's invalid.", + "type": "array", + "items": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json" + } + }, + "description": { + "title": "Parameter description", + "description": "Defines a synopsis for the parameter explaining its purpose.", + "type": "string" + }, + "metadata": { + "title": "Parameter metadata", + "description": "Defines a set of key-value pairs for the parameter. This metadata isn't validated.", + "type": "object" + } + }, + "allOf": [ + { + "if": { + "properties": { + "type": { + "const": "int" + } + } + }, + "then": { + "minValue": { + "title": "Minimum value", + "description": "The minimum valid value for an integer type. If defined with the `maxValue` property, this value must be less than the value of `maxValue`.", + "type": "integer" + }, + "maxValue": { + "title": "Maximum value", + "description": "The maximum valid value for an integer type. If defined with the `minValue` property, this value must be greater than the value of `minValue`.", + "type": "integer" + } + } + }, + { + "if": { + "oneOf": [ + { + "properties": { + "type": { + "const": "string" + } + } + }, + { + "properties": { + "type": { + "const": "securestring" + } + } + }, + { + "properties": { + "type": { + "const": "array" + } + } + } + ] + }, + "then": { + "minLength": { + "title": "Minimum length", + "description": "The minimum valid length for a `string`, `securestring`, or `array`. If defined with the `maxLength` property, this value must be less than the value of `maxLength`.", + "type": "integer", + "minimum": 0 + }, + "maxLength": { + "title": "Maximum length", + "description": "The maximum valid length for a `string`, `securestring`, or `array`. If defined with the `minLength` property, this value must be less than the value of `minLength`.", + "type": "integer", + "minimum": 0 + } + } + } + ] + }, + "document.resource.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json", + "title": "DSC Resource instance", + "type": "object", + "required": [ + "type", + "name" + ], + "properties": { + "type": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json" + }, + "name": { + "$ref": "#/$defs/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json" + }, + "dependsOn": { + "title": "Instance depends on", + "description": "Defines a list of DSC Resource instances that DSC must successfully process before processing this instance. Each value for this property must be the value of another DSC Resource instance's `name` property.", + "type": "array", + "items": { + "type": "string", + "uniqueItems": true, + "pattern": "^\\[\\w+(\\.\\w+){0,2}\\/\\w+\\].+$" + } + }, + "properties": { + "title": "Managed instance properties", + "description": "Defines the properties of the DSC Resource this instance manages. This property's value must be an object. DSC validates the property's value against the DSC Resource's schema.", + "type": "object" + } + } + } + }, + "definitions": { + "parameters": { + "dataTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/dataTypes.json", + "title": "Data Types", + "description": "Defines the data type for the value.", + "type": "string", + "enum": [ + "string", + "securestring", + "int", + "bool", + "object", + "secureobject", + "array" + ] + }, + "validValueTypes.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/parameters/validValueTypes.json", + "type": [ + "string", + "integer", + "object", + "array", + "boolean" + ] + } + }, + "resourceType.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/resourceType.json", + "title": "DSC Resource fully qualified type name", + "description": "The namespaced name of the DSC Resource, using the syntax:\n\nowner[.group][.area]/name\n\nFor example:\n\n - Microsoft.SqlServer/Database\n - Microsoft.SqlServer.Database/User\n", + "type": "string", + "pattern": "^\\w+(\\.\\w+){0,2}\\/\\w+$" + }, + "instanceName.json": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/definitions/instanceName.json", + "title": "Instance name", + "description": "The short, human-readable name for a DSC Resource instance. Must be unique within a DSC Configuration document.", + "type": "string" + } + } + } + } + } + } + } + } + } } diff --git a/schemas/2023/08/config/document.json b/schemas/2023/08/config/document.json index 3be3f9c7e..9b9ba5a30 100644 --- a/schemas/2023/08/config/document.json +++ b/schemas/2023/08/config/document.json @@ -1,49 +1,49 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", - "title": "DSC Configuration Document schema", - "description": "Describes a valid DSC Configuration Document.", - "type": "object", - "required": [ - "$schema", - "resources" - ], - "properties": { - "$schema": { - "title": "Schema", - "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", - "type": "string", - "format": "uri", - "enum": [ - "/PowerShell/DSC/main/schemas/2023/08/config/document.json" - ] - }, - "parameters": { - "title": "DSC Configuration document parameters", - "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", - "type": "object", - "additionalProperties": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" - } - }, - "variables": { - "title": "Configuration variables", - "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", - "type": "object" - }, - "resources": { - "title": "DSC Configuration document resources", - "description": "Defines a list of DSC Resource instances for the configuration to manage.", - "type": "array", - "minItems": 1, - "items": { - "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" - } - }, - "metadata": { - "title": "Configuration metadata", - "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", - "type": "object" - } - } +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json", + "title": "DSC Configuration Document schema", + "description": "Describes a valid DSC Configuration Document.", + "type": "object", + "required": [ + "$schema", + "resources" + ], + "properties": { + "$schema": { + "title": "Schema", + "description": "This property must be the canonical URL of the DSC Configuration Document schema that the document is implemented for.", + "type": "string", + "format": "uri", + "enum": [ + "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json" + ] + }, + "parameters": { + "title": "DSC Configuration document parameters", + "description": "Defines runtime options for the configuration. Users and integrating tools can override use the defined parameters to pass alternate values to the configuration.", + "type": "object", + "additionalProperties": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.parameter.json" + } + }, + "variables": { + "title": "Configuration variables", + "description": "Defines a set of reusable values for the configuration document. The names of this value's properties are the strings used to reference a variable's value.", + "type": "object" + }, + "resources": { + "title": "DSC Configuration document resources", + "description": "Defines a list of DSC Resource instances for the configuration to manage.", + "type": "array", + "minItems": 1, + "items": { + "$ref": "/PowerShell/DSC/main/schemas/2023/08/config/document.resource.json" + } + }, + "metadata": { + "title": "Configuration metadata", + "description": "Defines a set of key-value pairs for the configuration. This metadata isn't validated.", + "type": "object" + } + } } diff --git a/schemas/src/config/document.yaml b/schemas/src/config/document.yaml index 373a6a47f..21cb2e613 100644 --- a/schemas/src/config/document.yaml +++ b/schemas/src/config/document.yaml @@ -19,7 +19,7 @@ properties: type: string format: uri enum: - - ///config/document.yaml + - ///config/document.yaml parameters: title: DSC Configuration document parameters