core-schema/tap-core-person-schema-create-json-representation.adoc at master · internet2/core-schema

TAP Attribute Dictionary: How to Create a JSON Representation

v 1.1.0 November 2020

About the JSON Representation

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

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

Example TS-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 TAP Schema map to JSON strings, except as follows:

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 TS-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 Core Schema.

Example Record Metadata

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

Attribute Representation

Within the TS-JSON object, each attribute key is the corresponding Core Schema 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.

TS-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 a Core Schema 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"
}