Skip to content

Commit 6fade3e

Browse files
michaeltlombardimichaeltlombardi
committed
Canonicalize registry resource schema
This change prototypes shifting from separately maintained schemas in the `schemas` folder to deriving fully expressed schemas from the Rust structs in the code. Doing so requires using the alpha release of schemars v1, which added support for more easily defining schemas using attributes and supports deriving schemas adhering to the JSON Schema 2020-12 specification. Of particular note are the following changes to the JSON Schema for instances of the registry resource: - Use JSON Schema specification draft 2020-12 instead of draft 07. - Added `title` and `description` for every property as documentation. - Added a regular expression check for `keyPath` to ensure it starts with a valid hive identifier. - Added the `$id` keyword to ensure that users and integrating developers can get a copy of the schema online instead of always calling the command. - Marked the `keyPath` property as required. - Marked the `valueName` property as required _only when_ `valueData` is specified. - Marked the `_metadata` property and its `whatIf` sub-property as read-only. - Defined the default value for the `_exist` property as `true`. In the process of implementing this prototype, this change also addressed a few related challenges: - In order to define longer strings for documentation keywords in the schemas, this change uses the `rust_i18n` library to provide a way to map complex or lengthy strings to key names. This also prepares the project for internationalization and localization, though the change only defines translations for English. - To minimize rework, the struct attributes define the JSON Schema with VS Code's annotation keywords, which enhance the authoring and editing experience in VS Code, but are generally ignored by other tools and libraries. To account for the difference between the canonical (stictly 2020-12 compatible) schema and the enhanced schema this change also: 1. Adds the `--enhanced` option to the `registry schema` command to enable returning the enhanced schema, but default to returning the canonical schema as is current behavior. 1. Defines the `remove_vscode_keywords` function to recursively remove those keywords. While the function is implemented in the registry resource in this prototyping PR, it better belongs in `dsc_lib`. 1. Defines the `get_schema_generator` function to return a generator with the correct settings for canonical and enhanced schemas. In both cases, it no longer adds the `null` type for optional items in the struct to better conform with JSON Schema. In JSON Schema, specifying `null` for a property value is _not_ semantically the same as _not_ specifying the property. For the enhanced schemas, it also uses `definitions` instead of `$defs`, as VS Code doesn't understand retrieving references from `$defs`. This change shows how we can begin to: 1. Define full, enhanced JSON schemas for data types in Rust and export those schemas in both canonical and enhanced variants. 1. Migrate from in-code strings to referencing data keys, making it easier to change documentation and messages without editing the code and preparing the projects for internationalization and localization. 1. Define reusable helpers for the projects to minimize rework. The scope of these changes is limited to the registry project only.
1 parent e97747d commit 6fade3e

File tree

8 files changed

+784
-26
lines changed

8 files changed

+784
-26
lines changed

‎registry/Cargo.lock

Lines changed: 388 additions & 18 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎registry/Cargo.toml

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,11 @@ name = "registry"
33
version = "1.0.0"
44
edition = "2021"
55

6+
[package.metadata.i18n]
7+
available-locales = ["en"]
8+
default-locale = "en"
9+
load-path = "locales"
10+
611
[profile.release]
712
strip = true
813
# optimize for size
@@ -16,9 +21,11 @@ lto = true
1621
[dependencies]
1722
clap = { version = "4.5.20", features = ["derive"] }
1823
crossterm = "0.28.1"
24+
regex = "1.11.0"
1925
registry = "1.2.3"
20-
schemars = "0.8.0"
21-
serde = "1.0.130"
26+
rust-i18n = "3"
27+
schemars = "1.0.0-alpha.15"
28+
serde = { version = "1.0.130", features = ["derive"] }
2229
serde_json = "1.0.68"
2330
thiserror = "1.0.64"
2431
tracing = { version = "0.1.37" }

‎registry/locales/cli.yml

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
_version: 2
2+
cli:
3+
# schema command help
4+
schema:
5+
about:
6+
en: Retrieve JSON schema.
7+
args:
8+
enhanced:
9+
help:
10+
en: Retrieve JSON schema enhanced for VS Code authoring and review.

‎registry/locales/schemas.yml

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
_version: 2
2+
3+
schema:
4+
title:
5+
en: Microsoft.Windows/Registry instance
6+
description:
7+
en: Manages Windows Registry keys and values.
8+
markdownDescription:
9+
en: |-
10+
Each instance of the `Microsoft.Windows/Registry` resource manages a registry key or value.
11+
You can use it to idempotently ensure that a registry key or value exists and set the data
12+
for registry values.
13+
# Properties
14+
keyPath:
15+
title:
16+
en: Registry key path
17+
description:
18+
en: >-
19+
Defines the path to the registry key to manage. Must be prefixed with a valid
20+
hive identifier. Separate the paths with back slashes only.
21+
markdownDescription:
22+
en: |-
23+
The `keyPath` property defines the path to the registry key an instance
24+
of the resource manages. It must be prefixed with a valid hive identifier:
25+
26+
| Identifier | Hive |
27+
|:-------------------------------:|:----------------------|
28+
| `HKCC` or `HKEY_CURRENT_CONFIG` | Current configuration |
29+
| `HKCU` or `HKEY_CURRENT_USER` | Current user |
30+
| `HKCR` or `HKEY_CLASSES_ROOT` | Classes root |
31+
| `HKLM` or `HKEY_LOCAL_MACHINE` | Local machine |
32+
| `HKU` or `HKEY_USERS` | Users |
33+
34+
Specify the path to the registry key with backslashes (`\`), like
35+
`HKCU\DSC\Properties\keyPath\Example`. If using JSON, ensure the
36+
backlsashes are escaped, like `HKCU\\DSC\\Properties\\keyPath\\Example`.
37+
patternErrorMessage:
38+
en: >-
39+
The value must begin with a valid hive identifier. Valid identifiers are:
40+
41+
HKCC, HKEY_CURRENT_CONFIG,
42+
HKCU, HKEY_CURRENT_USER
43+
HKCR, HKEY_CLASSES_ROOT
44+
HKLM, HKEY_LOCAL_MACHINE
45+
HKU, and HKEY_USERS.
46+
47+
metadata:
48+
title:
49+
en: Resource metadata
50+
description:
51+
en: Defines metadata returned by the resource.
52+
markdownDescription:
53+
en: |-
54+
The `metadata` property defines metadata returned by the resource. The registry resource
55+
doesn't support sending metadata input. It returns messages when invoked in what-if mode.
56+
whatIf:
57+
title:
58+
en: What-if messages
59+
description:
60+
en: A list of messages returned by the resource when invoked in what-if mode.
61+
markdownDescription:
62+
en: >-
63+
Contains a list of messages returned by the resource when invoked in what-if mode, as
64+
with the `dsc config set --what-if` command.
65+
valueName:
66+
title:
67+
en: Registry value name
68+
description:
69+
en: Defines the name of the registry value to manage.
70+
markdownDescription:
71+
en: |-
72+
The `valueName` property defines the name of the registry value to manage. This value is
73+
required when specifying value data.
74+
valueData:
75+
title:
76+
en: Registry value data
77+
description:
78+
en: Defines the data for a registry value.
79+
markdownDescription:
80+
en: |-
81+
Defines the data for a registry value. When you specify this value, you must also specify
82+
the name of the registry value.
83+
84+
Define the data as an object with a single property. The property name determines the data
85+
type and the property value determines the data value. The following table lists the
86+
available data types.
87+
88+
| Property name | Data description |
89+
|:--------------:|:-------------------------------------------------------------------|
90+
| `String` | Defines the registry value as a static string. |
91+
| `ExpandString` | Defines the registry value as a string with expandable references. |
92+
| `MultiString` | Defines the registry value as an array of static strings. |
93+
| `Binary` | Defines the registry value as an array of bytes. |
94+
| `DWord` | Defines the registry value as an unsigned 32-bit integer. |
95+
| `QWord` | Defines the registry value as an unsigned 64-bit integer. |
96+
String:
97+
title:
98+
en: String value data
99+
description:
100+
en: Defines the registry value as a static string.
101+
markdownDescription:
102+
en: |-
103+
When you define `valueData` with the `String` property, the resource sets the data for
104+
the registry value as a static string. If the string contains any unexpanded references
105+
to environment variables, such as `%PATH%`, the references are treated as literal
106+
characters and aren't expandable.`
107+
ExpandString:
108+
title:
109+
en: Expandable string value data
110+
description:
111+
en: Defines the registry value as a string with expandable references.
112+
markdownDescription:
113+
en: |-
114+
When you define `valueData` with the `ExpandString` property, the resource sets the data
115+
for the registry value as a string. If the string contains any unexpanded references to
116+
environment variables, such as `%PATH%`, they're expandable.
117+
MultiString:
118+
title:
119+
en: Multiple string value data
120+
description:
121+
en: Defines the registry value as an array of static strings.
122+
markdownDescription:
123+
en: |-
124+
When you define `valueData` with the `MultiString` property, the resource sets the data
125+
for the registry value as an array of static strings. You can specify the value as an
126+
empty array, or as an array containing one or more strings. If any of the strings in the
127+
array contain any unexpanded references to environment variables, such as `%PATH%`, the
128+
references are treated as literal characters and aren't expandable.
129+
Binary:
130+
title:
131+
en: Binary value data
132+
description:
133+
en: Defines the registry value as an array of bytes.
134+
markdownDescription:
135+
en: |-
136+
When you define `valueData` with the `Binary` property, the resource sets the data for
137+
the registry value as an array of bytes. You can specify the value as an empty array or
138+
as an array containing the integer representation of one or more bytes.
139+
DWord:
140+
title:
141+
en: DWord value data
142+
description:
143+
en: Defines the registry value as an unsigned 32-bit integer.
144+
markdownDescription:
145+
en: |-
146+
When you define `valueData` with the `DWord` property, the resource sets the data for the
147+
registry value as an unsigned 32-bit integer.
148+
QWord:
149+
title:
150+
en: QWord value data
151+
description:
152+
en: Defines the registry value as an unsigned 64-bit integer.
153+
markdownDescription:
154+
en: |-
155+
When you define `valueData` with the `QWord` property, the resource sets the data for the
156+
registry value as an unsigned 64-bit integer.
157+
exist:
158+
title:
159+
en: Exist
160+
description:
161+
en: Defines whether the instance should exist.
162+
markdownDescription:
163+
en: |-
164+
The `_exist` property defines whether a registry key or value should exist. When this
165+
property is `true`, the resource creates the registry key or value if it doesn't exist
166+
during a `set` operation. When this property is `false`, the resource deletes the registry
167+
key or value if it exists during a `set` operation.
168+
169+
The default value is `true`.

‎registry/src/args.rs

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,9 @@ pub enum SubCommand {
7777
#[clap(subcommand)]
7878
subcommand: ConfigSubCommand,
7979
},
80-
#[clap(name = "schema", about = "Retrieve JSON schema.")]
81-
Schema,
80+
#[clap(name = "schema", about = t!("cli.schema.about").to_string())]
81+
Schema {
82+
#[clap(short, long, help = t!("cli.schema.args.values_only.help").to_string())]
83+
enhanced: bool,
84+
},
8285
}

‎registry/src/config.rs

Lines changed: 101 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,39 +3,139 @@
33

44
use schemars::JsonSchema;
55
use serde::{Deserialize, Serialize};
6+
use crate::schema::{get_registry_key_path_pattern, get_schema_uri};
67

78
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
89
pub enum RegistryValueData {
10+
#[schemars(
11+
title = t!("schema.valueData.String.title").to_string(),
12+
description = t!("schema.valueData.String.description").to_string(),
13+
extend(
14+
"markdownDescription" = t!("schema.valueData.String.markdownDescription").to_string()
15+
)
16+
)]
917
String(String),
18+
#[schemars(
19+
title = t!("schema.valueData.ExpandString.title").to_string(),
20+
description = t!("schema.valueData.ExpandString.description").to_string(),
21+
extend(
22+
"markdownDescription" = t!("schema.valueData.ExpandString.markdownDescription").to_string()
23+
)
24+
)]
1025
ExpandString(String),
26+
#[schemars(
27+
title = t!("schema.valueData.Binary.title").to_string(),
28+
description = t!("schema.valueData.Binary.description").to_string(),
29+
extend(
30+
"markdownDescription" = t!("schema.valueData.Binary.markdownDescription").to_string()
31+
)
32+
)]
1133
Binary(Vec<u8>),
34+
#[schemars(
35+
title = t!("schema.valueData.DWord.title").to_string(),
36+
description = t!("schema.valueData.DWord.description").to_string(),
37+
extend(
38+
"markdownDescription" = t!("schema.valueData.DWord.markdownDescription").to_string()
39+
)
40+
)]
1241
DWord(u32),
42+
#[schemars(
43+
title = t!("schema.valueData.MultiString.title").to_string(),
44+
description = t!("schema.valueData.MultiString.description").to_string(),
45+
extend(
46+
"markdownDescription" = t!("schema.valueData.MultiString.markdownDescription").to_string()
47+
)
48+
)]
1349
MultiString(Vec<String>),
50+
#[schemars(
51+
title = t!("schema.valueData.QWord.title").to_string(),
52+
description = t!("schema.valueData.QWord.description").to_string(),
53+
extend(
54+
"markdownDescription" = t!("schema.valueData.QWord.markdownDescription").to_string()
55+
)
56+
)]
1457
QWord(u64),
1558
}
1659

1760
#[derive(Debug, Default, Clone, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
1861
#[serde(rename = "Registry", deny_unknown_fields)]
62+
#[schemars(
63+
title=t!("schema.title").to_string(),
64+
description=t!("schema.description").to_string(),
65+
extend(
66+
"$id" = get_schema_uri(true),
67+
"dependentRequired" = { "valueData": ["valueName"] },
68+
"markdownDescription" = t!("schema.markdownDescription").to_string()
69+
)
70+
)]
1971
pub struct Registry {
2072
/// The path to the registry key.
2173
#[serde(rename = "keyPath")]
74+
#[schemars(
75+
title = t!("schema.keyPath.title").to_string(),
76+
description = t!("schema.keyPath.description").to_string(),
77+
required,
78+
regex(pattern = get_registry_key_path_pattern()),
79+
extend(
80+
"markdownDescription" = t!("schema.keyPath.markdownDescription").to_string(),
81+
"patternErrorMessage" = t!("schema.keyPath.patternErrorMessage").to_string(),
82+
)
83+
)]
2284
pub key_path: String,
2385
/// The information from a config set --what-if operation.
2486
#[serde(rename = "_metadata", skip_serializing_if = "Option::is_none")]
87+
#[schemars(
88+
title = t!("schema.metadata.title").to_string(),
89+
description = t!("schema.metadata.description").to_string(),
90+
extend(
91+
"readOnly" = true,
92+
"markdownDescription" = t!("schema.metadata.markdownDescription").to_string()
93+
)
94+
)]
2595
pub metadata: Option<Metadata>,
2696
/// The name of the registry value.
2797
#[serde(rename = "valueName", skip_serializing_if = "Option::is_none")]
98+
#[schemars(
99+
title = t!("schema.valueName.title").to_string(),
100+
description = t!("schema.valueName.description").to_string(),
101+
extend(
102+
"markdownDescription" = t!("schema.valueName.markdownDescription").to_string()
103+
)
104+
)]
28105
pub value_name: Option<String>,
29106
/// The data of the registry value.
30107
#[serde(rename = "valueData", skip_serializing_if = "Option::is_none")]
108+
#[schemars(
109+
title = t!("schema.valueData.title").to_string(),
110+
description = t!("schema.valueData.description").to_string(),
111+
extend(
112+
"markdownDescription" = t!("schema.valueData.markdownDescription").to_string()
113+
)
114+
)]
31115
pub value_data: Option<RegistryValueData>,
32-
#[serde(rename = "_exist", skip_serializing_if = "Option::is_none")]
116+
#[serde(rename = "_exist")]
117+
#[schemars(
118+
title = t!("schema.exist.title").to_string(),
119+
description = t!("schema.exist.description").to_string(),
120+
extend(
121+
"default" = true,
122+
"markdownDescription" = t!("schema.exist.markdownDescription").to_string()
123+
)
124+
)]
33125
pub exist: Option<bool>,
34126
}
35127

36128
#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize, JsonSchema)]
37129
#[serde(deny_unknown_fields)]
38130
pub struct Metadata {
39131
#[serde(rename = "whatIf", skip_serializing_if = "Option::is_none")]
132+
#[schemars(
133+
title = t!("schema.metadata.whatIf.title").to_string(),
134+
description = t!("schema.metadata.whatIf.description").to_string(),
135+
extend(
136+
"readOnly" = true,
137+
"markdownDescription" = t!("schema.metadata.whatIf.markdownDescription").to_string()
138+
)
139+
)]
40140
pub what_if: Option<Vec<String>>
41141
}

0 commit comments

Comments
 (0)