TypeSpec Validation

Table of Contents

• Running Locally
• Examples Source and Destination
• Validation Rule Suppression

Running Locally

To ensure you see the same results from TypeSpecValidation in your PR check and tsv on your local machine:

1. Merge latest from parent (e.g. main or RPSaaSMaster) to your PR branch
2. Run locally
   1. git clean -xdf (may revert any local changes)
   2. git pull
   3. npm ci
3. npx tsv specification/contosowidgetmanager/Contoso.Management
4. If you are still having problems, try cloning your branch to a new folder, or try on another machine.
5. If the problem can be reproduced on a clean machine, request assistance from the TypeSpec Discussion teams channel.

Examples Source and Destination

If you are having problems with diffs from "tsp compile" related to examples, ensure you understand how examples flow from source to destination.

The source of examples is under your TypeSpec source code folder, and the destination of examples is under the Swagger folder. The TypeSpec compiler copies from source to destination. In our sample:

• source
  • https://github.com/Azure/azure-rest-api-specs/tree/main/specification/contosowidgetmanager/Contoso.Management/examples/2021-10-01-preview
• destination
  • https://github.com/Azure/azure-rest-api-specs/tree/main/specification/contosowidgetmanager/resource-manager/Microsoft.Contoso/preview/2021-10-01-preview/examples

If you are changing examples, you must first change the copy under your TypeSpec folder, and then run tsp compile (or tsv which calls compile) to update the copies in your Swagger folder.

Validation Rule Suppression

You can suppress specific validation rules within TypeSpecValidation by creating or modifying a suppressions.yaml file in the root directory of your service specification.

Note: Currently, only the SdkTspConfigValidation rule supports suppression.

Suppressing SdkTspConfigValidation Rules

The SdkTspConfigValidation rule is responsible for validating emitter options and parameters defined in your tspconfig.yaml file. You have the flexibility to suppress this rule entirely or target specific sub-rules within it.

Suppress the Entire SdkTspConfigValidation Rule

If you need to skip all validation checks for emitter options and parameters within a particular tspconfig.yaml file, you can suppress the entire SdkTspConfigValidation rule.

To do this, add or update the suppressions.yaml file in your service's root folder with the following content:

- tool: TypeSpecValidation
  paths:
    # Specify the path to the tspconfig.yaml file where suppression should apply
    - /path/to/tspconfig.yaml
  rules:
    - SdkTspConfigValidation
  reason: the-reason-you-want-to-suppress # Explain why this suppression is necessary

Suppress Specific Sub-rules within SdkTspConfigValidation

If you only need to bypass validation for specific emitter options or parameters, you can suppress individual sub-rules. Add or update your suppressions.yaml file with the following structure, specifying the sub-rules to ignore: Sub-rule Syntax:

• For parameters: parameters.<parameter-key>.default
• For emitter options: options.<emitter-name>.<option-key>
• For nested options (e.g., package-details: name: "xxx"), use dot notation: options.<emitter-name>.package-details.name

- tool: TypeSpecValidation
  paths:
    # Specify the path to the tspconfig.yaml file where suppression should apply
    - /path/to/tspconfig.yaml
  rules:
    - SdkTspConfigValidation
  sub-rules:
    # Example: Suppress validation for a specific parameter's default value
    - parameters.<key-to-validate>.default 
    # Example: Suppress validation for a specific emitter option
    - options.<emitter-name>.<key-to-validate>
    # Example: Suppress validation for a nested emitter option
    - options.<emitter-name>.package-details.name 
  reason: the-reason-you-want-to-suppress # Explain why this suppression is necessary