Issue 493 - First draft of data type description

docs/data_types.md

@@ -0,0 +1,33 @@
+# XDM Logical Data Types
+
+XDM schemas are defined in terms of JSON Schema and therefore inherit a type model from JSON. While this allows XDM to describe data types represented in JSON directly, it is useful to define the basic logical data types more specifically so that the XDM data model can be more easily mapped to non-JSON representations.
+
+## Data Type Definitions
+
+The following table describes the available data types:
+
+| XDM type  | Range                                                     | JSON Schema type | JSON Schema format |
+| --------- | --------------------------------------------------------- | ---------------- | ------------------ |
+| string    | unlimited                                                 | string           |                    |
+| number    | ±2.23×10^308 to ±1.80×10^308 (IEEE 64-bit floating point) | number           |                    |
+| long      | (-2^53 + 1) - (2^53 + 1) (54-bit signed integer\*)        | integer          |                    |
+| int       | -2^31 - 2^31 (32-bit signed integer)                      | integer          |                    |
+| short     | -2^15 - 2^15 (16-bit signed integer)                      | integer          |                    |
+| byte      | -2^7 - 2^7 (8-bit signed integer)                         | integer          |                    |
+| boolean   | { true, false }                                           | boolean          |                    |
+| date      | n/a                                                       | string           | date\*\*           |
+| date-time | n/a                                                       | string           | date-time\*\*      |
+
+\* While conceptually JSON numbers have no limits on range, in practice they are assumed to be represented as IEEE 64-bit floating point numbers. A JSON Schema integer is represented as the set of numbers that don’t have a decimal part. When this is mapped to what can be represented in 64-bit floating point format, the effective range is approximately that of a 54-bit signed integer (shifted by 1). While this can easly be represented as a 64-bit signed integer, processors must take care not to exceed the valid range when exchanging data between services as XDM.
+
+\*\* Dates and date-times are defined as they are in JSON Schema: strings conforming to [RFC 3339](https://tools.ietf.org/html/rfc3339).
+
+## Describing XDM Data Types in JSON Schema
+
+All fields defined in an XDM schema are interpreted as one of the above types. This interpretation is based on the specified type of the field (via the `type` attribute), the format of the field when present (via the `format`) attribute, and the specified range of the field (via the `minimum` and `maximum` attributes).
+
+Integer fields are interpreted as the smallest integer data type that can contain the specified range. For example, if a "dayOfMonth" field has a minimum value of 1, and a maximum value of 31, it will be intepreted as a "byte" XDM type.
+
+## Explicitly Signaling XDM Data Types
+
+To make interpreting data types from the JSON Schema definition less error prone, schemas MAY explicitly signal the intended data type using the `meta:xdmType` attribute. Explicit signaling of types is optional. Even when the `meta:xdmType` attribute is present, schemas MUST fully define the field in terms of type, format, and range. When the `meta:xdmType` attribute is encountered, processors MUST verify that the JSON Schema description of the field matches the signaled type. When the JSON Schema description of a type and the signaled type do not match, the schema MUST be considered invalid.

docs/introduction.md

@@ -86,3 +86,4 @@ This means, if the JSON representation of two XDM models is identical, then the
 4.  [Abstract and Concrete Schema](abstract.md)
 5.  [Schema Status](status.md)
 6.  [Identifiable Entities](id.md)
+7.  [XDM Logical Data Types](data_types.md)

meta.schema.json

@@ -102,6 +102,23 @@
           "https://ns.adobe.com/xdm/common/desciptors/schemadescriptor#/definitions/descriptor"
       }
     },
+    "meta:xdmType": {
+      "description": "signals the logical data type of a field",
+      "type": "string",
+      "enum": [
+        "string",
+        "number",
+        "long",
+        "int",
+        "short",
+        "byte",
+        "boolean",
+        "date",
+        "date-time",
+        "array",
+        "object"
+      ]
+    },
     "type": {
       "type": "string",
       "const": "object"