Jurisdiction

A geographic and administrative jurisdiction (federal, state, county, etc.) that scopes a program.

JurisdictionBase

A geographic or administrative unit within which a program operates. Multiple standards (ISO 3166-2, U.S. Census FIPS, U.S. Census GEOID) may be valid identifiers for the same jurisdiction; `identifiers.otherIds` carries those cross-system codes.

Property	Type	Required	Description
id	uuid	Yes	The jurisdiction's unique identifier.
name	string	Yes	Human-readable display name.
level	JurisdictionLevel	Yes	The level of this jurisdiction (country, state, etc.).
identifiers	Identifiers	Yes	System and cross-system identifiers for this jurisdiction.
parent	JurisdictionRef	No	The parent jurisdiction, if any. Null for country-level jurisdictions.

Example

{
  "id": "30a12e5e-5940-4c08-921c-17a8960fcf4b",
  "name": "Colorado",
  "level": {
    "value": "state",
    "description": ""
  },
  "identifiers": {
    "systemId": "30a12e5e-5940-4c08-921c-17a8960fcf4b",
    "otherIds": {
      "iso_3166_2": {
        "registry": "iso_3166_2",
        "value": "US-CO",
        "description": "ISO 3166-2 subdivision code"
      },
      "us_census_fips": {
        "registry": "us_census_fips",
        "value": "08",
        "description": "U.S. Census 2-digit state FIPS code"
      }
    }
  },
  "parent": {
    "id": "40a12e5e-5940-4c08-921c-17a8960fcf4b",
    "name": "United States"
  }
}

JSON Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: JurisdictionBase.yaml
type: object
properties:
  id:
    $ref: uuid.yaml
    description: The jurisdiction's unique identifier.
  name:
    type: string
    description: Human-readable display name.
  level:
    $ref: JurisdictionLevel.yaml
    description: The level of this jurisdiction (country, state, etc.).
  identifiers:
    $ref: Identifiers.yaml
    description: System and cross-system identifiers for this jurisdiction.
  parent:
    $ref: JurisdictionRef.yaml
    description: The parent jurisdiction, if any. Null for country-level jurisdictions.
required:
  - id
  - name
  - level
  - identifiers
examples:
  - id: 30a12e5e-5940-4c08-921c-17a8960fcf4b
    name: Colorado
    level:
      value: state
      description: ""
    identifiers:
      systemId: 30a12e5e-5940-4c08-921c-17a8960fcf4b
      otherIds:
        iso_3166_2:
          registry: iso_3166_2
          value: US-CO
          description: ISO 3166-2 subdivision code
        us_census_fips:
          registry: us_census_fips
          value: "08"
          description: U.S. Census 2-digit state FIPS code
    parent:
      id: 40a12e5e-5940-4c08-921c-17a8960fcf4b
      name: United States
description: |-
  A geographic or administrative unit within which a program operates.

  Multiple standards (ISO 3166-2, U.S. Census FIPS, U.S. Census GEOID) may
  be valid identifiers for the same jurisdiction; `identifiers.otherIds`
  carries those cross-system codes.

TypeSpec

/** A geographic or administrative unit within which a program operates.
 *
 * Multiple standards (ISO 3166-2, U.S. Census FIPS, U.S. Census GEOID) may
 * be valid identifiers for the same jurisdiction; `identifiers.otherIds`
 * carries those cross-system codes.
 */
@example(Examples.Jurisdiction.colorado)
@Versioning.added(Versions.v0_1)
model JurisdictionBase {
  /** The jurisdiction's unique identifier. */
  id: Types.uuid;

  /** Human-readable display name. */
  name: string;

  /** The level of this jurisdiction (country, state, etc.). */
  level: JurisdictionLevel;

  /** System and cross-system identifiers for this jurisdiction. */
  identifiers: Fields.Identifiers;

  /** The parent jurisdiction, if any. Null for country-level jurisdictions. */
  parent?: JurisdictionRef;
}

JurisdictionLevel

The level of a jurisdiction, modeled as an extensible enum so implementations can supply custom levels via the `description` field.

Property	Type	Required	Description
value	JurisdictionLevelOptions	Yes	The selected value, typed to `T`.
customValue	string	No	Caller-defined value when `value` is the `custom` option (or otherwise does not fit a predefined option in `T`).
description	string	No	Human-readable description or annotation for the value.

Example

{
  "value": "country",
  "customValue": "string",
  "description": "string"
}

JSON Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: JurisdictionLevel.yaml
type: object
properties:
  value:
    $ref: JurisdictionLevelOptions.yaml
    description: The selected value, typed to `T`.
  customValue:
    type: string
    description: |-
      Caller-defined value when `value` is the `custom` option (or otherwise
      does not fit a predefined option in `T`).
  description:
    type: string
    description: Human-readable description or annotation for the value.
required:
  - value
description: |-
  The level of a jurisdiction, modeled as an extensible enum so
  implementations can supply custom levels via the `description` field.

TypeSpec

/** The level of a jurisdiction, modeled as an extensible enum so
 * implementations can supply custom levels via the `description` field.
 */
@Versioning.added(Versions.v0_1)
model JurisdictionLevel is Fields.ExtensibleEnumT<JurisdictionLevelOptions>;

// #########################################################
// JurisdictionRef
// #########################################################

/** A denormalized reference to a jurisdiction. Carries enough information
 * to display without a separate lookup. Used for parent references and
 * embedded jurisdiction references on other models.
 */
@Versioning.added(Versions.v0_1)
model JurisdictionRef {
  /** The jurisdiction's unique identifier. */
  id: Types.uuid;

  /** Human-readable display name. */
  name: string;
}

JurisdictionLevelOptions

Predefined set of jurisdiction levels.

Value	Description
country	A nation-state.
state	A first-level subdivision of a country (e.g., U.S. state, Canadian province).
county	A second-level subdivision (e.g., U.S. county).
municipal	A city, town, or other municipality.
tribal	A tribal nation or tribal area.
custom	A caller-defined jurisdiction level.

Example

"country"

JSON Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: JurisdictionLevelOptions.yaml
type: string
enum:
  - country
  - state
  - county
  - municipal
  - tribal
  - custom
description: |-
  Predefined set of jurisdiction levels.

  - `country`: A nation-state.
  - `state`: A first-level subdivision of a country (e.g., U.S. state, Canadian province).
  - `county`: A second-level subdivision (e.g., U.S. county).
  - `municipal`: A city, town, or other municipality.
  - `tribal`: A tribal nation or tribal area.
  - `custom`: A caller-defined jurisdiction level.

TypeSpec

/** Predefined set of jurisdiction levels.
 *
 * - `country`: A nation-state.
 * - `state`: A first-level subdivision of a country (e.g., U.S. state, Canadian province).
 * - `county`: A second-level subdivision (e.g., U.S. county).
 * - `municipal`: A city, town, or other municipality.
 * - `tribal`: A tribal nation or tribal area.
 * - `custom`: A caller-defined jurisdiction level.
 */
@Versioning.added(Versions.v0_1)
enum JurisdictionLevelOptions {
  country,
  state,
  county,
  municipal,
  tribal,
  custom,
}

JurisdictionRef

A denormalized reference to a jurisdiction. Carries enough information to display without a separate lookup. Used for parent references and embedded jurisdiction references on other models.

Property	Type	Required	Description
id	uuid	Yes	The jurisdiction's unique identifier.
name	string	Yes	Human-readable display name.

Example

{
  "id": "30a12e5e-5940-4c08-921c-17a8960fcf4b",
  "name": "string"
}

JSON Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: JurisdictionRef.yaml
type: object
properties:
  id:
    $ref: uuid.yaml
    description: The jurisdiction's unique identifier.
  name:
    type: string
    description: Human-readable display name.
required:
  - id
  - name
description: |-
  A denormalized reference to a jurisdiction. Carries enough information
  to display without a separate lookup. Used for parent references and
  embedded jurisdiction references on other models.

TypeSpec

/** A denormalized reference to a jurisdiction. Carries enough information
 * to display without a separate lookup. Used for parent references and
 * embedded jurisdiction references on other models.
 */
@Versioning.added(Versions.v0_1)
model JurisdictionRef {
  /** The jurisdiction's unique identifier. */
  id: Types.uuid;

  /** Human-readable display name. */
  name: string;
}