Developer-friendly API Governance
Optic has an API linter built for the messy real-world. You can use it to govern APIs that have already shipped, without getting in the way of developers. Optic makes sure the additions to your API follow the latest standards and understands that existing API endpoints cannot be updated without introducing breaking changes. Get the benefits of Spectral, Redocly and other API Linting tools without all the noise.
Get started by creating an optic.yml file at the root of your repository, and copying in the following:
- ✅ Run any of your existing Spectral (opens in a new tab) Rules
- ✅ Catch Breaking Changes
- ✅ Support Advanced style guides for things like pagination
- ✅ Enforce a versioning policy (ie require semantic versioning)
Optic Cloud Subscriptions include several free API Governance consults. If you want help choosing API standards Book a session here (opens in a new tab)
Setting API Standards
The community maintains many useful off-the-shelf standards. Here's an example optic.yml
file you can copy to your repo to get started:
ruleset:
# Prevent breaking changes
- breaking-changes:
# Pick an extension for your work-in-progress operations.
# Breaking changes will be allowed here
exclude_operations_with_extension: x-draft
# Run any spectral ruleset
- spectral:
# These rules will ony run on things you add to your API
# Ie new properties, operations, responses, etc.
added:
# URLs are supported
- https://www.apistyleguides.dev/api/url-style-guides/3ba0b4a
# Local files work too.
# - ./local-file.js
# These rules will ony run on everything in the spec (normal spectral)
always:
- https://www.apistyleguides.dev/api/url-style-guides/3ba0b4a
# Enforce consistent cases in your API
- naming:
# This will apply the rule to only new names (existing ones will be exempted)
# Change to always if you want to fail on legacy names
# Change to addedOrChanged if you want it to run on added or changed parts of the spec
required_on: added
# Different names for different parts of the spec
# options = "snake_case" "camelCase" "Capital-Param-Case" "param-case" "PascalCase"
requestHeaders: Capital-Param-Case
responseHeaders: param-case
properties: Capital-Param-Case
pathComponents: param-case
queryParameters: snake_case
# Require your OpenAPI has examples, and that those examples match the schema
- examples:
# Turn on/off the parts of the spec that need examples
require_request_examples: true
require_response_examples: true
require_parameter_examples: true
# (optional) allow certain operations do not need examples
exclude_operations_with_extension: x-legacy-api
Running the Standards
Because Optic tests your API changes, you run standards with the diff
command
optic diff openapi.yaml --base main --check --ruleset ./optic.dev.yml
This tests the changes between the working copy of openapi.yaml
and the version on the main
branch. It runs the rulesets as configured in optic.dev.yml
and prints the results to the console. If you would like to see the errors formatted in the browser, pass in the --web
flag:
Sharing API Standards
Optic Cloud allows API Programs to set their team's standards in Optic Cloud, and apply them to multiple API specs. This way when the standards are changed, everyone gets the update quickly. Go to your team's organization Settings
> Standards
to get started. If you are a Cloud Subscriber we suggest booking a session with us as well to talk about what we have learned helping many teams adopt API Standards: Book a session here (opens in a new tab).

Advanced Standards and Style Guides
Need more than the community standards? Want to do something too advanced for Spectral? Optic has a framework for testing API Changes that all the community standards are built upon.
Notable examples:
- Snyk's V3 API Standards (opens in a new tab)
- Breaking change standards (opens in a new tab)
- Casing and Naming standards (opens in a new tab)
- Examples must match schema standard (opens in a new tab)
If you are interested in writing custom rules for your team you can also book a session here (opens in a new tab).