Skip to content
CommonGrants

Revision

A revision is a record of a single change to a resource. It captures the merge patch that was submitted, a snapshot of the record with the change applied, and the lifecycle status of the change. Revisions make up the change ledger used for organization profile syncing: every write, whether a direct PATCH or a submitted POST /changes, records a revision, and GET /orgs/{orgId}/changes lists them newest first. A revision’s submission facts (its patch and source) never change, but its status can transition until it reaches a terminal state.

createdAt marks when the change was submitted and orders the ledger, while lastModifiedAt marks when the status last changed.

Revision

Section titled “Revision”

The generic, untyped record of a change, where patch and snapshot are open objects. It is defined as a template, RevisionT<SnapshotT, PatchT>, that a concrete resource binds to its own snapshot and patch types (see OrgRevision).

Table

Section titled “Table”
PropertyTypeRequiredDescription
iduuidYesGlobally unique id for the revision
statusRevisionStatusYesThe lifecycle status of the change
sourcestringNoThe source system the change came from
patchunknownNoThe merge patch that was submitted
snapshotunknownNoA full snapshot of the record with the change applied
createdAtutcDateTimeYesThe timestamp (in UTC) at which the record was created.
lastModifiedAtutcDateTimeYesThe timestamp (in UTC) at which the record was last modified.

Formats

Section titled “Formats”

A JSON example of this model.

{
  "id": "01912a8b-7c3d-7890-abcd-ef1234567890",
  "status": {
    "value": "accepted",
    "description": "The change was applied."
  },
  "source": "grants.gov",
  "patch": {
    "mission": "To expand access to community health resources."
  },
  "snapshot": {
    "id": "01912a8b-7c3d-7890-abcd-ef1234567890",
    "name": "Example Nonprofit",
    "mission": "To expand access to community health resources."
  },
  "createdAt": "2026-06-20T14:30:00Z",
  "lastModifiedAt": "2026-06-20T14:30:00Z"
}

Changelog

Section titled “Changelog”
VersionChangesSchema
0.4.0
  • Added Revision model
Revision.yaml

RevisionStatus

Section titled “RevisionStatus”

The lifecycle status of a change, with a value from a fixed set of options, an optional customValue for implementation-defined states, and an optional human-readable description.

A change moves once from the non-terminal pending state into one of three terminal states. A direct PATCH is created already accepted. A terminal revision is never restated, so an accepted change never later becomes superseded.

Status Terminal Reached by
pending No POST /orgs/{orgId}/changes when the receiver queues for review
accepted Yes PATCH (applied immediately), or a pending change approved
denied Yes a pending change rejected (carries a reason)
superseded Yes a pending change made moot by a competing change accepted first
custom — an implementation-defined state; the receiver documents it

How a receiver resolves a pending change (a human review, a policy engine, a batch job) is out of scope for this contract, so there is no review endpoint. The receiver drives the transition and reports the outcome through the change’s status.

Table

Section titled “Table”
PropertyTypeRequiredDescription
valueRevisionStatusOptionsYesThe selected value, from a predefined set of options
customValuestringNoA custom value, used when the selected value is the `custom` option
descriptionstringNoA human-readable description of the value

Formats

Section titled “Formats”

A JSON example of this model.

{
  "value": "custom",
  "customValue": "escalated",
  "description": "The change was escalated for additional review."
}

Changelog

Section titled “Changelog”
VersionChangesSchema
0.4.0
  • Added RevisionStatus model
RevisionStatus.yaml

RevisionStatusOptions

Section titled “RevisionStatusOptions”

The fixed set of values a RevisionStatus can take: pending, accepted, denied, superseded, and custom.

Formats

Section titled “Formats”

A JSON example of this model.

"pending"

Changelog

Section titled “Changelog”
VersionChangesSchema
0.4.0
  • Added RevisionStatusOptions enum
RevisionStatusOptions.yaml

OrgRevision

Section titled “OrgRevision”

A Revision bound to organization profiles, where patch is an OrgPatchData merge patch and snapshot is an OrganizationBase with that change applied. Returned by the organization write and changes routes.

Table

Section titled “Table”
PropertyTypeRequiredDescription
iduuidYesGlobally unique id for the revision
statusRevisionStatusYesThe lifecycle status of the change
sourcestringNoThe source system the change came from
patchOrgPatchDataNoThe merge patch that was submitted
snapshotOrganizationBaseNoA full snapshot of the record with the change applied
createdAtutcDateTimeYesThe timestamp (in UTC) at which the record was created.
lastModifiedAtutcDateTimeYesThe timestamp (in UTC) at which the record was last modified.

Formats

Section titled “Formats”

A JSON example of this model.

{
  "id": "01912a8b-7c3d-7890-abcd-ef1234567890",
  "status": {
    "value": "accepted",
    "description": "The change was applied."
  },
  "source": "grants.gov",
  "patch": {
    "mission": "To provide support and resources to the community."
  },
  "snapshot": {
    "id": "083b4567-e89d-42c8-a439-6c1234567890",
    "name": "Example Organization",
    "orgType": {
      "term": "Hospital",
      "class": "Organization types",
      "description": "Institutions with the primary purpose of providing in-patient physical and mental health services...",
      "code": "EO000000"
    },
    "identifiers": {
      "org:us:ein": {
        "registry": {
          "code": "org:us:ein",
          "url": "https://commongrants.org/registries/org-us-ein"
        },
        "id": "123456789"
      },
      "org:us:uei": {
        "registry": {
          "code": "org:us:uei",
          "url": "https://commongrants.org/registries/org-us-uei"
        },
        "id": "AB0123456789"
      }
    },
    "addresses": {
      "primary": {
        "street1": "456 Main St",
        "street2": "Suite 100",
        "city": "Anytown",
        "stateOrProvince": "CA",
        "country": "US",
        "postalCode": "12345"
      },
      "otherAddresses": {
        "satellite": {
          "street1": "456 Main St",
          "street2": "Suite 100",
          "city": "Anytown",
          "stateOrProvince": "CA",
          "country": "US",
          "postalCode": "12345"
        },
        "international": {
          "street1": "123 Rue Principale",
          "city": "Montreal",
          "stateOrProvince": "QC",
          "country": "CA",
          "postalCode": "H2Y 1C6"
        }
      }
    },
    "phones": {
      "primary": {
        "countryCode": "+1",
        "number": "444-456-1230",
        "isMobile": true
      },
      "fax": {
        "countryCode": "+1",
        "number": "555-123-4567",
        "extension": "123",
        "isMobile": false
      },
      "otherPhones": {
        "support": {
          "countryCode": "+1",
          "number": "333-456-1230",
          "isMobile": false
        },
        "marketing": {
          "countryCode": "+1",
          "number": "444-456-1230",
          "isMobile": true
        }
      }
    },
    "emails": {
      "primary": "info@example.com",
      "otherEmails": {
        "support": "support@example.com",
        "marketing": "marketing@example.com"
      }
    },
    "mission": "To provide support and resources to the community.",
    "yearFounded": "2024",
    "socials": {
      "website": "https://www.example.com",
      "facebook": "https://www.facebook.com/example",
      "twitterOrX": "https://x.com/example",
      "instagram": "https://www.instagram.com/example",
      "linkedin": "https://www.linkedin.com/company/example",
      "otherSocials": {
        "youtube": "https://www.youtube.com/example"
      }
    }
  },
  "createdAt": "2026-06-20T14:30:00Z",
  "lastModifiedAt": "2026-06-20T14:30:00Z"
}

Changelog

Section titled “Changelog”
VersionChangesSchema
0.4.0
  • Added OrgRevision model
OrgRevision.yaml