($and/ <== DO NOT REMOVE - switch for preventing MathML interpretation of dollar signs on this page)

About

This proposal is to specify XDI serialization formats and their associated MIME types and parameters.

Change Log

Motivations & Requirements

  1. A standard compact serialization syntax for XDI documents.
  2. A syntax that is as intuitive as possible for JSON developers while still losslessly serializing the XDI graph.
  3. A syntax that supports using all JSON datatypes natively as XDI literals, i.e., to be able to get and set JSON arrays, objects, strings, numbers, booleans, and null values from an XDI server.
  4. A syntax that is easy and fast for machines to parse while retaining the full semantics and addressability of XDI.
  5. A syntax that includes unambiguous data type definitions.
  6. At least one syntax that is easy for humans to read and relatively easy to write.
  7. A syntax that can include data serialized in other popular data interchange formats, including XML.

  8. A syntax that can be easily extended to carry other new data serialization formats as they are developed.

XDI Display Formats (Human-Readable Only)

XDI display formats are text documents intended only for for teaching and debugging XDI. There are two XDI display formats:

  1. Single-line display format uses one line per XDI statement.

  2. Double-line display format uses one line per unique XDI subject/predicate "key" and one line per unique XDI object "value".

  3. Triples display format is almost identical to JSON triples format. It uses one line per XDI subject, one line per XDI predicate, and one line per XDI object.

  4. Quad tree display format is almost identical to quad tree format. It uses one line per XDI graph, one line per XDI entity, one line per XDI attribute, and one line per XDI literal.

XDI JSON Serialization Formats (Human- and Machine-Readable)

XDI serialization formats are both human- and machine-readable text documents intended for over-the-wire semantic data interchange. Currently there are three XDI serialization formats all based on JSON:

  1. Flat format is optimized for key-value data storage and access.

  2. Tree format is optimized for traversing an XDI directed graph of nested contexts.

  3. Parse format is a parse tree of XDI statements.

  4. Triples format follows the natural subject-predicate-object structure of an XDI graph.

  5. Quad tree format follows the natural graph root-entity-attribute-literal (REAL) structure of an XDI graph.

XDI Serialization Format Rules

  1. An XDI 1.0 compliant endpoint MUST implement the XDI JSON serialization formats using the MIME types and parameters specified below.
  2. An XDI 1.0 compliant endpoint MAY implement the XDI display formats. Display formats MUST NOT be used as a substitute for the XDI JSON formats for over-the-wire usage of XDI.

MIME Types

  1. The JSON format MUST use the MIME type application/xdi+json.

  2. The XDI Display format MUST use the MIME type text/xdi.

**** THE BALANCE OF THE TEXT BELOW NEEDS TO BE REVISED *****

Parameters

Both the JSON format and the XDI Display format support parameters to control details of the serialization.

Support for some parameters is REQUIRED for an XDI endpoint, support for others is OPTIONAL.

The choice of serialization format as well as the setting of parameter values MUST NOT result in a loss of graph data. In other words, a graph MUST always be serialized in a way that makes it possible to unambiguously re-construct the graph from the serialization.

implied (REQUIRED)

  1. If implied=1, the serialization format MUST include all XDI statements.

  2. If implied=0, the serialization MUST NOT include implied statements. A statement is implied, if one of the following conditions is true:

    1. The statement is a contextual statement, AND the context it represents either
      1. contains at least one sub-context, or
      2. contains a literal node, or
      3. has an outgong relational arc, or
      4. has an incoming relational arc
    2. The statement is a relational statement, AND the relation it represents establishes an inner root, AND that inner root is not empty.
  3. If the parameter is absent, the default is implied=0

inner (REQUIRED)

  1. If inner=1, statements under an inner root MUST be serialized using a "short notation" specific to the serialization format.

  2. If inner=0, statements under an inner root MUST be serialized like any other statement.

  3. If the parameter is absent, the default is inner=1

ordered (OPTIONAL)

  1. If ordered=1, statements in the serialization MUST be ordered as specified in SerializationStatementOrder.

  2. If ordered=0, the ordering of statements in the serialization is undefined.

  3. If the parameter is absent, the default is ordered=0

pretty (OPTIONAL)

  1. If pretty=1, pretty-printing is applied to add white-space to the serialization in order to make it more readable for humans.

  2. If pretty=0, no pretty-printing is applied.

  3. If the parameter is absent, the default is pretty=0

html (OPTIONAL)

  1. If html=1, HTML markup is applied to the serialization in order to make it suitable for display in a web browser.

  2. If html=0, no HTML markup is applied.

  3. If the parameter is absent, the default is html=0


CategoryProposal CategorySerialization CategoryHighPriority

SerializationFormats (last edited 2015-02-09 07:17:19 by drummond-xns)