diff --git a/README.md b/README.md index 61e0226..e09953f 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ The following types of documents are defined as part of the Core Schema library: * **Representations**: Mappings of the Core Schema to a specific form, such as JSON, XML, or YAML. + * [TAP Core Schema JSON Representation](json-representation.adoc) (CS-JSON) * **Profiles**: Selections of Core Schema attributes for a particular purpose. diff --git a/json-representation.adoc b/json-representation.adoc new file mode 100644 index 0000000..4039858 --- /dev/null +++ b/json-representation.adoc @@ -0,0 +1,213 @@ +Core Schema JSON Representation +=============================== +:Date: August 2020 +:Revision: v1.0.0 + +{revision} {date} + +Copyright (C) 2020 +University Corporation for Advanced Internet Development, Inc. + +About the JSON Representation +----------------------------- +The Core Schema JSON Representation describes how to represent Core Schema +attributes in JSON. For compactness, this document uses the term "CS-JSON" to +refer to the JSON Representation of the Core Schema. + +CS-JSON is represented as a 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 CS-JSON object to itself be embedded in a broader JSON +document, for example for message transport purposes. + +.Example CS-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 Core 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 CS-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 CS-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. + +CS-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" +} +----