JSON Schema Diff

Overview

You send the old and the new version of a JSON Schema and we sort every difference into three buckets: breaking, non-breaking, and ambiguous. The yardstick is consumer-first backward compatibility — data written against the old schema should still validate against the new one. We look at type, required, properties, enum, the six size and range constraints, and additionalProperties, and every change comes back with the path where it happened. To check a payload against a schema, use schema.validate_json; to build a schema from sample data, use schema.infer_json_schema. Accepts file input via file_ref — no need to extract file content first.

Schemas keep moving, and the cost of a breaking change lands on whoever consumes your data. You get a deterministic verdict before you publish, instead of a support ticket afterwards.

When to use it

Scope

Non-goals

• We never check a document against a schema — that is schema.validate_json
• We never merge the two schemas into a combined version
• We never follow a remote $ref or fetch anything from the network

Properties

Capabilities

Cost & billing

Flat rate per invocation

File handling

File limits

Constraints this skill applies to your input and generated files. The “Limited by” column shows the static source of each cap; none of these can be raised by upgrading your plan.

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.diff_json_schema","input":{"oldSchema":"{\"type\":\"object\"}","newSchema":"{\"type\":\"object\",\"properties\":{\"email\":{\"type\":\"string\"}}}"}}'

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

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

const { output } = await sq.execute("schema.diff_json_schema", {"oldSchema":"{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\"}},\"required\":[\"name\"]}","newSchema":"{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\"},\"email\":{\"type\":\"string\"}},\"required\":[\"name\"]}"});

Errors

Other limits

Limitations

• We never check a document against a schema — that is schema.validate_json
• We never merge the two schemas into a combined version
• We never follow a remote $ref or fetch anything from the network
• Validating data against a schema — use schema.validate_json
• Merging two schemas into one
• Inferring schemas from data — use schema.infer_json_schema

How to call

POST /v1/execute (requires authentication)

{
  "skillKey": "schema.diff_json_schema",
  "input": {
    "oldSchema": "{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\"}},\"required\":[\"name\"]}",
    "newSchema": "{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\"},\"email\":{\"type\":\"string\"}},\"required\":[\"name\"]}"
  }
}

Examples

{
  "oldSchema": "{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\"}},\"required\":[\"name\"]}",
  "newSchema": "{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\"},\"email\":{\"type\":\"string\"}},\"required\":[\"name\"]}"
}

{
  "ambiguous": [],
  "totalChanges": 1,
  "nonBreaking": [
    {
      "path": "/properties/email",
      "changeType": "property_added_optional",
      "description": "New optional property 'email' added"
    }
  ],
  "compatible": true,
  "breaking": []
}

{
  "oldSchema": "{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"integer\"}},\"required\":[\"id\"]}",
  "newSchema": "{\"type\":\"object\",\"properties\":{\"id\":{\"type\":\"string\"}},\"required\":[\"id\"]}"
}

{
  "ambiguous": [],
  "totalChanges": 1,
  "nonBreaking": [],
  "compatible": false,
  "breaking": [
    {
      "path": "/properties/id/",
      "changeType": "type_changed",
      "description": "Type changed from \"integer\" to \"string\""
    }
  ]
}

Recommended use cases

• API contract compatibility checks during schema evolution
• CI/CD gates that block deployments on breaking changes
• Schema version review before publishing updated contracts

Avoid for

• Validating data against a schema — use schema.validate_json
• Merging two schemas into one
• Inferring schemas from data — use schema.infer_json_schema

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