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


This proposal specifies the core structure and functionality of XDI messages. Additional features are specified by additional proposals, e.g., XDI Signatures. See the Discussion page for comments.

Change Log


XDI messaging is the standard mechanism for sending or receiving XDI data from an XDI endpoint. XDI messages are themselves XDI graphs, so they can be addressed, stored, shared, and controlled like any other XDI data (particularly useful for auditing).

XDI messaging is peer-to-peer between any XDI client and any XDI endpoint, or between any two XDI endpoints. The endpoint URIs of XDI endpoints can be discovered using the XDI Discovery protocol, which is itself an application of XDI messaging.

XDI Message Pattern Rules

Following is the standard template for an XDI message (shown in XDI display format). Labels in <--this-form--> represent template variables. Since an XDI message is itself an XDI graph, it consists of a set of XDI statements.

  1. An XDI message MUST conform to the statements in this template.
  2. All statements except the OPERATION statement are OPTIONAL for certain types of XDI messages (this is still under discussion by the TC).

See XdiSyntaxExamples for more about XDI syntax. Note: statements are named and numbered for reference only (XDI graphs are unordered by default).

#1:  FROM                  <--from-peer-->/$set/<--from-->[$msg]<--msg-id-->
#2:  TO                    <--from-->[$msg]<--msg-id-->/$is()/<--to-peer-->
#3:  MESSAGE TYPE          <--from-->[$msg]<--msg-id-->/$is#/<--message-type-->[$v]<--version-number-->$xdi[$v]@1$msg
#4:  TIMESTAMP             <--from-->[$msg]<--msg-id--><$t>&/&/<--timestamp-->
#5:  AUTHENTICATION TOKEN  <--from-->[$msg]<--msg-id--><--token-type--><$token>/&/<--token-->
#6:  AUTHENTICATION SIG    <--from-->[$msg]<--msg-id--><--signature-type--><$sig>/&/<--signature-->
#7:  AUTHORIZATION         <--from-->[$msg]<--msg-id-->/$do/<--link-contract-id-->
#8:  OPERATION             <--from-->[$msg]<--msg-id-->$do/<--operation-->/<--object-graph-->
#9:  CONDITION             <--from-->[$msg]<--msg-id-->$do$if<--boolean-context-->/<--operator-->/<--condition-->
#10: PARAMETERS            <--from-->[$msg]<--msg-id--><--operation--><--parameter-->/&/<--parameter-value-->


Message Envelope Rules

The entire XDI graph containing one or more XDI messages is called the XDI message envelope.

  1. A message envelope MAY contain more than one message subgraph.
  2. A message MAY contain more than one operation statement.
  3. An XDI endpoint MUST execute all messages in a message envelope.
  4. An XDI endpoint MUST execute all operation statements within a message.

Statement Ordering Rules

In the XDI graph model as a whole, XDI statements are unordered.

  1. Messages within a message envelope (i.e., within the <--from-->[$msg] collection) MAY be explicitly ordered by appending the @<--digit--> ordering context to the <--from-->[$msg]!<--id--> context.

  2. Operation statements within a message (i.e., as objects of the <--operation--> predicate) MAY be explicitly ordered by appending the @<--digit--> ordering context to the `<--operation--> predicate.

  3. Explicit ordering of messages and operations is OPTIONAL for an XDI client.
  4. Support for explicit ordering of messages and operations is REQUIRED for an XDI endpoint.
  5. If explicit ordering of messages and operations is not used, then an XDI endpoint MUST NOT make guarantees about the order in which messages in a message envelope are executed, or about the order in which operations in a message are executed.
  6. An XDI endpoint MUST guarantee that all operations in one message are executed before operations in another message are executed.

Sender Rules

If an XDI message is required to include a FROM statement, the following rules apply.

  1. <--from-peer--> MUST be the peer root address of the XDI endpoint originating the message. (Note that the <--from-peer--> for XDI client that does not function as an XDI endpoint may be an XDI cross-reference to its current network endpoint or some other client identifier acceptable to the receiving XDI endpoint.)

  2. <--from--> MUST be the XDI address representing the XDI authority (e.g., person, organization, device, service, etc.) originating the message.

Message ID Rules

  1. Like any XDI subgraph, the value of the <--id--> variable representing the message ID MUST be unique within the scope of the [$msg] collection of messages sent by the sender. The <--id--> value may be sequential, or based on timestamps, or a UUID, or use any other algorithm that provides uniqueness in this context.

  2. An XDI client MUST use a different message ID for every message.
  3. An XDI endpoint MAY enforce uniqueness of message IDs.

Recipient Rules

If an XDI message is required to include a TO statement, the following rules apply.

  1. <--to-peer--> MUST be the peer root address of the XDI endpoint to which the message is sent.

  2. This peer root address SHOULD be discoverable using XDI Discovery.

  3. An XDI message MAY include multiple TO statements in order to deliver the message to multiple recipients.

Timestamp Rules

If an XDI message is required to include a TIMESTAMP statement, the following rules apply.

  1. <--timestamp--> MUST be an XML datetime as specified by the $t entry in the XDI $ Dictionary.

  2. An XDI endpoint MAY enforce server-side policy requiring the message <timestamp> value to be within a certain tolerance of the server timestamp.

Authentication Rules

Token-Based Authentication

A message MAY be authenticated with a token as defined in section 1.4 of RFC 6749 - The OAuth 2.0 Authorization Framework.

Supported token types and token authentication requirements will defined in separate specifications. The token types currently planned to be supported by the XDI TC include:

  1. $secret for shared secrets. Any valid XDI literal value may be used as a shared secret.

  2. $bearer for bearer tokens as defined by RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage.

  3. Other token types as registered with the IANA OAuth Access Token Types Registry defined in section 11.1 of RFC 6749 - The OAuth 2.0 Authorization Framework.

Signature-Based Authentication

XDI messages MAY be signed for authentication. See the XdiSignature page.

Authorization Rules

  1. Each XDI message MUST include a <--link-contract--> reference to the XDI link contract authorizing that message. See the Link Contract Pattern. Requiring the <--link-contract--> reference in an XDI message makes it much more efficient for XDI servers to perform authentication and authorization, because they know which link contract to evaluate. (For a public link contract, the value of <--link-contract--> is $public$do.)

  2. The message MUST be executed only if the link contract policies evaluates to true.

Operation Execution Rules

Operations constitute the body of an XDI message.

  1. An XDI message MUST contain at least one operation statement.
  2. To successfully complete execution of an XDI message, an XDI endpoint MUST complete execution of each operation requested in each operation statement in the message.

Depending on: a) the operation, and b) whether the operation target is an XDI address or a statement, the following results are possible:

(click on an operation name for details)

on XDI address

on contextual statement

on literal statement

on relational statement

GetOperation ($get)

retrieves graph/subgraph

retrieves graph/subgraph

retrieves literal

retrieves relation

SetOperation ($set)

writes context node(s)

writes context node(s)

writes literal value

writes relation

DelOperation ($del)

deletes graph/subgraph

deletes graph/subgraph

deletes literal

deletes relation

Note: AddOperation and ModOperation are proposed to be deprecated.

Conditional Execution Rules

  1. An XDI message MAY also include condition statements to govern their execution at an XDI endpoint.
  2. If an XDI message includes a <--from-->[$msg]<--id-->$do$if sub context, the set of message policy statements in this context MUST be evaluated by the XDI endpoint.

  3. The message MUST only be executed if the message policy statement set evaluates to true.
  4. Message policy evaluation MUST follow the same rules as link contract policy evaluation.

  5. For privacy reasons, a message policy may only access parts of the target graph which it has $get access to under the link contract referenced in the message.

Parameter Rules

  1. An XDI message MAY include one or more parameters that govern how an XDI endpoint processes an XDI message.
  2. A parameter MUST apply only to the XDI message and the XDI message operation that contains it.

Currently, parameters are only defined for the XDI $get operation.

$get Parameters

  1. The $deref parameter is defined in XDI Equivalence Relations. It governs whether the XDI endpoint automatically dereferences $ref statements in a response graph.

  2. The $proxy parameter is defined in XDI Discovery. It governs whether the XDI endpoint serves as a proxy to complete discovery of an XDI resource for which the XDI endpoint is not itself authoritative.

Error Handling Rules

The template for an error message is:

#1: ERROR AND TIMESTAMP      $error<$t>/&/<--timestamp-->
#2: ERROR STATEMENTS         $error/$do/<--error-statement-->

<error-statement> is an inner graph of error statements pertaining to the message.

The dictionary for XDI error code statements is still being defined. See MessagingErrorCode.

Transactional Integrity

The XDI TC has discussed transactional integrity, including ACID and BASE, but has not yet determined the requirements that XDI messaging will need to support.

Index of Common Message Patterns

Following is an index of XDI TC wiki pages that document common XDI message exchange patterns as they are developed.

CategoryProposal CategoryMessaging CategoryCurrent

XdiMessagePatterns (last edited 2015-03-10 06:49:38 by drummond-xns)