A short guide to clearer checks.

Start in the playground

1. Open the playground and choose Validate payload.
2. Use Load example, paste JSON, or open a local JSON file.
3. Run the check. Each failed rule includes an instance path and a readable message.
4. Choose Compare schemas to review a baseline and a candidate revision.
5. Download the JSON report if you want to keep the results.

Payload validation

Ajv validates JSON Schema 2020-12 and draft-07 documents. Types, required fields, enums, local references, composition and supported format rules are evaluated by the validator. Inputs are not coerced and missing fields are not filled in.

{
  "type": "object",
  "properties": {
    "total": { "type": "number", "minimum": 0 }
  },
  "required": ["total"]
}

For that schema, {"total":42.5} satisfies the contract. {"total":"42.5"} does not: a numeric string is still a string.

How revision findings work

Comparison is directional: the left document is the baseline, and the right document is the candidate. Checks identify structural changes that could reject data previously accepted by the baseline.

Breaking

A recognized rule became more restrictive.

Review

The effect needs a human decision.

Compatible

A recognized rule became more permissive.

Findings include JSON Pointer paths. Treat “compatible” as a local finding about that change, not a guarantee that the full API contract is compatible.

Supported scope & limitations

• Validation accepts JSON, not YAML or a complete OpenAPI document.
• Revision checks inspect common types, object properties, required fields, enums, additional properties and size/value bounds.
• Changed advanced rules, including schema composition, may require manual review.
• Remote references are never fetched. Only references resolvable within the document are supported.
• Each editor accepts up to 512 KB of UTF-8 input. A timed-out worker is terminated.
• No hosted CI integration or team account is included in the preview. The Claude AI Migration Explainer is an optional beta that runs from your browser with your own Anthropic key and sends only breaking findings, never your schemas.
• We do not prove full semantic or API request/response compatibility.

Automating contract checks in CI

The repository ships a command-line runner, bin/schemalabs.js, built on the same engine as the playground. A packaged GitHub Action is planned, not released.

node bin/schemalabs.js --baseline s1.json --candidate s2.json
node bin/schemalabs.js --baseline s1.json --candidate s2.json --format json
node bin/schemalabs.js --baseline s1.json --candidate s2.json --format sarif -o results.sarif

• --format text (default) prints one line per finding; json prints the raw result; sarif prints a SARIF v2.1.0 log for GitHub code scanning.
• --output or -o writes the result to a UTF-8 file instead of standard output. Prefer it to shell redirection, which writes UTF-16 in Windows PowerShell 5.1.
• Exit code 1 means at least one Breaking finding, 0 means none, and 2 means a usage or input error.

This workflow compares a schema on the base branch with the pull request version, uploads every finding to code scanning and fails the job on any breaking change, before anything deploys.

name: Schema check
on:
  pull_request:
    paths: ['schemas/**.json']

permissions:
  contents: read
  security-events: write

jobs:
  contract:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - name: Install the Schema Labs CLI
        run: |
          git clone --depth 1 https://github.com/schemalabs-dev/schemalabs.git "$RUNNER_TEMP/schemalabs"
          npm ci --prefix "$RUNNER_TEMP/schemalabs"
      - name: Compare schema revisions
        env:
          BASE_REF: ${{ github.base_ref }}
          SCHEMA: schemas/order.json
        run: |
          git show "origin/$BASE_REF:$SCHEMA" > "$RUNNER_TEMP/base.json"
          node "$RUNNER_TEMP/schemalabs/bin/schemalabs.js" \
            --baseline "$RUNNER_TEMP/base.json" --candidate "$SCHEMA" \
            --format sarif -o results.sarif
      - name: Upload findings to code scanning
        if: always() && hashFiles('results.sarif') != ''
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif
          category: schemalabs

The upload step runs with if: always(), so findings reach the pull request even when the comparison step fails. Breaking, review and compatible findings appear as errors, warnings and notes; with a pretty-printed schema each one points at the line of the changed keyword. Code scanning is available for public repositories; private repositories need GitHub Code Security. For reproducible builds, check out a specific commit of the CLI instead of the default branch.

The same limits apply as in the playground, so treat a passing job as “no recognized breaking change”, not proof of compatibility.

Processing & reports

The worker receives documents from the page and returns computed results. There are no document upload requests. Refreshing the page clears your edits; use Download report before leaving if you want a record.

Reports contain findings, timestamps and mode information, not your full source documents. The website host still receives ordinary requests for site files. Read the privacy notice for that distinction.