TAP Attribute Dictionary JSON Representation

v1.0.0 April 2021

About the JSON Representation

The TAP Attribute Dictionary JSON Representation describes how to represent Attribute Dictionary attributes in JSON. For compactness, this document uses the term "TAD-JSON" to refer to the JSON Representation of the Attribute Dictionary.

TAD-JSON is represented as a JSON object, that is a pair of curly braces surrounding zero or more JSON members. It is possible (and perhaps even expected) for a TAD-JSON object to itself be embedded in a broader JSON document, for example for message transport purposes.

Example TAD-JSON Object

{
  "meta": {
    "id": "14874930-d274-4a1b-881a-3aee78235dbf",
    "created": "2020-08-28T20:10:38Z",
    "lastModified": "2020-08-29T03:17:55Z",
    "release": "public"
  }
}

Attribute Data Types

All Attribute Data Types defined in the Attribute Dictionary map to JSON strings, except as follows:

binary: Maps to JSON string, but value is base64 encoded
boolean: Maps to JSON true or false
integer: Maps to JSON number

Record Metadata

Metadata attributes that apply to the entire record are defined in a JSON member of the TAD-JSON object, identified by the key meta, and consisting of a JSON object whose key/value pairs are any Record Metadata attribute defined in the Attribute Dictionary.

Example Record Metadata

{
  "meta": {
    "id": "5458879",
    "lastModified": "2020-02-27T19:30:03Z"
  },
  "attributes": {
    ...
  }
}

Deleted Records

A record may be indicated as having been deleted using the deleted metadata attribute. When a record is deleted, the id metadata attribute must be included while record attributes should not be included.

Alternately, deleted records may be conveyed via a Protocol specific mechanism, such as an HTTP DELETE request.

Example Deleted Record

{
  "meta": {
    "id": "5458879",
    "lastModified": "2020-02-28T12:05:18Z",
    "deleted": true
  }
}

Attribute Representation

Within the TAD-JSON object, each attribute key is the corresponding Attribute Dictionary attribute. The plural name is used when the attribute may have multiple values, regardless of whether or not multiple values are conveyed in any given transaction. In other words, the attribute name EmailAddresses is always used even if only one email address is being sent across the wire, as long as the context permits multiple email addresses.

TAD-JSON defines several different representations for attributes. It is up to each Protocol to determine which formats to use in which context.

Simple Attribute

A Simple Attribute is a single key/value pair, where the value is an appropriate JSON type (ie: neither an object nor an array).

Example Simple Attribute

{
  "dateOfBirth": "1983-03-18"
}

Simple Attribute With Multiple Values

To represent multiple values for a simple attribute, a JSON array is used with the plural attribute name.

Example Simple Attribute With Multiple Values

{
  "citizenships": [
    "CA",
    "NL"
  ]
}

Simple Attribute With Metadata

Adding metadata to a simple attribute requires the use of a JSON object, which will have two keys: meta and value. value is of an appropriate JSON type (neither an object nor an array), while meta is a JSON object holding the desired metadata attributes.

Example Simple Attribute With Metadata

{
  "dateOfBirth": {
    "meta": {
      "id": "179865",
      "created": "2017-08-21T14:27:55Z",
      "source": "sis"
    }
    "value": "1983-03-18"
  }
}

Complex Attribute

A Complex Attribute is represented as a JSON object, whose members are key/value pairs or, if appropriate, sub-objects.

Example Complex Attributes

{
  "emailAddress": {
    "address": "plee@university.edu",
    "type": "official",
    "verified": true
  },
  "role": {
    "affiliation": "faculty",
    "address": {
      "streetAddress": "127 University Drive",
      "room": "305C",
      "type": "office"
    }
  }
}

Complex Attribute With Multiple Values

To represent multiple values for a complex object, a JSON array is used with the plural attribute name.

Example Complex Attributes With Multiple Values

{
  "names": [
    {
      "given": "Patricia",
      "family": "Lee",
      "type": "official"
    },
    {
      "given": "Pat",
      "family": "Lee",
      "type": "preferred"
    }
  ]
}

Complex Attribute With Metadata

Metadata can be added to complex attributes in two ways, depending on what the metadata is intended to represent. A meta block applied to the JSON object itself applies to the entire complex attribute. Additionally, component attributes may use the Simple Attribute With Metadata form to apply metadata to each component.

Example Complex Attribute With Metadata

{
  "emailAddress": {
    "meta": {
      "created": "2018-01-03T09:18:21Z",
      "source": "selfservice"
    }
    "address": "plee@social.com",
    "type": "preferred",
    "verified": {
      "meta": {
        "source": "emaillink"
      },
      "value": true
    }
  }
}

Ad Hoc Attributes

Ad Hoc Attributes are namespaced using the namespace, a colon :, and the attribute name. For example: university.edu:provider. Ad Hoc attributes may be used anywhere an Attribute Dictionary attribute or subattribute may be used.

Example Ad Hoc Attributes

{
  "emailAddress": {
    "address": "plee@university.edu",
    "type": "official",
    "verified": true,
    "university.edu:mailboxProvider": "OIT Exchange"
  },
  "univerity.edu:campusTrainingLevel": "magenta"
}

Deleted Attributes

Deleted attributes may be represented using the deleted metadata attribute. This implies only those representations that include metadata may use this mechanism.

Deleted attributes may also be implied in Protocol specific contexts. For example, if the Protocol requires a full representation of an object to be transmitted each time, sending an empty value for the attribute or omitting the attribute entirely can represent deletion. If the Protocol permits a partial representation of an object (ie: a "patch"), then sending an empty value for the attribute may represent deletion.

JSON Schema

The Attribute Dictionary is available in a (XXX link) JSON Schema representation.

For the string type, Attribute Dictionary types are represented using the format keyword as follows:

caseSensitive: Indicates a case-sensitive attribute of the Attribute Dictionary.
country: Indicates an attribute of the Attribute Dictionary type country.
extensible: Indicates an attribute of the Attribute Dictionary type string, with the pre-defined values listed in the enum keyword as specified in the Attribute Dictionary.
locale: Indicates an attribute of the Attribute Dictionary type locale.
region: Indicates an attribute of the Attribute Dictionary type region.

Organizations that wish to use the JSON Schema representations while also extending the Attribute Dictionary in one way or another will need to create their own versions of these files.

attribute-dictionary/json-representation.adoc