Representation Profiles and Schemas

Object representations in Apiture 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 of an API which defines the profile. {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:

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.