SpecDoc

Spec Registry

Every time your CI/CD pipeline runs, SpecDoc creates an immutable, versioned snapshot of your OpenAPI spec. The Spec Registry is your complete audit trail — every change, every deployment.

How versioning works

Each successful pipeline publish creates a new version numbered sequentially (v1, v2, v3…). Versions are immutable — they can never be overwritten. A version is tied to:

The exact spec file content (SHA-256 hash stored)
The environment (production, staging, etc.)
The commit SHA and pipeline run ID
The governance check result at time of publish
Timestamp and publisher identity

Browsing version history

In the SpecLayer app, navigate to your project and select the Registry tab. You'll see a list of all published versions with their status, commit SHA, and governance result. Click any version to view the full spec and its diff from the previous version.

Comparing versions

The diff view highlights changes at the operation level:

Added

New paths, operations, or schema properties

Changed

Modified descriptions, types, or constraints

Removed

Deleted operations or required fields (breaking)

Tagging versions

You can tag any version with a human-readable label. Tags are useful for marking stable releases. Add a tag from the Registry UI or via the CLI:

SpecLayer CLI

# Tag a specific version
speclayer registry tag \
  --project payments-api \
  --version 14 \
  --tag v2.0.0-stable

# Tag the latest published version
speclayer registry tag \
  --project payments-api \
  --tag v2.1.0

Accessing versions via API

Every version is available as a raw OpenAPI file via the SpecLayer API. Useful for feeding specs into other tools (mock servers, contract testing, SDK generators).

REST API

# Get the latest spec for a project
GET https://api.speclayer.net/api/v1/specs/{projectSlug}
Authorization: Bearer {api_key}

# Get a specific version
GET https://api.speclayer.net/api/v1/specs/{projectSlug}?version=14
Authorization: Bearer {api_key}

# List all versions (history)
GET https://api.speclayer.net/api/v1/specs/{projectSlug}/history
Authorization: Bearer {api_key}

Response

{
  "id": "01J8X4Q...",
  "project_slug": "payments-api",
  "version": 14,
  "environment": "production",
  "title": "Payments API",
  "governance_passed": true,
  "governance_results": [...],
  "has_breaking_changes": false,
  "breaking_changes": [],
  "created_at": "2026-04-15T10:23:00Z"
}

Spec files are served with a Content-Type: application/yaml or application/json header depending on the original upload format. Add Accept: application/json to force JSON output.

Breaking change detection

SpecDoc automatically compares each new version against the previous one and classifies changes as breaking or non-breaking. Configure how the pipeline reacts in your task inputs:

Pipeline configuration

breakingChange: 'fail'   # Exit pipeline with error (default for production)
breakingChange: 'warn'   # Print warning, continue pipeline
breakingChange: 'off'    # Skip breaking change detection

Breaking changes include: removing an endpoint, removing a required request field, changing a response field type, and removing an enum value. Non-breaking changes include: adding optional fields, adding new endpoints, and updating descriptions.

Quickstart

Governance Rules