com.tituslegaldesign.immigration.agreementEvent Documentation (EN)

main record

An append-only changelog entry for a 287(g) agreement record. One event is written every time the sync detects a change: a new agreement, a cancellation, a field-level modification, or a data correction. Together these events form the public changelog that ICE's snapshot-only publishing omits. Record key is a TID (timestamp identifier); events are never updated or deleted. Events carry the CID of the agreement record version they describe, so a third party holding an older CAR export can verify that an event describes the bytes they already have.

Record Key tid Timestamp-based ID

Properties

changes array of ref #fieldChange Optional

Field-level before/after values, for modified and corrected events.

maxLength: 50 items

effectiveDate string datetime Optional

When the underlying change took effect in the real world, if known (e.g. the signed or canceled date). May precede recordedAt, and for backfill events usually precedes it by years.

effectiveDateText string Optional

effectiveDate as a plain calendar date, YYYY-MM-DD, no timezone. Preferred for display.

maxLength: 10 bytes

eventType string Required

signed = new agreement appeared; canceled = agreement ended; reinstated = a canceled agreement became active again; modified = a substantive field changed (model, dates, reimbursements); corrected = publisher fixed a data error (spelling, population, geography).

Known values: signed, canceled, reinstated, modified, corrected

note string Optional

Optional human-readable context for the change.

maxLength: 2000 bytes

priorCid string cid Optional

CID of the agreement record immediately BEFORE this event. Absent for the first event on a record. Together with subjectCid this chains events into a verifiable version history.

provenance string Required

observed = the sync detected this change between two of its own runs, so recordedAt is a real observation time. backfill = the event was reconstructed at initial publication from a historical snapshot; recordedAt is the import time and carries no information about when the change was noticed. Consumers plotting change-over-time should exclude or separately handle backfill events.

Known values: observed, backfill

recordedAt string datetime Required

When this event record was written. For provenance=observed this is when the sync saw the change; for provenance=backfill it is merely the import time.

source string at-uri Optional

AT URI of the com.tituslegaldesign.immigration.sourceSnapshot record this change was derived from, where one was archived.

subject string at-uri Required

AT URI of the agreement record this event describes, e.g. at://did:plc:xxx/com.tituslegaldesign.immigration.agreement/ga-tift-county-so-tfm

subjectCid string cid Required

CID of the agreement record as it stands immediately AFTER this event. Pins the exact version described. An AT-URI alone points at whatever the record says now, which is not the same thing.

subjectSlug string Optional

The agreement's rkey slug, denormalized for convenience.

maxLength: 200 bytes

View raw schema

{
  "description": "An append-only changelog entry for a 287(g) agreement record. One event is written every time the sync detects a change: a new agreement, a cancellation, a field-level modification, or a data correction. Together these events form the public changelog that ICE's snapshot-only publishing omits. Record key is a TID (timestamp identifier); events are never updated or deleted. Events carry the CID of the agreement record version they describe, so a third party holding an older CAR export can verify that an event describes the bytes they already have.",
  "key": "tid",
  "record": {
    "properties": {
      "changes": {
        "description": "Field-level before/after values, for modified and corrected events.",
        "items": {
          "ref": "#fieldChange",
          "type": "ref"
        },
        "maxLength": 50,
        "type": "array"
      },
      "effectiveDate": {
        "description": "When the underlying change took effect in the real world, if known (e.g. the signed or canceled date). May precede recordedAt, and for backfill events usually precedes it by years.",
        "format": "datetime",
        "type": "string"
      },
      "effectiveDateText": {
        "description": "effectiveDate as a plain calendar date, YYYY-MM-DD, no timezone. Preferred for display.",
        "maxLength": 10,
        "type": "string"
      },
      "eventType": {
        "description": "signed = new agreement appeared; canceled = agreement ended; reinstated = a canceled agreement became active again; modified = a substantive field changed (model, dates, reimbursements); corrected = publisher fixed a data error (spelling, population, geography).",
        "knownValues": [
          "signed",
          "canceled",
          "reinstated",
          "modified",
          "corrected"
        ],
        "type": "string"
      },
      "note": {
        "description": "Optional human-readable context for the change.",
        "maxLength": 2000,
        "type": "string"
      },
      "priorCid": {
        "description": "CID of the agreement record immediately BEFORE this event. Absent for the first event on a record. Together with subjectCid this chains events into a verifiable version history.",
        "format": "cid",
        "type": "string"
      },
      "provenance": {
        "description": "observed = the sync detected this change between two of its own runs, so recordedAt is a real observation time. backfill = the event was reconstructed at initial publication from a historical snapshot; recordedAt is the import time and carries no information about when the change was noticed. Consumers plotting change-over-time should exclude or separately handle backfill events.",
        "knownValues": [
          "observed",
          "backfill"
        ],
        "type": "string"
      },
      "recordedAt": {
        "description": "When this event record was written. For provenance=observed this is when the sync saw the change; for provenance=backfill it is merely the import time.",
        "format": "datetime",
        "type": "string"
      },
      "source": {
        "description": "AT URI of the com.tituslegaldesign.immigration.sourceSnapshot record this change was derived from, where one was archived.",
        "format": "at-uri",
        "type": "string"
      },
      "subject": {
        "description": "AT URI of the agreement record this event describes, e.g. at://did:plc:xxx/com.tituslegaldesign.immigration.agreement/ga-tift-county-so-tfm",
        "format": "at-uri",
        "type": "string"
      },
      "subjectCid": {
        "description": "CID of the agreement record as it stands immediately AFTER this event. Pins the exact version described. An AT-URI alone points at whatever the record says now, which is not the same thing.",
        "format": "cid",
        "type": "string"
      },
      "subjectSlug": {
        "description": "The agreement's rkey slug, denormalized for convenience.",
        "maxLength": 200,
        "type": "string"
      }
    },
    "required": [
      "subject",
      "subjectCid",
      "eventType",
      "provenance",
      "recordedAt"
    ],
    "type": "object"
  },
  "type": "record"
}

fieldChange object

No description available.

Properties

field string Required

Name of the agreement-record field that changed.

maxLength: 100 bytes

newValue string Optional

New value, stringified. Absent when the field was removed.

maxLength: 3000 bytes

oldValue string Optional

Previous value, stringified. Absent when the field was newly set. Sized to hold a full notes field.

maxLength: 3000 bytes

truncated boolean Optional

True when oldValue or newValue was cut to fit. Consumers must not treat a truncated value as the literal field contents.

View raw schema

{
  "properties": {
    "field": {
      "description": "Name of the agreement-record field that changed.",
      "maxLength": 100,
      "type": "string"
    },
    "newValue": {
      "description": "New value, stringified. Absent when the field was removed.",
      "maxLength": 3000,
      "type": "string"
    },
    "oldValue": {
      "description": "Previous value, stringified. Absent when the field was newly set. Sized to hold a full notes field.",
      "maxLength": 3000,
      "type": "string"
    },
    "truncated": {
      "description": "True when oldValue or newValue was cut to fit. Consumers must not treat a truncated value as the literal field contents.",
      "type": "boolean"
    }
  },
  "required": [
    "field"
  ],
  "type": "object"
}