If you work with OpenAPI specs in any serious capacity, you've probably encountered Spectral. It's the linting tool that lets you define rules for what a good API spec looks like — things like "all operations must have a summary," "response codes should follow a specific pattern," or "authentication must be defined." Teams use it in CI pipelines to catch spec quality issues before they reach production.
What's less well known is that Spectral's rule format is the same format that API Commons uses to define its governance rules. This isn't a coincidence — it's a deliberate choice that means API Commons rules are directly usable in Spectral, and Spectral rulesets can be published and shared through API Commons.
How API Commons Rules Are Structured
An API Commons rule is a YAML (or JSON) document that defines a pattern to check against an API contract. The structure maps directly to Spectral's rule schema: a name, a description, a severity level, a given (the JSON Path expression that selects what to check), and a then (the function and options that perform the check).
Here's what a simple rule looks like:
apis-json-info-title:
description: Ensures that the APIs.json index has a title.
message: The APIs.json index must have a non-empty title.
given: "$"
severity: error
then:
field: name
function: truthyThis rule checks that the root-level name field is present and non-empty in an APIs.json file. You can drop this directly into a Spectral configuration file and it will run as part of your linting process.
Positive and Negative Rules
API Commons organizes rules into positive and negative variants. Positive rules check that something is present or correctly formed — "this field should exist," "this value should match this pattern." Negative rules check that something problematic is absent — "this deprecated pattern should not appear," "this field should not be empty."
The distinction matters for governance. A positive rule failure means your API is missing something required. A negative rule failure means your API is doing something it shouldn't. Both are important, but they call for different remediation actions and different severity levels in your CI pipeline.
Rulesets: Bundling Rules for Use Cases
Individual rules are useful, but rulesets are where API Commons governance becomes practical at scale. A ruleset is a collection of rules assembled for a specific use case — a minimal viability ruleset, an OpenAPI quality ruleset, an APIs.json completeness ruleset, or a domain-specific ruleset for financial APIs or healthcare APIs.
Rulesets in API Commons are expressed as Spectral-compatible configuration files. You can reference them directly in your .spectral.yaml:
extends:
- https://apicommons.org/rulesets/apis-json-completeness
rules:
# your additional project-specific rules hereThis means the API Commons rulesets are live, runnable governance tools — not just documentation. Any team that wants to validate their APIs.json files or OpenAPI specs against API Commons standards can do so in a CI pipeline with a single configuration line.
Contributing Rules
The API Commons rules collection grows through community contribution. If you've identified a governance pattern that's broadly applicable — something that distinguishes well-formed API contracts from poorly-formed ones — you can propose it as an API Commons rule through the GitHub issues or discussions.
The bar for inclusion is that a rule should be objective (it checks a property of the artifact, not a subjective quality judgment), automatable (it can be expressed in Spectral's rule format), and broadly applicable (it's relevant to more than one API type or domain).
If your governance needs are domain-specific — say, rules that only apply to financial services APIs or rules tied to your organization's internal standards — those belong in a community ruleset rather than the core collection, and API Commons supports that use case through its community collection.