Skip to content
subcloakdocs
subcloak.comDownload

Insights

Schema changes

Catch JSON fields that were added, removed or changed type between successive responses from the same endpoint, and compare the two responses side by side.

The Schema tab watches the shape of JSON responses. When an endpoint returns a field that wasn’t there last time, drops one that was, or changes a field’s type (a number becoming a string, say), the change shows up here. Use it to catch a backend deploy that would break your app before your users do, or to confirm that a migration didn’t change an API’s contract.

Each row is one change to one field, between two responses from the same endpoint.

  1. The kind of change: Removed, Type changed or Added
  2. The field's path in the JSON
  3. What the field was and what it is now
  4. The earlier and later request numbers
The Schema tab showing three changes to GET api.example.com/v1/products/{id} between requests 18 and 19: price removed, id changed from Number to String, and badge added

Review a change

Section titled “Review a change”
  1. Open Insights with ⌥ ⌘ I and click Schema.
  2. Select a change. A bar appears under the table.
  3. Click Compare Responses to open the earlier and later responses side by side in the diff window. See Compare requests.
  4. Click Show Request to select the later request in the main window.

When there’s nothing to report, the tab says No schema changes.

Table columns

Section titled “Table columns”
Column What it shows
(badge) Severity.
Endpoint The method, host and templated path, such as GET api.example.com/v1/products/{id}.
Change Removed (red), Added (green) or Type changed (orange).
Field The field’s path. Nested keys are joined with dots and array items are written [], as in items[].price. The document’s root is $.
Detail For Removed, what it was (was Number). For Added, its type (String). For Type changed, the old and new types (Number → String).
Requests The earlier and later request numbers, such as #18 → #19.

Types are written Object, Array, String, Number, Boolean and Null. A field that held more than one type (for example across array items) lists them all: Number or String for added and removed fields, Null/Number → String for type changes.

Severities

Section titled “Severities”
Change Severity Why
Removed High Code that reads the field will break or get nothing.
Type changed High, or Low when Null is involved Code that parses the field as the old type will fail. A change to or from Null (a field that became nullable, or stopped being null) is Low.
Added Low Usually harmless, but worth knowing about.

How changes are detected

Section titled “How changes are detected”
  1. Cloak Proxy picks the responses to compare: requests to API endpoints (not images, stylesheets, scripts, fonts, media or tunnels) that returned a 2xx status with JSON. A response counts as JSON when its Content-Type contains json or its body starts with {.
  2. It records every key path in each response and the JSON types seen there. Arrays are sampled from their first 50 items, and documents are read to a depth of 24 levels and up to 5,000 paths.
  3. It groups responses by endpoint template, in the order the requests started, and compares each response with the previous one from the same endpoint.
  4. It reports what changed between each pair.

To keep the list readable:

  • Only the top of an added or removed subtree is reported. If a whole shipping object disappears, you see one Removed shipping, not one row per key inside it.
  • Fields inside an array that was empty in one of the two responses aren’t reported, because there were no items to compare.
  • Inside arrays, a field whose types in one response include all the types in the other isn’t reported as a type change. Arrays of mixed objects naturally vary that way.

Because the comparison is always with the previous response, a field that disappears and comes back shows up twice: once as Removed and once as Added.

Schema changes in CI, the report and MCP

Section titled “Schema changes in CI, the report and MCP”
  • The Markdown report lists up to 100 changes with the endpoint, request number, kind, field and detail. See Insights report.
  • cloakctl run --fail-on-schema-change exits with status 1 if any endpoint’s JSON shape changed during the run. See Headless and CI.
  • The MCP server’s insights tool returns changes with section set to schema.
Section titled “Related”
Compare requestsDiff two requests and responses side by side.
EndpointsHow requests are grouped into endpoint templates.
Headless and CIFail a test run when the API contract changes.
Mock SetsRecord responses to replay a known-good backend.