Address

A mailing address and a collection of addresses for a person or organization.

Address

A mailing address.

Property	Type	Required	Description
street1	string	Yes	The primary street address line.
street2	string	No	Additional street address information (e.g., apartment number, suite, etc.).
city	string	Yes	The city or municipality name.
stateOrProvince	string	Yes	The state, province, or region name.
country	string	Yes	The country name or ISO country code.
postalCode	string	Yes	The postal or ZIP code for the address.
latitude	number	No	The latitude coordinate of the address location.
longitude	number	No	The longitude coordinate of the address location.
geography	RecordUnknown	No	Additional geospatial data in GeoJSON format.
period	AddressPeriod	No	The time period during which the address was occupied.

Example

{
  "street1": "123 Main St",
  "city": "Anytown",
  "stateOrProvince": "CA",
  "country": "US",
  "postalCode": "12345"
}

JSON Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: Address.yaml
type: object
properties:
  street1:
    type: string
    description: The primary street address line.
  street2:
    type: string
    description: Additional street address information (e.g., apartment number, suite, etc.).
  city:
    type: string
    description: The city or municipality name.
  stateOrProvince:
    type: string
    description: The state, province, or region name.
  country:
    type: string
    description: The country name or ISO country code.
  postalCode:
    type: string
    description: The postal or ZIP code for the address.
  latitude:
    type: number
    description: The latitude coordinate of the address location.
  longitude:
    type: number
    description: The longitude coordinate of the address location.
  geography:
    $ref: "#/$defs/RecordUnknown"
    description: Additional geospatial data in GeoJSON format.
  period:
    $ref: AddressPeriod.yaml
    description: The time period during which the address was occupied.
required:
  - street1
  - city
  - stateOrProvince
  - country
  - postalCode
examples:
  - street1: 123 Main St
    city: Anytown
    stateOrProvince: CA
    country: US
    postalCode: "12345"
description: A mailing address.
$defs:
  RecordUnknown:
    type: object
    properties: {}
    unevaluatedProperties: {}

TypeSpec

/** A mailing address. */
@example(Examples.Address.apartment)
@Versioning.added(Versions.v0_1)
model Address {
  /** The primary street address line. */
  street1: string;

  /** Additional street address information (e.g., apartment number, suite, etc.). */
  street2?: string;

  /** The city or municipality name. */
  city: string;

  /** The state, province, or region name. */
  stateOrProvince: string;

  /** The country name or ISO country code. */
  country: string;

  /** The postal or ZIP code for the address. */
  postalCode: string;

  /** The latitude coordinate of the address location. */
  latitude?: numeric;

  /** The longitude coordinate of the address location. */
  longitude?: numeric;

  /** Additional geospatial data in GeoJSON format. */
  geography?: Record<unknown>;

  /** The time period during which the address was occupied. */
  period?: AddressPeriod;
}

AddressPeriod

The time period during which a household or person occupied an address. `endDate` is `null` (or omitted) for currently-occupied addresses; `isCurrent` is the authoritative signal regardless of date values.

Property	Type	Required	Description
startDate	isoDate	Yes	The date the address was first occupied, in ISO 8601 (YYYY-MM-DD).
endDate	isoDate | null	No	The date the address was vacated. `null` if currently occupied.
isCurrent	boolean	Yes	`true` if this is the current address.

Example

{
  "startDate": "2020-01-01",
  "endDate": "2023-05-31",
  "isCurrent": false
}

JSON Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: AddressPeriod.yaml
type: object
properties:
  startDate:
    $ref: isoDate.yaml
    description: The date the address was first occupied, in ISO 8601 (YYYY-MM-DD).
  endDate:
    anyOf:
      - $ref: isoDate.yaml
      - type: "null"
    description: The date the address was vacated. `null` if currently occupied.
  isCurrent:
    type: boolean
    description: "`true` if this is the current address."
required:
  - startDate
  - isCurrent
examples:
  - startDate: 2020-01-01
    endDate: 2023-05-31
    isCurrent: false
  - startDate: 2023-06-01
    endDate: null
    isCurrent: true
description: |-
  The time period during which a household or person occupied an address.

  `endDate` is `null` (or omitted) for currently-occupied addresses;
  `isCurrent` is the authoritative signal regardless of date values.

TypeSpec

/** The time period during which a household or person occupied an address.
 *
 * `endDate` is `null` (or omitted) for currently-occupied addresses;
 * `isCurrent` is the authoritative signal regardless of date values.
 */
@example(Examples.Address.currentPeriod)
@example(Examples.Address.previousPeriod)
@Versioning.added(Versions.v0_1)
model AddressPeriod {
  /** The date the address was first occupied, in ISO 8601 (YYYY-MM-DD). */
  startDate: Types.isoDate;

  /** The date the address was vacated. `null` if currently occupied. */
  endDate?: Types.isoDate | null;

  /** `true` if this is the current address. */
  isCurrent: boolean;
}

AddressCollection

A collection of addresses with named slots for residential and mailing addresses plus an open map of additional addresses keyed by a caller-defined label (e.g., "previous", "work", "satellite").

Property	Type	Required	Description
residential	Address	Yes	The primary residential address.
mailing	Address	No	The mailing address, if different from the residential address.
otherAddresses	RecordAddress	No	Additional addresses keyed by a caller-defined label (e.g., "previous", "work").

Example

{
  "residential": {
    "street1": "456 Main St",
    "street2": "Suite 100",
    "city": "Anytown",
    "stateOrProvince": "CA",
    "country": "US",
    "postalCode": "12345"
  },
  "mailing": {
    "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"
    }
  }
}

JSON Schema

$schema: https://json-schema.org/draft/2020-12/schema
$id: AddressCollection.yaml
type: object
properties:
  residential:
    $ref: Address.yaml
    description: The primary residential address.
  mailing:
    $ref: Address.yaml
    description: The mailing address, if different from the residential address.
  otherAddresses:
    $ref: "#/$defs/RecordAddress"
    description: Additional addresses keyed by a caller-defined label (e.g., "previous", "work").
required:
  - residential
examples:
  - residential:
      street1: 456 Main St
      street2: Suite 100
      city: Anytown
      stateOrProvince: CA
      country: US
      postalCode: "12345"
    mailing:
      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
  - residential:
      street1: 123 Main St
      city: Denver
      stateOrProvince: CO
      country: US
      postalCode: "80201"
      period:
        startDate: 2023-06-01
        endDate: null
        isCurrent: true
    otherAddresses:
      previous:
        street1: 456 Oak Ave
        city: Aurora
        stateOrProvince: CO
        country: US
        postalCode: "80010"
        period:
          startDate: 2020-01-01
          endDate: 2023-05-31
          isCurrent: false
description: |-
  A collection of addresses with named slots for residential and mailing
  addresses plus an open map of additional addresses keyed by a
  caller-defined label (e.g., "previous", "work", "satellite").
$defs:
  RecordAddress:
    type: object
    properties: {}
    unevaluatedProperties:
      $ref: Address.yaml

TypeSpec

/** A collection of addresses with named slots for residential and mailing
 * addresses plus an open map of additional addresses keyed by a
 * caller-defined label (e.g., "previous", "work", "satellite").
 */
@example(Examples.Address.personalCollection)
@example(Examples.Address.orgCollection)
@Versioning.added(Versions.v0_1)
model AddressCollection {
  /** The primary residential address. */
  residential: Address;

  /** The mailing address, if different from the residential address. */
  mailing?: Address;

  /** Additional addresses keyed by a caller-defined label (e.g., "previous", "work"). */
  otherAddresses?: Record<Address>;
}