Schema Version Recommendation

Overview

You send the old and new text of a contract plus the version you are on, and we return the bump SemVer 2.0.0 calls for and the version it produces. The comparison is not ours: it is the same engine schema.diff_json_schema uses, so a diff and a recommendation can never disagree. A breaking change is major, an additive one is minor, and a change the engine itself calls ambiguous escalates to major rather than being quietly resolved — an over-recommendation spends a version number, an under-recommendation ships a consumer outage. Every change behind the verdict is cited with its path, its type and the bump it implies. We recommend; code.bump_version computes.

Something has to decide which bump a change deserves. A diff classifies changes and a bump calculator applies a decision, but between them sits a judgement that today is made by hand in a pull request, inconsistently, at the moment everyone wants to ship.

When to use it

Scope

Non-goals

• We never write a version anywhere, touch a file, or contact a registry
• We never compare schemas ourselves: the diff engine does that
• We never downgrade minor to patch — an added optional property is a feature
• We never resolve an ambiguous change quietly; it escalates and is cited

Properties

Capabilities

Cost & billing

Flat rate per invocation

File handling

How we handle your data

Input schema

Output schema

API contract

curl -sS -X POST "$BASE/v1/execute" -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' -d '{"skillKey":"schema.version_contract","input":{"oldContract":"{\"type\":\"object\"}","newContract":"{\"type\":\"string\"}","currentVersion":"1.2.3"}}'

import { Squillify } from "@squillify/sdk";

const sq = new Squillify({ apiKey: process.env.SQUILLIFY_API_KEY });

const { output } = await sq.execute("schema.version_contract", {"oldContract":"{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"integer\"}}}","newContract":"{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\"}}}","currentVersion":"2.4.1"});

Errors

Other limits

Limitations

• We never write a version anywhere, touch a file, or contact a registry
• We never compare schemas ourselves: the diff engine does that
• We never downgrade minor to patch — an added optional property is a feature
• We never resolve an ambiguous change quietly; it escalates and is cited
• Computing a next version from a bump you have already chosen, which code.bump_version does
• Listing the differences themselves, which schema.diff_json_schema does

How to call

POST /v1/execute (requires authentication)

{
  "skillKey": "schema.version_contract",
  "input": {
    "oldContract": "{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"integer\"}}}",
    "newContract": "{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\"}}}",
    "currentVersion": "2.4.1"
  }
}

Examples

{
  "oldContract": "{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"integer\"}}}",
  "newContract": "{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\"}}}",
  "currentVersion": "2.4.1"
}

{
  "compatible": false,
  "recommendedVersion": "3.0.0",
  "breaking": [
    {
      "path": "/properties/id/",
      "changeType": "type_changed",
      "impliedBump": "major"
    }
  ],
  "recommendedBump": "major",
  "summary": {
    "totalChanges": 1,
    "breakingCount": 1,
    "nonBreakingCount": 0,
    "ambiguousCount": 0,
    "truncated": false
  },
  "currentVersionNormalized": "2.4.1",
  "rationale": {
    "rule": "semver-recommend-1",
    "decidedBy": "breaking_change_present",
    "citedChanges": [
      {
        "path": "/properties/id/",
        "changeType": "type_changed",
        "bucket": "breaking",
        "impliedBump": "major"
      }
    ],
    "zeroMajorPolicy": "SEMVER_INITIAL_DEVELOPMENT",
    "ambiguityHandling": "none",
    "preReleaseHandling": "not_present",
    "buildMetadataDropped": false
  }
}

{
  "oldContract": "{\"type\":\"object\"}",
  "newContract": "{\"type\":\"object\"}",
  "currentVersion": "1.0.0"
}

{
  "compatible": true,
  "recommendedVersion": "1.0.0",
  "breaking": [],
  "recommendedBump": "none",
  "summary": {
    "totalChanges": 0,
    "breakingCount": 0,
    "nonBreakingCount": 0,
    "ambiguousCount": 0,
    "truncated": false
  },
  "currentVersionNormalized": "1.0.0",
  "rationale": {
    "rule": "semver-recommend-1",
    "decidedBy": "no_change",
    "citedChanges": [],
    "zeroMajorPolicy": "SEMVER_INITIAL_DEVELOPMENT",
    "ambiguityHandling": "none",
    "preReleaseHandling": "not_present",
    "buildMetadataDropped": false
  }
}

Recommended use cases

• Decide the release number for a schema change in CI
• Show a reviewer which change forced a major bump
• Check whether a proposed contract can ship as a minor release

Avoid for

• Computing a next version from a bump you have already chosen, which code.bump_version does
• Listing the differences themselves, which schema.diff_json_schema does

Related skills

Composable with

Safety & privacy

• Runs without calling any external service.
• Your payloads are never stored permanently.
• Telemetry captures metadata only — never your payload contents.
• We never train models on your payloads.
• No human reviews your payloads.

Tags