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}/{profileName} is multiple path elements, such as common/error or users/user. 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 describe its configurable groups with a configuration profile.

Example

For this discussion, consider an API which has a profile named users/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. The schemas below are presented in YAML notation for easier viewing, but actual schema documents are stored and served in JSON format.

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.