Name: Specwise API: OpenAPI Validator and Breaking-Change Diff
Brand: bytestay
SKU: api-bytestay-specwise
Availability: InStock
Author: API Market

# Specwise OpenAPI Validator and Diff API

## Overview

The Specwise API validates OpenAPI and JSON Schema documents and compares two OpenAPI versions to find breaking changes. Every error comes with a readable message, its JSON Pointer and, for documents sent as text, the line and column.

It is built for API teams, platform engineers and CI pipeline authors who want one HTTP call instead of installing and wiring several validators. Documents are sent in the request body, nothing is fetched from the network and nothing is stored.

## Features

*   **Five endpoints**: OpenAPI validation, JSON Schema validation, an OpenAPI diff, the rule catalogue and a health check.
*   **Every OpenAPI version**: Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2 are detected automatically.
*   **Two validation passes**: the official meta-schema first, then semantic checks such as unresolved path parameters and duplicate operationIds.
*   **12 lint rules**: missing operationIds, summaries, servers or success responses, unused components and more, kept apart from real errors.
*   **JSON Schema drafts**: 4, 6, 7, 2019-09 and 2020-12, with instance path, schema path and keyword for every error.
*   **Breaking-change diff**: 70 change kinds in four severities, a `breaking` flag your CI can act on and a semver suggestion.
*   **Rate limit**: up to 10 requests per second on every plan.

## Use Cases

*   **CI gates**: fail a pull request when an OpenAPI change breaks existing clients.
*   **Release notes**: list every change between two spec versions, with its severity.
*   **Spec authoring**: catch errors and lint warnings with line numbers before publishing docs or generating SDKs.
*   **Payload checks**: validate JSON or YAML data against a JSON Schema in a backend or a form pipeline.
*   **API governance**: check every spec in a portfolio against the same rules.

## API Documentation

### Base URL

All requests go through the API.market proxy at this base URL:

```
https://prod.api.market/api/v1/bytestay/specwise
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Health check

Returns `ok`, the service version and its uptime.

**Method:** `GET`

**Endpoint:** `/v1/health`

**Parameters:**

This endpoint takes no parameters.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/bytestay/specwise/v1/health' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK):**

```json
{
  "ok": true,
  "version": "0.2.2",
  "uptime_s": 263
}
```

#### 2. Validate an OpenAPI document

Validates a Swagger 2.0 or OpenAPI 3.0, 3.1 or 3.2 document and returns every error with its location, plus lint warnings. The example spec uses `{id}` in the path but never declares it as a parameter.

**Method:** `POST`

**Endpoint:** `/v1/openapi/validate`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `spec` | body | The document as a JSON object, or a YAML or JSON string. Send a string to get line and column numbers. | object or string | Yes | - | 2 MB body |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/bytestay/specwise/v1/openapi/validate' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"spec": "openapi: 3.1.0\ninfo:\n  title: Pets\n  version: 1.0.0\npaths:\n  /pets/{id}:\n    get:\n      responses:\n        \"200\":\n          description: A pet\n"}'
```

**Example Response (200 OK, shortened to 2 of the 5 warnings):**

```json
{
  "valid": false,
  "spec_type": "openapi",
  "dialect": "3.1",
  "version": "3.1.0",
  "input_format": "yaml",
  "error_count": 1,
  "errors": [
    {
      "message": "Path parameter 'id' for 'get' operation in '/pets/{id}' was not resolved",
      "pointer": "/paths/~1pets~1{id}/get",
      "line": 7,
      "column": 5,
      "source": "semantic",
      "keyword": null,
      "hints": []
    }
  ],
  "warning_count": 5,
  "warnings": [
    {
      "rule": "info-description-missing",
      "message": "info.description is missing",
      "pointer": "/info",
      "line": 2,
      "column": 1
    },
    {
      "rule": "servers-missing",
      "message": "no `servers`: clients will assume `/` on the host that served the document",
      "pointer": "",
      "line": 1,
      "column": 1
    }
  ],
  "unresolved_refs": [],
  "semantic_checks_complete": true,
  "truncated": false,
  "stats": {
    "paths": 1,
    "operations": 1,
    "schemas": 0
  }
}
```

#### 3. Validate a JSON Schema and an instance

Checks the schema against its meta-schema, then validates the instance. Leave `instance` out to check only the schema.

**Method:** `POST`

**Endpoint:** `/v1/jsonschema/validate`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `schema` | body | The JSON Schema as an object, a boolean, or a YAML or JSON string. | object, boolean or string | Yes | - | 2 MB body |
| `instance` | body | The value to validate. Omit it to only check the schema. | any | No | - | - |
| `instance_format` | body | `value` when `instance` is the data itself, `json` or `yaml` when it is a string to parse first. | string | No | `value` | - |
| `draft` | body | Force a draft: `4`, `6`, `7`, `2019-09` or `2020-12`. By default it comes from `$schema`, else 2020-12. | string | No | - | - |
| `formats` | body | Assert `format` (email, date-time, uuid and others) instead of only annotating it. | boolean | No | `true` | - |

**Example Request:**

```bash
curl -X POST 'https://prod.api.market/api/v1/bytestay/specwise/v1/jsonschema/validate' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"schema": {"type": "object", "required": ["email", "age"], "properties": {"email": {"type": "string", "format": "email"}, "age": {"type": "integer", "minimum": 0}}}, "instance": {"email": "not-an-email", "age": -3}}'
```

**Example Response (200 OK):**

```json
{
  "valid": false,
  "draft": "2020-12",
  "draft_source": "default",
  "schema_valid": true,
  "schema_errors": [],
  "instance_valid": false,
  "error_count": 2,
  "errors": [
    {
      "message": "-3 is less than the minimum of 0",
      "instance_path": "/age",
      "schema_path": "/properties/age/minimum",
      "keyword": "minimum",
      "line": null,
      "column": null,
      "hints": []
    },
    {
      "message": "'not-an-email' is not a 'email'",
      "instance_path": "/email",
      "schema_path": "/properties/email/format",
      "keyword": "format",
      "line": null,
      "column": null,
      "hints": []
    }
  ],
  "unresolved_refs": [],
  "notes": [],
  "complete": true,
  "truncated": false
}
```

#### 4. Compare two OpenAPI documents

Compares two OpenAPI 3.x documents and classifies every change as breaking, warning, non-breaking or info. Local `$ref`s are followed, and request and response directions are judged separately.

**Method:** `POST`

**Endpoint:** `/v1/openapi/diff`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `base` | body | The old OpenAPI 3.x document, as an object or a YAML or JSON string. | object or string | Yes | - | 2 MB body |
| `revision` | body | The new OpenAPI 3.x document. | object or string | Yes | - | 2 MB body |

**Example Request:**

In this example the `limit` query parameter becomes required and the `name` response property is removed.

```bash
curl -X POST 'https://prod.api.market/api/v1/bytestay/specwise/v1/openapi/diff' \
  -H 'x-api-market-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"base": "openapi: 3.0.3\ninfo: {title: Pets, version: 1.0.0}\npaths:\n  /pets:\n    get:\n      operationId: listPets\n      parameters:\n        - {name: limit, in: query, schema: {type: integer}}\n      responses:\n        \"200\":\n          description: ok\n          content:\n            application/json:\n              schema:\n                type: object\n                properties:\n                  id: {type: string}\n                  name: {type: string}\n", "revision": "openapi: 3.0.3\ninfo: {title: Pets, version: 1.0.0}\npaths:\n  /pets:\n    get:\n      operationId: listPets\n      parameters:\n        - {name: limit, in: query, required: true, schema: {type: integer}}\n      responses:\n        \"200\":\n          description: ok\n          content:\n            application/json:\n              schema:\n                type: object\n                properties:\n                  id: {type: string}\n"}'
```

**Example Response (200 OK):**

```json
{
  "breaking": true,
  "semver": "major",
  "summary": {
    "total": 2,
    "breaking": 2,
    "warning": 0,
    "non_breaking": 0,
    "info": 0
  },
  "base_version": "1.0.0",
  "revision_version": "1.0.0",
  "changes": [
    {
      "kind": "parameter.became_required",
      "severity": "breaking",
      "operation": "GET /pets",
      "pointer": "/paths/~1pets/get/parameters/0/required",
      "message": "GET /pets: query parameter 'limit' is now required"
    },
    {
      "kind": "response.property_removed",
      "severity": "breaking",
      "operation": "GET /pets",
      "pointer": "/paths/~1pets/get/responses/200/content/application~1json/schema/properties/name",
      "message": "response 200 (application/json) `name`: property removed"
    }
  ],
  "truncated": false,
  "unresolved_refs": {
    "base": [],
    "revision": []
  }
}
```

#### 5. List rules and change kinds

Returns the 12 lint rules and the 70 diff change kinds with their severity.

**Method:** `GET`

**Endpoint:** `/v1/rules`

**Parameters:**

This endpoint takes no parameters.

**Example Request:**

```bash
curl -X GET 'https://prod.api.market/api/v1/bytestay/specwise/v1/rules' \
  -H 'x-api-market-key: YOUR_API_KEY'
```

**Example Response (200 OK, shortened to one item per list):**

```json
{
  "lint": [
    {
      "rule": "operation-id-missing",
      "description": "Operation has no operationId (code generators and SDKs need one)"
    }
  ],
  "changes": [
    {
      "kind": "path.removed",
      "severity": "breaking",
      "description": "A path was removed, with every operation under it"
    }
  ]
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The document was checked. An invalid document is still a 200; check `valid`, `errors` or `breaking`. |
| 401 | Unauthorized | The `x-api-market-key` header is missing or the key is not valid. |
| 403 | Forbidden | Your key has no active subscription to this API, your plan quota is used up, or the endpoint is not part of your plan. |
| 404 | Not Found | The path is wrong. This API has `GET /v1/health`, `POST /v1/openapi/validate`, `POST /v1/jsonschema/validate`, `POST /v1/openapi/diff` and `GET /v1/rules`. |
| 413 | Payload Too Large | The request body is over 2 MB. |
| 422 | Unprocessable Entity | The body is not valid JSON, a required field is missing, the YAML cannot be parsed, or the document is too large or too slow to check. |
| 429 | Too Many Requests | You sent more than 10 requests per second. Wait for the time in `Retry-After` and try again. |
| 500 | Internal Server Error | Something failed on the provider side. Retry once; if it keeps failing, contact us. |
| 503 | Service Unavailable | The service is briefly unavailable. Retry after a short pause. |

## Rate Limits

Every plan allows up to 10 requests per second, and each request counts as one call whatever it returns.

Monthly quotas:

*   **Free**: 15 calls, a one-time 7-day trial.
*   **Pro**: 10,000 calls.
*   **Ultra**: 60,000 calls.
*   **Mega**: 300,000 calls.

Going over 10 requests per second returns `429 Too Many Requests`. Back off when you get a 429 and honour the `Retry-After` header before retrying.

## FAQ

*   **Which OpenAPI versions are supported?**

    Validation supports Swagger 2.0 and OpenAPI 3.0, 3.1 and 3.2. The diff supports OpenAPI 3.x only, so convert Swagger 2.0 first.

*   **Why don't I get line numbers?**

    Line and column come from text input. Send the document as a YAML or JSON string instead of a JSON object.

*   **Are external `$ref`s followed?**

    No. External references are listed in `unresolved_refs` and never fetched, so the API makes no network calls.

*   **What counts as breaking?**

    A change that can break an existing client, such as a removed path, a new required parameter or a removed response property. Debatable cases, such as a new enum value in a response, are warnings, and `GET /v1/rules` lists every kind with its severity.

*   **Is my document stored?**

    No. Documents are parsed in memory with safe YAML loading and are not logged or stored.

## Contact Us

If you have any questions or need assistance, use the embedded chat on the bottom right corner of the page or email hello@bytestay.pt.

Website: [specwise.bytestay.pt](https://specwise.bytestay.pt)


Validate OpenAPI 2.0 to 3.2 and JSON Schema over HTTP with line-level errors, and diff two OpenAPI versions to flag breaking changes in CI.

Specwise API: OpenAPI Validator and Breaking-Change Diff

Specwise OpenAPI Validator and Diff