Configuring address locales

The fields in an address that are either valid or required can vary based on the country or region that the address belongs to. For example, when designating a specific region in a country:

  • A US address uses state
  • A Canadian address uses province
  • A Japanese address uses prefecture

The base configuration of Cloud API comes with locale settings for a wide range of countries. you may need to configure the base configuration locales, and you may need to add new locales.

Properties in the Address schema

In Cloud API, addresses are managed by the Address schema. There are two properties used in the schema to address locale-specific issues.

  • The schema itself has a discriminatorProperty attribute. This attribute defines the field in each address that can be used to determine which fields are required or valid. In the base configuration, this property is set to country. In other words, it is the country of an address that determines which other fields are valid or required.
  • Every property in the schema can have a countryRestricted Boolean property set to true. This marks the property as being restricted to certain countries.

Note that the Address schema does not identify the required and valid fields for each country. This information is declared in the addresses.i18n.yaml file.

The Address schema

The Address schema is defined in common_pl-1.0.schema.json. The following is a portion of the schema. Note the following:

  • The Address itself has the discriminatorProperty set to country.
  • The addressLine1 property is valid for all locales. Therefore, there is no countryRestricted attribute.
  • The province property is not valid for all locales. Therefore, there is an x-gw-extensions.countryRestricted attribute and it is set to true.
"Address": {
  "title": "Address",
  "description": "An `Address` represents a postal address. The fields available on an `Address` 
                  will depend upon the `country` value for the `Address`.",
  "type": "object",
  "x-gw-extensions": {
    "discriminatorProperty": "country"
  },
  "properties": {
    "addressLine1": {
      "title": "Address line 1",
      "description": "The first line of the address",
      "type": "string",
      "x-gw-nullable": true
    },
    ...
    "province": {
      "title": "Province",
      "description": "The province of the address. Only applicable in certain countries.",
      "$ref": "#/definitions/TypeKeyReference",
      "x-gw-nullable": true,
      "x-gw-extensions": {
        "countryRestricted": true,
        "typelist": "State"
      }
    },

The Address mapping

The schema mapping is defined in common_pl-1.0.mapping.json. The following is a portion of the mapping file. Note that if a property is not available for all locales, it has an additional predicate attribute set to Address.RestV1_isFieldAvailable('<propertyName>').

"Address": {
  "schemaDefinition": "Address",
  "root": "entity.Address",
  "properties": {
    "addressLine1": {
      "path": "Address.AddressLine1"
    },
  "province": {
    "path": "Address.State",
    "mapper": "#/mappers/TypeKeyReference",
    "predicate": "Address.RestV1_isFieldAvailable('province')"
  },

The Address updaters

The schema updater is defined in common_pl-1.0.updater.json. The following is a portion of the updater file. Note that if a property is not available for all locales, it has an additional allowed attribute set to Address.RestV1_validateInputField('<propertyName>', srcJson).

"Address": {
  "schemaDefinition": "Address",
  "root": "entity.Address",
  ...
  },
  "properties": {
    "addressLine1": {
      "path": "Address.AddressLine1"
    },
  "province": {
    "path": "Address.State",
    "allowed": "Address.RestV1_validateInputField('province', srcJson)",
    "valueResolver": {
      "typeName": "TypeKeyValueResolver"
    }
  },

Properties in the addresses.i18n.yaml file

The addresses.il8n.yaml file provides information about the required and valid properties for an address based on its country. Every country has its own listing with the following information:

  • The country code, as defined in the Country typelist
  • The name of the country
  • The valid fields for an address in that country
  • The required fields for an address in that country

The following is a portion of the addresses.il8n.yaml file. Note the following:

  • For Canada:
    • The province property is valid and required.
    • The addressLine2 field is valid, but not required.
  • For Japan:
    • The prefecture property is valid and required.
    • The addressLine1Kanji field is valid, but not required.
  • For the United States:
    • The state property is valid and required.
    • The addressLine2 field is valid, but not required.
countries:
  CA:
    name: Canada
    addressFields: addressLine1, addressLine2, addressLine3, city, county, province, postalCode
  addressRequire: addressLine1, city, province, postalCode
  JP:
    name: Japan
    addressFields: addressLine1, addressLine1Kanji, addressLine2, addressLine2Kanji, addressLine3, city, cityKanji, prefecture, postalCode
    addressRequire: addressLine1, city, prefecture, postalCode
US:
    name: United States
    addressFields: addressLine1, addressLine2, addressLine3, city, county, state, postalCode
    addressRequire: addressLine1, city, state, postalCode

Configuration tasks

Schema extensions for the Address schema must be declared in the following files:

  • The Common API schema extension file: common_ext-1.0.schema.json
  • The Common API mapping extension file: common_ext-1.0.mapping.json
  • The Common API updater extension file: common_ext-1.0.updater.json

For detailed information on how to configure schemas, see Endpoint architecture.

Properties that are valid for all locales

If you want to add a custom Address property that is valid for all locales:

  1. Add the field to the Address data model entity.
  2. In the Common API schema extension file, add a property for the field to the Address schema.
  3. In the Common API mapping file, add mapping information for the property.
  4. In the Common API updater file, add updater information for the property.
  5. Add the field to the addressFields section of every country entries in the addresses.il8n.yaml file.

Properties that are valid for some locales

If you want to add a custom Address property that is valid for only some locales:

  1. Add the field to the Address data model entity.
  2. In the Common API schema extension file, add a property for the field to the Address schema.
    • Set the property's x-gw-extensions.countryRestricted attribute to true.
  3. In the Common API mapping file, add mapping information for the property.
    • Add a predicate attribute set to Address.RestV1_isFieldAvailable('<propertyName>').
  4. In the Common API updater file, add updater information for the property.
    • Add an allowed attribute set to Address.RestV1_validateInputField('<propertyName>', srcJson)
  5. Add the field to the addressFields section of the appropriate country entries in the addresses.il8n.yaml file.

Properties that are valid and required for some locales

If you want to add a custom Address property that is valid for only some locales:

  1. Add the field to the Address data model entity.
  2. In the Common API schema extension file, add a property for the field to the Address schema.
    • Set the property's x-gw-extensions.countryRestricted attribute to true.
  3. In the Common API mapping file, add mapping information for the property.
    • Add a predicate attribute set to Address.RestV1_isFieldAvailable('<propertyName>').
  4. In the Common API updater file, add updater information for the property.
    • Add an allowed attribute set to Address.RestV1_validateInputField('<propertyName>', srcJson)
  5. Add the field to the addressFields section and the addressRequire section of the appropriate country entries in the addresses.il8n.yaml file.