Spec fidelity directives

When using AutoRest (or similar) to generate PowerShell/SDK surfaces, enforce that the generated cmdlets and types preserve the intended REST API contract—especially around nullability, required parameters, and unintended extra parameter-set variants.

Apply this standard: 1) Verify intent with spec/API diffs

• If a generated type changes (e.g., non-nullable -> nullable), confirm whether the REST spec truly changed.
• If the change is unintended, correct it with an explicit directive (e.g., restore non-nullability) rather than patching generated code.

2) Fix via generation directives; regenerate outputs

• Avoid manual edits to generated cmdlets/models/help files.
• Update README/directives (or typespec/swagger inputs) and then regenerate so the same rule is consistently applied.

3) Suppress unwanted generated surface for API-correct behavior

• Don’t allow generic command behaviors that don’t make sense for the underlying HTTP action.
• Example: for Get- commands, suppress -Confirm/-WhatIf if the generator adds ShouldProcess due to non-GET transport behavior.

4) Keep required parameters required; don’t hide breaking changes without basis

• Ensure path/route parameters remain mandatory in cmdlet signatures.
• If generation introduces “new” parameter sets/variants, only include/unhide those that are part of the intended backward-compatible surface; otherwise filter them.

Example (directive-driven contract correction):

# Force non-nullable primitive array elements to preserve released contract
# (addresses unintended IList<int?> generation)
- from: swagger-document
  where: $.definitions["SomeResource"].properties["rules"].items
  transform: $['x-nullable'] = false

# Suppress ShouldProcess for Get- commands that don't benefit from -Confirm/-WhatIf
# (exact directive syntax depends on the repo’s directive framework)
- where:
    subject: ^Get-.*
  suppress-shouldprocess: true

5) Resource-scope correctness in documentation/examples

• For examples, ensure the stated scope (resource group vs subscription-level proxy resources) matches how the API actually creates/targets the resource.

Checklist for PRs in this area:

• Show old vs new generated type signature (and where it came from in spec).
• Confirm whether the spec change is intentional.
• If not intentional: add/adjust a generation directive.
• Regenerate SDK/docs and confirm the only diffs are the intended ones.
• Validate cmdlet signature correctness (mandatory path params, filtering of unwanted variants, and suppression of misleading -Confirm/-WhatIf on Get where applicable).