Skip to content

TypeSpec Validation

Jump to bottom
Wanpeng Li edited this page Jun 10, 2025 · 23 revisions

Table of Contents

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:

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

Rules

SdkTspConfigValidation

Parameters

  • parameters.default.service-dir
    • Allowed values: strings that matches the regex /^sdk\/.*$/
    • example: sdk/aaa

JavaScript Sub Rules

Please follow the below steps to configure. If you encounter any issues, please seek help in the JS channel

Management Plane

  • @azure-tools/typespec-ts.options.experimental-extensible-enums

    • Allowed values: true

  • @azure-tools/typespec-ts.options.package-dir

    • Allowed values: strings that matches the regex /^arm(?:-[a-z]+)+$/
    • example: arm-aaa-bbb

  • @azure-tools/typespec-ts.options.package-details.name

    • Allowed values: strings that matches the regex /^\@azure\/arm(?:-[a-z]+)+$/
    • example: @azure/arm-aaa-bbb

Data Plane

  • @azure-tools/typespec-ts.options.package-dir

    • Allowed values: strings that matches the regex /^(?:[a-z]+-)+rest$/
    • example: arm-aaa-rest

  • @azure-tools/typespec-ts.options.package-details.name

    • Allowed values: strings that matches the regex /^\@azure-rest\/[a-z]+(?:-[a-z]+)*$/
    • example: @azure-rest/aaa-bbb

Python Sub Rules

Please follow the below steps to configure. If you encounter any issues, please seek help in the python channel

Management Plane

  • @azure-tools/typespec-python.options.package-dir

    • Allowed values: strings that matches the regex /^azure-mgmt(-[a-z]+){1,2}$/
    • example: azure-mgmt-aaa

  • @azure-tools/typespec-python.options.namespace

    • Allowed values: strings that matches the regex /^azure\.mgmt(\.[a-z]+){1,2}$/
    • example: azure.mgmt.aaa

  • @azure-tools/typespec-python.options.generate-test

    • Allowed values: true

  • @azure-tools/typespec-python.options.generate-sample

    • Allowed values: true

Data Plane

  • @azure-tools/typespec-python.options.package-dir

    • Allowed values: strings that matches the regex /^azure(-[a-z]+){1,3}$/
    • example: azure-aaa-bbb-ccc

  • @azure-tools/typespec-python.options.generate-test

    • Allowed values: true

  • @azure-tools/typespec-python.options.generate-sample

    • Allowed values: true

Go Sub Rules

Please follow the below steps to configure. If you encounter any issues, please seek help in the go channel

Management Plane

  • @azure-tools/typespec-go.options.service-dir

    • Allowed values: strings that matches the regex /^sdk\/resourcemanager\/[^\/]*$/
    • example: sdk/resourcemanager/aaa

  • @azure-tools/typespec-go.options.package-dir

    • Allowed values: strings that matches the regex /^arm[^\/]*$/
    • example: armaaa

  • @azure-tools/typespec-go.options.module

    • Allowed values: strings that matches the regex github.com/Azure/azure-sdk-for-go/{service-dir}/{package-dir}
    • example: github.com/Azure/azure-sdk-for-go/{service-dir}/{package-dir}

  • @azure-tools/typespec-go.options.fix-const-stuttering

    • Allowed values: true

  • @azure-tools/typespec-go.options.generate-samples

    • Allowed values: true

  • @azure-tools/typespec-go.options.generate-fakes

    • Allowed values: true

  • @azure-tools/typespec-go.options.head-as-boolean

    • Allowed values: true

  • @azure-tools/typespec-go.options.inject-spans

    • Allowed values: true

Data Plane

  • @azure-tools/typespec-go.options.package-dir

    • Allowed values: strings that matches the regex /^az.*$/
    • example: az1/2/3

  • @azure-tools/typespec-go.options.module

    • Allowed values: strings that matches the regex /^github.com/Azure/azure-sdk-for-go/.*$/ or undefined
    • example: github.com/Azure/azure-sdk-for-go/aaa, undefined

  • @azure-tools/typespec-go.options.generate-fakes

    • Allowed values: true

  • @azure-tools/typespec-go.options.inject-spans

    • Allowed values: true

Java Sub Rules

Please follow the below steps to configure. If you encounter any issues, please seek help in the java channel

  • @azure-tools/typespec-java.options.package-dir
    • Allowed values: strings that matches the regex /^azure(-\w+)+$/
    • example: azure-aaa

.Net Sub Rules

Please follow the below steps to configure. If you encounter any issues, please seek help in the .Net channel

Management Plane

  • @azure-tools/typespec-csharp.options.package-dir
    • Allowed values: strings that matches the regex /^Azure\.ResourceManager\./
    • example: Azure.ResourceManager.AAA
  • @azure-tools/typespec-csharp.options.namespace
    • Allowed values: package-dir or {package-dir}
    • example: package-dir, Azure.ResourceManager.AAA
  • @azure-tools/typespec-csharp.options.clear-output-folder
    • Allowed values: true

Data Plane

  • @azure-tools/typespec-csharp.options.package-dir
    • Allowed values: strings that start with Azure.
    • example: Azure.aaa
  • @azure-tools/typespec-csharp.options.namespace
    • Allowed values: package-dir or {package-dir}
    • example: package-dir, Azure.aaa
  • @azure-tools/typespec-csharp.options.clear-output-folder
    • Allowed values: true

Overview

Checks

Specs

Engineering System

Meta

Clone this wiki locally