Spec Versions

Each time you publish an OpenAPI spec for a service, SpecVault creates a new spec version. Versions are immutable, numbered sequentially, and automatically diffed against the previous version.

Publishing a spec version

You can publish a spec in two ways:

Fetch from URL

Provide a URL pointing to your OpenAPI spec. SpecVault fetches the file at publish time and stores the content. The URL must be accessible from the SpecVault server's network.

POST /api/services/{service_id}/specs
Content-Type: application/json

{"spec_url": "https://api.example.com/openapi.json"}

File upload

Upload a JSON or YAML file directly. Both OpenAPI 3.0.x and 3.1.x are supported. Swagger 2.0 files are accepted but the diff engine's coverage is best on OpenAPI 3.x.

Supported formats

• JSON — application/json with .json extension
• YAML — text/yaml or application/yaml with .yaml or .yml extension

SpecVault parses and validates the spec on upload. Invalid YAML/JSON returns a 422 error. A valid structure that doesn't conform to OpenAPI 3.x will be stored but may produce incomplete diff results.

Version numbering

Versions are numbered sequentially starting from 1. The version number is an integer assigned by SpecVault — it's independent of any version string in your spec's info.version field (that field is stored for reference but not used for ordering).

There is no concept of major/minor/patch versions in SpecVault's numbering. Every publish creates the next integer version. If you want semantic version labels, include them in a label field — see the API reference.

Automatic diff

Every publish after the first triggers an automatic diff against the immediately preceding version. The diff runs synchronously — the publish response includes the diff result:

• Number of endpoints added
• Number of endpoints removed
• Number of endpoints modified
• List of breaking changes (each with method, path, and description)

If breaking changes are detected, subscriber alerts are dispatched immediately as part of the same request.

Version history view

The service detail page shows all versions in reverse chronological order. Each row shows:

• Version number
• Publish date and time
• Endpoint count
• Breaking change count (or "No breaking changes")
• Published by (user name or API token name)

Clicking a version opens the diff detail — the full list of breaking changes, the added/removed endpoint counts, and the raw spec content.