Add schema for secret

Author: Gijsreyn

schemas/src/extension/manifest.secret.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:     <HOST>/<PREFIX>/<VERSION>/extension/manifest.secret.yaml
+
+title: Secret operation command
+description: >-
+  Defines how DSC must call the DSC extension to retrieve a secret value.
+markdownDescription: | # VS Code only
+  ***
+  [_Online Documentation_][00]
+  ***
+
+  Defines how DSC must call the DSC extension to retrieve a secret value. An
+  extension that defines this field in its manifest has the `secret` capability.
+
+  The secret operation is expected to output a single line to stdout containing
+  the secret text. If the extension outputs no data to stdout, DSC treats it as
+  "no secret returned". If the extension outputs multiple lines, DSC treats that
+  as an error.
+
+  For details about the output format, see
+  [Secret extension operation stdout][01].
+
+  [00]: <DOCS_BASE_URL>/reference/schemas/extension/manifest/secret?<DOCS_VERSION_PIN>
+  [01]: <DOCS_BASE_URL>/reference/schemas/extension/stdout/secret?<DOCS_VERSION_PIN>
+
+type: object
+required:
+  - executable
+properties:
+  executable:
+    $ref: /<PREFIX>/<VERSION>/definitions/commandExecutable.yaml
+    markdownDescription: |
+      ***
+      [_Online Documentation_][01]
+      ***
+
+      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.
+
+      [01]: <DOCS_BASE_URL>/reference/schemas/extension/manifest/secret?<DOCS_VERSION_PIN>#executable
+  args:
+    title: Arguments
+    description: >-
+      Defines an ordered list of arguments to pass to the command.
+    markdownDescription: |
+      ***
+      [_Online Documentation_][01]
+      ***
+
+      Defines an ordered list of arguments to pass to the command. Items can be plain strings or
+      structured entries indicating which argument name should receive the secret name or the vault
+      name.
+
+      DSC expands structured entries as follows:
+
+      - `{ "nameArg": "<flag>" }` expands to `"<flag>", "<secret-name>"`.
+      - `{ "vaultArg": "<flag>" }` expands to `"<flag>", "<vault-name>"` (only when a vault is
+        specified by the caller).
+
+      [01]: <DOCS_BASE_URL>/reference/schemas/extension/manifest/secret?<DOCS_VERSION_PIN>#args
+    type: array
+    items:
+      anyOf:
+        - type: string
+        - type: object
+          additionalProperties: false
+          required:
+            - nameArg
+          properties:
+            nameArg:
+              type: string
+        - type: object
+          additionalProperties: false
+          required:
+            - vaultArg
+          properties:
+            vaultArg:
+              type: string
+
+defaultSnippets: # VS Code only
+  - label: ' Define without arguments'
+    markdownDescription: |
+      Define the `secret` command for the extension when no arguments are required.
+    body:
+      executable: ${2:executable_name}
+  - label: ' Define with arguments (flags + name)'
+    markdownDescription: |-
+      Define the `secret` command where the secret name is passed to a specific flag.
+    body:
+      executable: ${2:executable_name}
+      args:
+        - ${3:--get-secret}
+        - nameArg: ${4:--name}
+  - label: ' Define with arguments (flags + name + vault)'
+    markdownDescription: |-
+      Define the `secret` command where both the secret name and the vault name are passed.
+    body:
+      executable: ${2:executable_name}
+      args:
+        - ${3:--get-secret}
+        - nameArg: ${4:--name}
+        - vaultArg: ${5:--vault}

schemas/src/extension/manifest.yaml

@@ -459,6 +459,8 @@ properties:
         characters are permitted.
   discover:
     $ref: /<PREFIX>/<VERSION>/extension/manifest.discover.yaml
+  secret:
+    $ref: /<PREFIX>/<VERSION>/extension/manifest.secret.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

schemas/src/extension/stdout/secret.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:     <HOST>/<PREFIX>/<VERSION>/extension/stdout/secret.yaml
+
+title: Secret extension operation stdout
+description: >-
+  Represents the secret text returned by a DSC extension for a secret request.
+markdownDescription: | # VS Code only
+  ***
+  [_Online Documentation_][00]
+  ***
+
+  Represents the secret text returned by a DSC extension for a secret request. DSC expects the
+  extension to emit a single line containing only the secret value. An empty output indicates that
+  no secret is available. If multiple lines are emitted, DSC treats it as an error.
+
+  [00]: <DOCS_BASE_URL>/reference/schemas/extension/stdout/secret?<DOCS_VERSION_PIN>
+
+type: string
+minLength: 0