Skip to main content

List Diffs

List schema graph diffs: field additions, removals, and type changes between class versions, risk-classified as safe, moderate, or critical for review.

A schema diff records the structural difference between two consecutive versions of a schema graph class: which fields were added, which were removed, and which changed type. Diffs are computed automatically after each schema generation and carry a risk classification plus a review_status, giving you an auditable review queue over how your document ontology evolves.

Diffs classified safe (additions only) are approved automatically. moderate and critical diffs are created with review_status: "pending" so a human can acknowledge or flag the change via the approve and reject endpoints. Filter by schema_class_id to audit one document type, or by status to build a review queue.

Classification bands: safe means new fields only. moderate means compatible type changes or required-status changes. critical means any field removal, an incompatible type change, or a large structural reorganization.
GET/v1/schema-graph/diffs

Query parameters

schema_class_iduuidFilter diffs to a specific schema class.
statusstringFilter by review_status: pending, approved, or rejected.

curl

Response

Response fields

dataarrayArray of diff objects.
data[].idstringDiff UUID.
data[].schema_class_idstringSchema class UUID this diff belongs to.
data[].from_versionintegerSource version number.
data[].to_versionintegerTarget version number.
data[].review_statusstringReview status: pending, approved, or rejected.
data[].classificationstringRisk classification: safe, moderate, or critical.
data[].added_fieldsarrayFields added in this diff: { name, type }.
data[].removed_fieldsarrayFields removed in this diff: { name, type }.
data[].type_changesarrayFields whose type changed: { name, from_type, to_type }.
data[].created_atstringISO 8601 creation timestamp.
data[].links.selfstringURL to this diff.

Response

{
  "data": [
    {
      "id": "diff-uuid-1",
      "schema_class_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "from_version": 2,
      "to_version": 3,
      "review_status": "pending",
      "classification": "moderate",
      "added_fields": [{ "name": "total", "type": "number" }],
      "removed_fields": [],
      "type_changes": [{ "name": "invoice_date", "from_type": "string", "to_type": "date" }],
      "created_at": "2024-09-14T10:00:00.000Z",
      "links": { "self": "/v1/schema-graph/diffs/diff-uuid-1" }
    }
  ]
}

Errors

Error responses

401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Filter by status=pending to build a review queue for ontology changes. Inspect the added_fields, removed_fields, and type_changes arrays to assess impact, then call POST /v1/schema-graph/diffs/{id}/approve or /reject to record a verdict on each diff. The classification band tells you which diffs need careful review: start with critical.

Related

Approve Diff
Reject Diff
List Versions