Representation Profiles and Schemas

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


Object representations in Apiture Digital Banking APIs contain a profile identifier which provides run-time type description for the object representation. The profile is a URL which is stored in the reserved _profile property of the object representation The profile URL is the address of a JSON resource which provides metadata about resources tagged with that profile.

Profile Syntax

Profile URLs have the pattern

https://api.apiture.com/schemas/{namespace}/{profileName}/v{version}/profile.json

The {namespace} is normally the basePath or the servers[].url of an API which defines the profile (with any / removed). {profileName} is the name of a schema defined by that API. The namespace common is used for reusable schemas not defined by a specific API. The {version} is a semantic version of the resource schema.

Note: A GET on the profile URL may return a redirect.

Profile Use Cases

  • static types defined in OpenAPI documents. These are model schema for API request and response bodies, such as the definitions for a user, an account, or a transfer, or others.
  • dynamic types for user interface forms which a financial institution may require, for example for Digital Account Opening, and other use cases.
  • dynamic types for configuration - a configurable service describes its configurable groups with a configuration profile.

Example

For example, consider the Users API which has a profile namespace users and a profile user which defines the model for an end user.

A basic User JSON representation looks like

{
  "_id": "9604e5f8-da29-4197-b6fb-60a1cfecfba8",
  "_profile" : "https://api.apiture.com/schemas/users/user/v1.0.0/profile.json",
  "username": "Johnny1733",
  "firstName": "John",
  "middleName": "Daniel",
  "lastName": "Smith",
  "preferredName": "John",

  "..." : " ... other properties ...",

  "_links": {
    "self": {
      "href": "https://api.thirdpartybank.com/users/users/9604e5f8-da29-4197-b6fb-60a1cfecfba8"
    }
  }
}

This model might be defined by a primary user schema which in turn depends on (possibly reusable) address and other schemas.

Representation Examples

When a profile describes an OpenAPI request or response representation, the profile can also contain a set of examples. These provide documentation which explain the representation’s model schema.

Profile schema

A profile.json document is a JSON document that contains information about the resource profile. The JSON document contains the following properties:

Name Type Description
name string The name of the type or profile; this is a lowerCamelCase identifier
title string A title for this schema, possibly localized
_id string The ID of the profile (the profile URI)
description string A short text description of the profile, possibly localized
version string The profile’s version such as "1.0.0", following semantic versioning
_links object Links related to the profile; see below

The _links of a profile contain the following JSON HAL links containing additional optional links about the profile. Link relations are:

rel Description
apiture:schema A JSON schema describing the fields and types in a JSON object that uses this resource profile. See JSON Schema below. (This link uses the apiture curie.) These URLs have the form https://api.apiture.com/schema/{namespace}/{schemaName}/v1.0.0/schema.json
describedby Detailed human-readable documentation (nominally, HTML) about the profile and schema (describedby is a standard IANA link relation and thus does not use the apiture: prefix.)
apiture:nextVersion The next version of this profile, if any.
apiture:previousVersion A previous version of this profile, if any.
apiture:latestVersion The latest version of the profile, if this is not the latest.