Skip to content

Draft #12

Merged
merged 15 commits into from Sep 24, 2020
24 changes: 23 additions & 1 deletion README.md
@@ -1,2 +1,24 @@
# core-schema
TAP Core Schema

## TAP Core Person Schema

The [TAP Core Person Schema](tap-core-person-schema.adoc) defines a dictionary of common
attributes used across various components of the TAP portfolio. The
authoritative Core Schema is abstract -- it cannot be used directly, but is
best thought of as an *attribute library* that can be used to construct other
documents.

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 Person Schema: How to Create a JSON Representation](tap-core-person-schema-create-json-representation.adoc) (CS-JSON)

* **Profiles**: Selections of Core Schema attributes for a particular purpose.

* **Protocols**: A specification for implementation, based on a Representation
and perhaps a Profile. Of all the Core Schema documents, only Protocols are
actually implementable in software.

As an example, the **eduPerson LDAP Schema** would be a *Protocol* that
references the *eduPerson Profile* and the *LDAP Representation*.
213 changes: 213 additions & 0 deletions tap-core-person-schema-create-json-representation.adoc
@@ -0,0 +1,213 @@
TAP Core Person Schema: How to Create a 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"
}
----