Representation Profiles and Schemas

Object representations in Apiture Open 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 this discussion, 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:

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