First draft of JSON representation (fixes #3)

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.
 

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"
+}
+----