Identifiers

An identifier issued to a record by a registry, such as an organization’s EIN or UEI.

The base Identifier accepts any string value and any registry code. Model-specific identifiers (for example OrgIdEin) are named instantiations of the IdentifierT<Id, Code> template, which constrains the identifier value to a registry-specific format and pins registry.code to a specific registry while keeping the same shape as the base schema. Identifiers are keyed by their canonical CommonGrants registry code (<schema>:<scope>:<prop>, e.g. org:us:ein), which links to a catalog entry via registry.url.

Table

Property	Type	Required	Description
registry	record	No	Registry-level facts shared by every record in this registry.
id	string	No	The primary identifier string, when the registry has a single canonical value. May be omitted for registries with no natural primary; consumers should read `allIds` in that case.
allIds	array<object>	No	Every known identifier for this record in this registry, including archived values.

Formats

Example

A JSON example of this model.

{
  "registry": {
    "code": "org:us:ein",
    "url": "https://commongrants.org/registries/org-us-ein"
  },
  "id": "123456789",
  "allIds": [
    {
      "id": "123456789",
      "status": "active"
    },
    {
      "id": "987654321",
      "status": "archived"
    }
  ]
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: Identifier.yaml
type: object
properties:
  registry:
    type: object
    properties:
      code:
        type: string
        description: Canonical CommonGrants registry code, `<schema>:<scope>:<prop>` (e.g. `org:us:ein`).
      url:
        type: string
        format: uri
        description: Link to the catalog entry for this registry.
    unevaluatedProperties:
      not: {}
    description: Registry-level facts shared by every record in this registry.
  id:
    type: string
    description: |-
      The primary identifier string, when the registry has a single canonical value.

      May be omitted for registries with no natural primary; consumers should read
      `allIds` in that case.
  allIds:
    type: array
    items:
      type: object
      properties:
        id:
          type: string
          description: The identifier string.
        status:
          $ref: IdentifierStatus.yaml
          description: Whether the identifier is currently valid or retired.
      required:
        - id
        - status
      unevaluatedProperties:
        not: {}
    description: Every known identifier for this record in this registry, including archived values.
unevaluatedProperties:
  not: {}
examples:
  - registry:
      code: org:us:ein
      url: https://commongrants.org/registries/org-us-ein
    id: "123456789"
    allIds:
      - id: "123456789"
        status: active
      - id: "987654321"
        status: archived
  - registry:
      code: org:us:ein
      url: https://commongrants.org/registries/org-us-ein
    id: "123456789"
description: |-
  An identifier issued to a record by a registry.

  Accepts any string value and any registry code. Model-specific collections use
  registry-typed instantiations of `IdentifierT` (e.g. `OrgIdEin`) for their base
  identifiers, and this generic form for extension identifiers under `otherIds`.

TypeSpec

The TypeSpec code for this model.

/** An identifier issued to a record by a registry.
 *
 * Template used to define concrete identifier schemas. `Id` constrains the
 * identifier value (e.g. `employerTaxId`); `Code` pins `registry.code` to a
 * specific registry (e.g. `"org:us:ein"`). Both default to a plain string, so
 * `Identifier` is the generic form and named instantiations (e.g. `OrgIdEin`)
 * are the registry-specific forms.
 */
@Versioning.added(CommonGrants.Versions.v0_4)
model IdentifierT<Id extends string = string, Code extends string = string> {
  /** Registry-level facts shared by every record in this registry. */
  registry?: {
    /** Canonical CommonGrants registry code, `<schema>:<scope>:<prop>` (e.g. `org:us:ein`). */
    code?: Code;

    /** Link to the catalog entry for this registry. */
    url?: url;
  };

  /** The primary identifier string, when the registry has a single canonical value.
   *
   * May be omitted for registries with no natural primary; consumers should read
   * `allIds` in that case.
   */
  id?: Id;

  /** Every known identifier for this record in this registry, including archived values. */
  allIds?: Array<{
    /** The identifier string. */
    id: Id;

    /** Whether the identifier is currently valid or retired. */
    status: IdentifierStatus;
  }>;
}

/** An identifier issued to a record by a registry.
 *
 * Accepts any string value and any registry code. Model-specific collections use
 * registry-typed instantiations of `IdentifierT` (e.g. `OrgIdEin`) for their base
 * identifiers, and this generic form for extension identifiers under `otherIds`.
 */
@example(Examples.Identifier.ein)
@example(Examples.Identifier.multiValue)
@Versioning.added(CommonGrants.Versions.v0_4)
model Identifier is IdentifierT<string, string>;

Changelog

Version	Changes	Schema
0.4.0	Added Identifier model	Identifier.yaml

SystemId

The hosting system’s own identifier for a record. It constrains the identifier value to a uuid, the record’s UUID within the hosting system, while the registry.code names that system (e.g. org:grants.gov:system). Collections reference it through their systemId field.

Table

Property	Type	Required	Description
registry	record	No	Registry-level facts shared by every record in this registry.
id	uuid	No	The primary identifier string, when the registry has a single canonical value. May be omitted for registries with no natural primary; consumers should read `allIds` in that case.
allIds	array<object>	No	Every known identifier for this record in this registry, including archived values.

Formats

Example

A JSON example of this model.

{
  "registry": {
    "code": "org:grants.gov:system",
    "url": "https://commongrants.org/registries/org-grants-gov-system"
  },
  "id": "01912a8b-7c3d-7890-abcd-ef1234567890"
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: SystemId.yaml
type: object
properties:
  registry:
    type: object
    properties:
      code:
        type: string
        description: Canonical CommonGrants registry code, `<schema>:<scope>:<prop>` (e.g. `org:us:ein`).
      url:
        type: string
        format: uri
        description: Link to the catalog entry for this registry.
    unevaluatedProperties:
      not: {}
    description: Registry-level facts shared by every record in this registry.
  id:
    $ref: uuid.yaml
    description: |-
      The primary identifier string, when the registry has a single canonical value.

      May be omitted for registries with no natural primary; consumers should read
      `allIds` in that case.
  allIds:
    type: array
    items:
      type: object
      properties:
        id:
          $ref: uuid.yaml
          description: The identifier string.
        status:
          $ref: IdentifierStatus.yaml
          description: Whether the identifier is currently valid or retired.
      required:
        - id
        - status
      unevaluatedProperties:
        not: {}
    description: Every known identifier for this record in this registry, including archived values.
unevaluatedProperties:
  not: {}
examples:
  - registry:
      code: org:grants.gov:system
      url: https://commongrants.org/registries/org-grants-gov-system
    id: 01912a8b-7c3d-7890-abcd-ef1234567890
description: |-
  The hosting system's own identifier for a record.

  The identifier value is the record's UUID within the hosting system; the
  registry code names that system (e.g. `org:grants.gov:system`).

TypeSpec

The TypeSpec code for this model.

/** The hosting system's own identifier for a record.
 *
 * The identifier value is the record's UUID within the hosting system; the
 * registry code names that system (e.g. `org:grants.gov:system`).
 */
@example(Examples.Identifier.systemId)
@Versioning.added(CommonGrants.Versions.v0_4)
model SystemId is IdentifierT<Types.uuid>;

Changelog

Version	Changes	Schema
0.4.0	Added SystemId model	SystemId.yaml

IdentifierCollection

A collection of identifiers associated with a record, keyed by registry code. Includes the hosting system’s own SystemId under systemId and an otherIds extension point for registries the protocol does not define as a base identifier on the model. Model-specific collections (for example OrgIds) extend it with their base identifiers.

Table

Property	Type	Required	Description
systemId	SystemId	No	The hosting system's own identifier for this record.
otherIds	record<Identifier>	No	Additional identifiers keyed by their registry code, for registries the protocol does not define as a base identifier on the model.

Formats

Example

A JSON example of this model.

{
  "systemId": {
    "registry": {
      "code": "org:grants.gov:system",
      "url": "https://commongrants.org/registries/org-grants-gov-system"
    },
    "id": "01912a8b-7c3d-7890-abcd-ef1234567890"
  },
  "otherIds": {
    "org:candid:bridge": {
      "registry": {
        "code": "org:candid:bridge"
      },
      "id": "1234567"
    }
  }
}

JSON Schema

The JSON Schema for this model.

$schema: https://json-schema.org/draft/2020-12/schema
$id: IdentifierCollection.yaml
type: object
properties:
  systemId:
    $ref: SystemId.yaml
    description: The hosting system's own identifier for this record.
  otherIds:
    $ref: "#/$defs/RecordIdentifier"
    description: |-
      Additional identifiers keyed by their registry code, for registries the
      protocol does not define as a base identifier on the model.
examples:
  - systemId:
      registry:
        code: org:grants.gov:system
        url: https://commongrants.org/registries/org-grants-gov-system
      id: 01912a8b-7c3d-7890-abcd-ef1234567890
    otherIds:
      org:candid:bridge:
        registry:
          code: org:candid:bridge
        id: "1234567"
description: A collection of identifiers associated with a record.
$defs:
  RecordIdentifier:
    type: object
    properties: {}
    unevaluatedProperties:
      $ref: Identifier.yaml

TypeSpec

The TypeSpec code for this model.

/** A collection of identifiers associated with a record. */
@example(Examples.Identifier.collection)
@Versioning.added(CommonGrants.Versions.v0_4)
model IdentifierCollection {
  /** The hosting system's own identifier for this record. */
  systemId?: SystemId;

  /** Additional identifiers keyed by their registry code, for registries the
   * protocol does not define as a base identifier on the model.
   */
  otherIds?: Record<Identifier>;
}

Changelog

Version	Changes	Schema
0.4.0	Added IdentifierCollection model	IdentifierCollection.yaml