Label Groups and Enumerations

Warning The Apiture Open product line will reach end of life December, 2023. Consumers of the Apiture Open APIs should migrate to the Apiture Digital Banking APIs before that time.


Label Groups are metadata about enumerations or choice groups in the Apiture Digital Banking APIs.

Enumerations

Several string properties in the API request and response bodies are defined with enumeration lists. An enumeration is a JSON Schema construct which constrains a value to one of a finite set of values. In the Apiture Digital Banking APIs, enumerations apply primarily to string values, although it is possible to define enumeration lists for integer values as well. Enumerations use the enum keyword in the JSON schema.

Enumeration lists are statically defined by the API, although new releases of the Apiture Digital Banking APIs may add new enumeration items.

For example, in the Products API, each banking %product has a property named newAccountAvailability which may have one of two values defined by an enum constraint:

    newAccountAvailability:
      title: New Account Availability
      description: Describes if the product is available for opening new accounts.
      type: string
      enum:
        - available
        - notAvailable
      x-apiture-enum: newAccountAvailability

The Products API also includes other enumeration lists, such as feeStructure (unknown, variable, fixed), productAvailability (general, limited), and productTarget (personal, business), and others.

Since the enumeration values are not always fully self-descriptive, the Apiture Digital Banking APIs provide additional metadata that describes the enumerations, defined in the labelGroup schema. This metadata includes a text label (for displaying the value in a client user interface), an optional description, and optional localized variants.

For example, for the Products API, the GET /products/labels operation returns a labelGroups response similar to that shown below. (These calls do not require an authenticated user, only the client API key.) The response is a labelGroups object.

{
  "_profile": "https://api.apiture.com/schemas/common/labelGroups/v1.1.3/profile.json",
  "groups" : {
    "feeStructure": {
      "unknown": {
        "label": "Undetermined fee structure"
      },
      "variable": {
        "label": "A variable rate fee"
      },
      "fixed": {
        "label": "A fixed rate fee"
      }
    },
    "newAccountAvailability": {
      "available": {
        "label": "Users may open new accounts of this type"
      },
      "notAvailable": {
        "label": "Users may not open new accounts of this type"
      }
    },
    "productTarget": {
      "personal": {
        "label": "Banking products for personal use"
      },
      "business": {
        "label": "Banking products for business use"
      }
    }
  }
}

In the response, the groups object lists all the label groups in the API. The keys are the label group names as described in the API. For example, the newAccountAvailability label group is in the response at groups.newAccountAvailability. If a schema has the x-apiture-enum keyword, that value is the key for that enumeration’s label group, as seen in the newAccountAvailability schema shown above:

      x-apiture-enum: newAccountAvailability

Clients can use these metadata for displaying a label for the corresponding string properties, or to generate selection lists in the client application if the client application allows user selection of a value constrained by an enum list.

Choice Groups

Choice groups are similar to enumerations, except that they are dynamically defined by the financial institution rather than being statically defined in the API’s JSON schemas. Choice groups (like enumeration lists) are also described with label groups returned by the getLabels operation.

Schemas with string properties defined by choice label groups are tagged with the x-apiture-choice keyword.

For example, the occupation of a bank customer is defined in the occupation property of the user schema. The set of occupations is defined by the financial institution. Furthermore, this list may vary between institutions. Thus, the set of occupations for a bank customer cannot be defined with a fixed enumeration list in the API JSON Schema. The occupation property is defined by the occupation schema which indicates the choice label group name:

    occupation:
      title: Occupation (v1.0.0)
      description: |-
        The person's occupation.


        The allowed values for this property are defined at runtime in the
        [label group](https://developer.apiture.com/open/concepts/label-groups) named `occupation`
        in the response from the [`getLabels`](#op-getLabels) operation.
      type: string
      x-apiture-choice: occupation

Below is a sample occupation label group in the Users API (shown here in YAML format):

occupation:
  unknown:
    label: Unknown
    code: '0'
    hidden: true
  architectureAndEngineering:
    label: Architecture and Engineering
    code: '17'
  artsDesignEntertainmentSportsAndMedia:
    label: Arts, Design, Entertainment, Sports, and Media
    code: '27'
  businessAndFinancialOperations:
    label: Business and Financial Operations
    code: '13'
  communityAndSocialService:
    label: Community and Social Service
    code: '21'
  computerAndMathematical:
    label: Computer and Mathematical
    code: '15'
  constructionAndExtraction:
    label: Construction and Extraction
    code: '47'
  educationTrainingAndLibrary:
    label: Education, Training, and Library
    code: '25'
  farmingFishingAndForestry:
    label: Farming, Fishing, and Forestry
    code: '45'
  foodPreparationAndServingRelated:
    label: Food Preparation and Serving Related
    code: '35'
  healthcarePractitionersAndTechnical:
    label: Healthcare Practitioners and Technical
    code: '29'
  installationMaintenanceAndRepair:
    label: Installation, Maintenance, and Repair
    code: '49'
  legal:
    label: Legal
    code: '23'
  lifePhysicalAndSciences:
    label: Life, Physical, and Sciences
    code: '19'
  management:
    label: Management
    code: '11'
  militarySpecific:
    label: Military Specific
    code: '55'
  officeAndAdministrativeSupport:
    label: Office and Administrative Support
    code: '43'
  protectiveServices:
    label: Protective Services
    code: '33'
  salesAndRelated:
    label: Sales and Related
    code: '41'
  other:
    label: Other
    code: '254'
  notApplicable:
    label: Not Applicable
    code: '255'

Thus, the client application can prompt an applicant for their occupation by presenting a list derived from the label values:

  • Architecture and Engineering
  • Arts, Design, Entertainment, Sports, and Media
  • Business and Financial Operations
  • Community and Social Service
  • Computer and Mathematical
  • Construction and Extraction
  • Education, Training, and Library
  • Farming, Fishing, and Forestry
  • Food Preparation and Serving Related
  • Healthcare Practitioners and Technical
  • Installation, Maintenance, and Repair
  • Legal
  • Life, Physical, and Sciences
  • Management
  • Military Specific
  • Office and Administrative Support
  • Protective Services
  • Sales and Related
  • Other
  • Not Applicable

Note that the label item unknown has the attribute hidden: true which means the client should not present that item to the user for selection. Therefore, this list does not include the Unknown choice.

If the user selects the occupation Computer and Mathematical, the client should set the user.occupation property to that label’s corresponding key, computerAndMathematical.

(A client application should only set a user’s occupation to one of the items listed in that label group, such as architectureAndEngineering, computerAndMathematical, and so on. The client should not set the occupation property to one of the corresponding label group label values such as Architecture and Engineering or Computer and Mathematical.)