Identifiers

Canonical system identifier plus a free-form bag of registry-scoped identifiers (e.g., SNAP-CO, SSA, FNS).

Identifiers

A collection of identifiers for a model. Includes the system-assigned identifier (`systemId`) plus an open map of cross-system identifiers (`otherIds`) keyed by a caller-defined label. Model-specific named canonical identifiers (e.g., `ssn` on Person) are added by extending this model in the relevant model file.

Property	Type	Required	Description
systemId	uuid	Yes	The system-assigned identifier.
otherIds	RecordIdEntry	No	Cross-system identifiers keyed by a caller-defined label.

Example

{
  "systemId": "30a12e5e-5940-4c08-921c-17a8960fcf4b",
  "otherIds": {
    "benefits_gov": {
      "registry": "benefits_gov",
      "value": "SNAP-CO",
      "description": "Benefits.gov program identifier"
    }
  }
}

JSON Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: Identifiers.yaml
type: object
properties:
  systemId:
    $ref: uuid.yaml
    description: The system-assigned identifier.
  otherIds:
    $ref: "#/$defs/RecordIdEntry"
    description: Cross-system identifiers keyed by a caller-defined label.
required:
  - systemId
examples:
  - systemId: 30a12e5e-5940-4c08-921c-17a8960fcf4b
    otherIds:
      benefits_gov:
        registry: benefits_gov
        value: SNAP-CO
        description: Benefits.gov program identifier
description: |-
  A collection of identifiers for a model. Includes the system-assigned
  identifier (`systemId`) plus an open map of cross-system identifiers
  (`otherIds`) keyed by a caller-defined label.

  Model-specific named canonical identifiers (e.g., `ssn` on Person) are
  added by extending this model in the relevant model file.
$defs:
  RecordIdEntry:
    type: object
    properties: {}
    unevaluatedProperties:
      $ref: IdEntry.yaml

TypeSpec

/** A collection of identifiers for a model. Includes the system-assigned
 * identifier (`systemId`) plus an open map of cross-system identifiers
 * (`otherIds`) keyed by a caller-defined label.
 *
 * Model-specific named canonical identifiers (e.g., `ssn` on Person) are
 * added by extending this model in the relevant model file.
 */
@example(Examples.Identifiers.programIdentifiers)
@Versioning.added(Versions.v0_1)
model Identifiers {
  /** The system-assigned identifier. */
  systemId: Types.uuid;

  /** Cross-system identifiers keyed by a caller-defined label. */
  otherIds?: Record<IdEntry>;
}

IdEntry

A single cross-system identifier entry. Captures the registry (the system that issued the ID), the value within that registry, and an optional description.

Property	Type	Required	Description
registry	string	Yes	The registry or external system this identifier belongs to (e.g., "iso_3166_2", "co_cbms").
value	string	Yes	The identifier value within that registry.
description	string	No	Optional human-readable description of the identifier.

Example

{
  "registry": "iso_3166_2",
  "value": "US-CO",
  "description": "ISO 3166-2 subdivision code"
}

JSON Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: IdEntry.yaml
type: object
properties:
  registry:
    type: string
    description: The registry or external system this identifier belongs to (e.g., "iso_3166_2", "co_cbms").
  value:
    type: string
    description: The identifier value within that registry.
  description:
    type: string
    description: Optional human-readable description of the identifier.
required:
  - registry
  - value
examples:
  - registry: iso_3166_2
    value: US-CO
    description: ISO 3166-2 subdivision code
description: |-
  A single cross-system identifier entry. Captures the registry (the system
  that issued the ID), the value within that registry, and an optional
  description.

TypeSpec

/** A single cross-system identifier entry. Captures the registry (the system
 * that issued the ID), the value within that registry, and an optional
 * description.
 */
@example(Examples.Identifiers.isoEntry)
@Versioning.added(Versions.v0_1)
model IdEntry {
  /** The registry or external system this identifier belongs to (e.g., "iso_3166_2", "co_cbms"). */
  registry: string;

  /** The identifier value within that registry. */
  value: string;

  /** Optional human-readable description of the identifier. */
  description?: string;
}