Improve your API design
Optic is the first API linter built with the API lifecycle in-mind. Because Optic understands how your API changes over time, it can test for breaking changes and proper use of your API versioning scheme, as well as enforce an API design guide like Spectral.
optic diff openapi.yml --check
Configuring your lint rules
Get started by creating an optic.yml
file at the root of your repository, and copying in the following rulesets:
ruleset:
# Prevent breaking changes
- "breaking-changes"
# Enforce naming conventions in your API
- naming:
required_on: always
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:
required_on: always
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
Forwards-only governance
Governing APIs that have already shipped to consumers is really difficult. If you turn on an API linter like Spectral to enforce an style guide it will ask developers to make breaking changes to meet the style guide. Optic has a unique approach to this problem -- lifecycle rules.
Every Optic lint rule can be set to run on certain kinds of changes. For example, if you set your naming
rules to be required_on: added
only new endpoints will have to follow them. Legacy endpoints that may not will not warn/error because changing them would be breaking changes.
required_on: always | added | addedOrChanged | removed
To use forwards-only governance and breaking change rules you will need to switch over to using the diff
command:
optic diff openapi.yml --base main --check
Using Spectral
Optic can run your existing Spectral rules. To do this, you'll need to ensure you have the spectral-cli
installed:
npm install -g @stoplight/spectral-cli
Once you've installed the spectral-cli
, modify your optic.yml
file with spectral config. You can point at URLs or local spectral YAML files.
Just like the other standards, you can run Spectral rules on added
parts of your API or always
. We suggest putting your latest API design standards in an added
ruleset, and your security and documentation standards in an always
ruleset.
ruleset:
...
- spectral:
# You can also point this at your own `spectral.yaml` file!
always:
- https://www.apistyleguides.dev/api/url-style-guides/3ba0b4a
added:
- ./spectral.yml
optic diff openapi.yml --base main --check
Next steps
Sharing API Standards
Optic Cloud allows API Programs to set their team's standards in a central location and share them across repos and 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).

Custom Rules
Optic supports writing custom rules in Spectral's rule format (opens in a new tab) or the Optic API Rule DSL. Optic rules look like this -- you specify a part of the specification you want to check and the kind of change that triggers the rule:
response.property.changed((before, after) => {
if (before.required && !after.required)
throw new Error("Making a response property optional is a breaking change")
})