diff --git a/.github/instructions/code-review/library.instructions.md b/.github/instructions/code-review/library.instructions.md index 0e47c8e44..8527f988e 100644 --- a/.github/instructions/code-review/library.instructions.md +++ b/.github/instructions/code-review/library.instructions.md @@ -26,6 +26,12 @@ They define the public API surface of the DSC codebase. - **Be precise with serde**: Review `rename_all`, `deny_unknown_fields`, `Option` vs default, and wire-format names. - **Names must match semantics**: Singular/plural, stale doc comments, misleading function names. - **Schema version catalogs**: `lib/dsc-lib-jsonschema/.versions.json` is auto-generated by build. Do not flag version entries as unintentional. +- **Inline schemas when possible**: Add the `[schemars(inline)]` attribute to struct and enum type definitions unless they are non-trivial or are used across multiple other types. Never inline types that derive `DscRepoSchema`. +- **Derive `DscRepoSchema` for all non-inlined types**: Any struct or enum that is not marked with `[schemars(inline)]` should derive `DscRepoSchema` to ensure it is included in the schema catalog. +- **Add `should_bundle` attribute to root document types**: Any struct that DSC reads directly from user input or outputs to the user should have the `should_bundle` attribute defined as `true` in the `dsc_repo_schema` derive macro helper attribute when deriving `DscRepoSchema` to ensure that consumers can point to a canonically bundled schema when authoring input or validating output. +- **Add the `idiomaticize_string_enum` transform to string enums**: When deriving `JsonSchema` for string enums, include the `idiomaticize_string_enum` transform in the `schemars` helper attribute to ensure that the JSON Schema is idiomatic. +- **Add the `idiomaticize_externally_tagged_enum` transform to externally tagged enums**: When deriving `JsonSchema` for externally tagged enums, include the `idiomaticize_externally_tagged_enum` transform in the `schemars` helper attribute to ensure that the JSON Schema is idiomatic. + ## Performance diff --git a/.github/instructions/code-review/resource.instructions.md b/.github/instructions/code-review/resource.instructions.md index d0537b95e..46d6c01fb 100644 --- a/.github/instructions/code-review/resource.instructions.md +++ b/.github/instructions/code-review/resource.instructions.md @@ -15,6 +15,10 @@ firewall, SSH config, DISM features, etc.). They run as separate executables inv - **Schema/manifest version consistency**: When bumping a version in `Cargo.toml`, ensure the corresponding `.dsc.resource.json` manifest is also updated. - **`noFiltering` semantics**: Export input should be treated as empty when `noFiltering` is declared. - **Canonical property naming**: Leading underscore (`_`) is only for cross-resource canonical properties. Resource-specific properties use descriptive names (e.g., `sshd_config_filepath`). +- **Canonical property definitions:** Always define a canonical property in the `properties` keyword with the `$ref` keyword pointing to the absolute URI for the canonical property schema. Always insert the canonical +property schema in the `$defs` keyword with the absolute URI for the canonical property schema as the key and the schema as the value. +- **Mark properties read-only as needed**: Define the `readOnly` keyword as `true` for properties that the resource can't directly use from user input but will return as part of the output representing the actual state of an instance. Don't define the keyword as `false` for any properties. +- **Mark properties write-only as needed**: Define the `writeOnly` keyword as `true` for properties that the resource accepts from user input but doesn't return in the output. Always mark secret and credential properties as write-only.Don't define the keyword as `false` for any properties. ## Operation Consistency