Rules

Make sure you have created a Scalar Account and are logged in (see create account guide)

Create your first rule#

Let's create our first rule! From the dashboard left-most sidebar under Rules, then click "+ New".

Configure your rule#

When you create a new rule, it will extend the default Spectral OSS ruleset (spectral:oas). This provides a solid foundation of OpenAPI linting rules from the Spectral project.

The default rule configuration looks like this:

extends: spectral:oas
rules: {}

You can customize your rule by:

• Extending other rulesets
• Adding custom rules
• Overriding existing rules

For more information about Spectral rules and how to write custom rules, see the Spectral documentation.

Access Control#

Just like other resources in the Registry, you can control who has access to your rules.

Public Rules#

Public rules can be shared with anyone and are accessible via their registry path. This is useful for open-source projects or when you want to share your linting standards with the community.

Private Rules#

Private rules are restricted to your organization and can be shared with specific access groups. This is ideal for internal API standards and company-specific linting requirements.

You can manage rule access from the rule's Overview page in the dashboard, similar to how you manage access for other registry resources.

CLI#

Now let's use your rule to lint an OpenAPI document using the Scalar CLI.

You can lint your OpenAPI files using the scalar document lint command:

scalar document lint ./openapi.yaml

To use a specific rule from the Registry, use the --rule option:

scalar document lint ./openapi.yaml --rule https://registry.scalar.com/@your-team/rules/your-rule

You can also use a local rule file:

scalar document lint ./openapi.yaml --rule ./my-custom-ruleset.yaml

For more information about Spectral rules and how to write custom rules, see the Spectral documentation.

Integration with CI/CD#

You can integrate rule-based linting into your CI/CD pipelines to automatically validate OpenAPI documents before they're merged or deployed.

# .github/workflows/lint-openapi.yml
name: Lint OpenAPI Document
 
on:
  push:
    branches:
      - main
  pull_request:
    paths:
      - 'openapi.yaml'
 
jobs:
  lint:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v6
 
      - name: Setup Node.js
        uses: actions/setup-node@v6
        with:
          node-version: 24
 
      - name: Lint OpenAPI Document
        run: npx @scalar/cli document lint openapi.yaml --rule https://registry.scalar.com/@your-team/rules/your-rule

This ensures that all OpenAPI documents meet your organization's standards before they're published or used to generate documentation.