Validating API Specifications Against Governance Rulesets | MuleSoft Documentation
# Validating API Specifications Against Governance Rulesets
Cloud IDE 
Desktop IDE 
**Open Beta Release** : The **cloud IDE is in open beta**. Any use of Anypoint Code Builder in its beta state is subject to the applicable beta services terms and conditions, available from the IDE.
Test your API specifications in Anypoint Code Builder design projects against rules in governance rulesets, and fix conformance issues that result.
For information about rulesets and governance, see Anypoint API Governance Concepts.
## Before You Begin
You must have an API design project with a supported specification in Anypoint Code Builder:
  * Creating and Importing API Specifications
  * Creating and Importing AsyncAPI Specifications


## Workflows and tasks
A typical workflow consists of one or more of the following tasks:
  1. Add one or more rulesets to an API design project:
Add Rulesets to a Project
  2. Run rules in the rulesets to determine if your API specification conforms with the rules:
Run Rules Against Your API Specification
  3. Fix any conformance issues in the specification:
Fix Conformance Issues


## Add Rulesets to a Project
Add governance rulesets as dependencies to your API design project in Anypoint Code Builder.
Rulesets are hosted on Exchange. MuleSoft provides a number of public rulesets that you can find from Anypoint Code Builder or review directly on Exchange. For example, the ruleset Anypoint Best Practices provides documentation and examples. Your team can also create and publish rulesets for your organization to Exchange (see Creating Custom Governance Rulesets).
  1. Open your API design project in Anypoint Code Builder.
  2. From the **Explorer** , expand the **Governance Rulesets** panel in your project.
If the panel is not in the **Explorer** , activate the panel from the **Views and More Actions…​** (**…​**) menu in the **Explorer**.
  3. Add a ruleset:
     * If the panel does not contain any rulesets, click **Add Rulesets**. For example:
     * If the panel contains rulesets, you can hover over the panel and click (**Add Governance Rulesets**) to add another ruleset. For example:
  4. If prompted, sign in to Anypoint Platform.
  5. Search for the ruleset, and click **Add Rulesets**. For example:
You can also narrow your search to specific organizations from the **Any organization** menu, and you can select a different version of a ruleset if more than one version is available.
  6. Proceed to Run Rules Against Your API Specification.


## Centralized Rulesets for Topics and Agents
If you enable your API project for topics and agents, the **SF API Topic and Action Enablement** centralized ruleset is added to your topic-enabled API project automatically.
For more information, see Topic and Agent Governance Rulesets.
## Run Rules Against Your API Specification
Determine whether your API specification conforms with rules in governance rulesets.
  1. Open your API design project in Anypoint Code Builder.
  2. From the **Explorer** , expand the **Governance Rulesets** panel to check for rulesets in your project.
     * If any rulesets are present and you don’t intend to add more, proceed to the next step.
     * If no rulesets are present or if you intend to add more rulesets, go to Add Rulesets to a Project.
  3. Run rules from the **Governance Rulesets** panel.
You can run rulesets at multiple levels:
     * All rules in all rulesets
     * All rules in a single ruleset
     * A single rule in a ruleset
You can monitor the rules as they run. For example:
  4. If any rules return an error () or a warning (), proceed to Fix Conformance Issues.
For example, this ruleset returns a warning on some rules:
Execution times displayed for a ruleset (such as 19.25s) represent the sum of time it takes to run each rule. Due to parallel execution of rules on machines with multiple cores, the execution time displayed for a ruleset is likely to be greater than the actual time to complete the execution.
The **Governance Results** panel also identifies any warnings or errors. For example:


## Fix Conformance Issues
To address rules that return errors or warnings, fix the specification to comply with the rules. Then re-run the rules to ensure that the fix is effective.
### Example
To illustrate the process for addressing issues, the example in this procedure starts with a partial RAML specification and some rulesets:
Full Example
  * The specification has this markup:
```
#%RAML 1.0
title: my-des-with-governance
protocols:
 - HTTP
```

  * The design project for the specification applies these rulesets:
    * HTTPS Enforcement
    * Anypoint Best Practices


### Fix Conformance Issues
To fix errors () and warnings ():
  1. Run the rulesets in your project.
For guidances, see Run Rules Against Your API Specification.
  2. Review any resulting errors and warnings in the **Governance Results** panel. For example:
**Governance Results** lists the corresponding issues. For example:
     * `Error: [HTTPS Enforcement] Only use https protocol scheme.`
     * `Warning: [Anypoint Best Practices] Provide the documentation for the API.`
     * `Warning: [Anypoint Best Practices] Provide the description for the API.`
  3. Address errors in the specification.
For instance, fix the **HTTPS Enforcement** error in the specification example by changing `HTTP` to `HTTPS`:
```
#%RAML 1.0
title: my-des-with-governance
protocols:
 - HTTPS
```

  4. Re-run the failing rule to ensure that the error is fixed.
For instance, after fixing the `protocols` error in the specification example, run **use-https-for-scheme-protocol** from the **Governance Rulesets** panel. For example:
Notice that the error no longer appears in **Governance Rulesets**. For example:
In addition, the **Governance Results** panel no longer lists the issue.
  5. Address warnings, as needed.
For instance:
    1. Address the warning `Provide the description for the API` by adding a `description` to the specification example. For example:
```
#%RAML 1.0
title: my-des-with-governance
description: my description
protocols:
 - HTTPS
```

The description is between `title` and `protocols`.
    2. Re-run the rule **api-must-have-description** , and notice that the specification now conforms to the rule.
The ruleset continues to identify a warning because a different rule in the ruleset has a warning.
  6. Address any remaining issues that you intend to fix.
For instance, for the warning `Provide the documentation for the API` in the example, add and save `documentation` markup to the specification:
```
#%RAML 1.0
title: my-des-with-governance
description: my description
documentation:
 - title: My Title
  content: |
   Welcome to my API documentation.
 - title: Legal
  content: |
   This is my legal documentation.
protocols:
 - HTTPS
```

  7. Re-run the corresponding rule from the **Governance Rulesets** panel.
For example, re-run **api-must-have-documentation** , and notice that the specification now conforms to the rule.


The specification has no more errors or warnings. For example:
## Remove a Ruleset from a Project
  1. In the **Governance Ruleset** panel, hover over a ruleset to display the **More actions** (**…​**) menu.
  2. In the **More actions** menu, click **Remove Ruleset…​**.


You can also use the command **MuleSoft: Remove Governance Ruleset…​** from the command palette for this purpose.
## Open a Ruleset YAML File
To examine the configuration of a ruleset’s YAML file:
  1. In the **Governance Ruleset** panel, hover over a ruleset to display its **More actions** (**…​**) menu.
  2. Click **Show in Files** to open the YAML file in a **ruleset.yaml** tab in the IDE.
7. Re-run the corresponding rule from the **Governance Rulesets** panel.
For example, re-run **api-must-have-documentation** , and notice that the specification now conforms to the rule.


The specification has no more errors or warnings. For example:
## Remove a Ruleset from a Project
  1. In the **Governance Ruleset** panel, hover over a ruleset to display the **More actions** (**…​**) menu.
  2. In the **More actions** menu, click **Remove Ruleset…​**.


You can also use the command **MuleSoft: Remove Governance Ruleset…​** from the command palette for this purpose.
## Open a Ruleset YAML File
To examine the configuration of a ruleset’s YAML file:
  1. In the **Governance Ruleset** panel, hover over a ruleset to display its **More actions** (**…​**) menu.
  2. Click **Show in Files** to open the YAML file in a **ruleset.yaml** tab in the IDE.


The following example shows version 1.6.1 of the HTTPS Enforcement YAML file:
```
#%Validation Profile 1.0
profile: HTTPS enforcement
description: This ruleset helps ensure the use of HTTPS across URLs in API
 definitions, both in the base server URL and in any callbacks optionally
 defined.
violation:
 - use-https-for-callbacks
 - use-https-for-scheme-protocol
 - use-https-for-urls
tags:
 - security
validations:
 use-https-for-callbacks:
  message: "{{apiContract.expression}} must use https as it is a callback url"
  targetClass: apiContract.Callback
  propertyConstraints:
   apiContract.expression:
    pattern: ^https://
  examples:
   valid: |
    openapi: "3.0.0"
    info:
     title: example API
     version: "1.0.0"
    paths:
     /subscribe:
      post:
       responses:
        '201':
         description: Webhook created
       callbacks:
        myEvent:
         'https://{$request.body#/callbackUrl}'
   invalid: |
    openapi: "3.0.0"
    info:
     title: example API
     version: "1.0.0"
    paths:
     /subscribe:
      post:
       responses:
        '201':
         description: Webhook created
       callbacks:
        myEvent:
         'http://{$request.body#/callbackUrl}'
 use-https-for-scheme-protocol:
  message: Only use https protocol scheme
  targetClass: apiContract.WebAPI
  not:
   propertyConstraints:
    apiContract.scheme:
     containsSome:
      - HTTP
      - http
  examples:
   valid: |
    #%RAML 1.0
    protocols:
     - HTTPS
   invalid: |
    #%RAML 1.0
    protocols:
     - HTTP
 use-https-for-urls:
  message: "{{core.urlTemplate}} should use https"
  targetClass: apiContract.Server
  propertyConstraints:
   core.urlTemplate:
    pattern: ^https://
  examples:
   valid: |
    openapi: "3.0.0"
    servers:
     - url: "https://mySecureEndpoint"
      description: "My endpoint that uses HTTPS"
   invalid: |
    openapi: "3.0.0"
    servers:
     - url: "http://myNotSoSecureEndpoint"
      description: "My endpoint that uses HTTP"
```

## Open a Ruleset in Exchange
In Exchange, rulesets list all rules and can provide documentation with examples.
To open the ruleset in Exchange:
  1. In the **Governance Ruleset** panel, hover over a ruleset to display its **More actions** (**…​**) menu.
  2. Click **Open in Exchange**.


## Change a Ruleset Version
To select a different version of a ruleset:
  1. In the **Governance Ruleset** panel, hover over a ruleset to display its **More actions** (**…​**) menu.
  2. Click **Change Version…​**.
  3. Select a different version from the **Change Version** menu that opens.