- Change Log
- XDI Message Pattern Rules
- Message Envelope Rules
- Statement Ordering Rules
- Sender Rules
- Message ID Rules
- Recipient Rules
- Timestamp Rules
- Authentication Rules
- Authorization Rules
- Operation Execution Rules
- Conditional Execution Rules
- Parameter Rules
- Error Handling Rules
- Transactional Integrity
- Index of Common Message Patterns
- 2014-03-29 - Drummond Reed: updated for symbol shift
- 2013-10-18 - Drummond Reed: added XDI message type statement per minutes of last two TC telecons.
- 2013-04-18 - Drummond Reed: updated to reflect XDI syntax revisions.
- 2013-02-24 - Drummond Reed: reformatted to follow new proposal formatting conventions, added links to external specs, added parameters section.
- 2012-10-15 - Markus Sabadello: Some more wording, e.g. in the Ordering section
- 2012-09-27 - Markus Sabadello: Turned this page into a proposal, cleaned up multiplicity syntax, moved information related to specific operations to separate proposal pages, moved information related to signatures to separate proposal page.
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.
- An XDI message MUST conform to the statements in this template.
- 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-->
<--from-peer--> is the XDI address of the peer root node of the XDI graph originating the message. This is expressed as an XDI cross-reference (i.e., in parentheses).
<--from--> is the XDI address of the sender (the XDI authority originating the message) which may or may not be the same as the XDI address inside the <--from-peer--> cross-reference.
<--msg-id--> is an unordered entity instance that is the unique ID of the message in the context of this sender. See the Message ID Rules section below.
<--to-peer--> is the XDI address of the XDI peer root for the recipient. This is always expressed as an XDI cross-reference (i.e., in parentheses). It is the XDI address on which XdiDiscovery is performed to discover the XDI endpoint URI. For a message to multiple recipients, there will be one TO statement per recipient.
<--message-type--> is an optional XDI context defining the XDI message type.
<--version-number--> is the message type version, expressed as an ordered instance @x where x is a non-negative integer.
<--timestamp--> is the timestamp of the message in XML datetime format.
<--token-type--> is the context defining the type of token provided for message authentication.
<--token--> is the literal token value provided for authentication as required by the referenced link contract.
<--signature-type--> is the context defining the type of signature provided for authentication.
<--signature--> is the literal signature value provided for authentication as required by the referenced link contract.
<--link-contract-id--> is the XDI address of the root node of the link contract authorizing the requested operation on the requested object graph. This MUST be either: a) a $do entity singleton or: b) a [$do] entity class followed by an entity instance. See the Link Contract Pattern.
<--operation--> is the requested XDI operation ($get, $set, $del, $copy, $move), plus subcontexts (if any). There may be one or more operation statements in a message.
<--object-graph--> is the XDI address or statement that is the target of the operation.
<--boolean-context--> is defined in XdiPolicyExpression.
<--operator--> is defined in XdiPolicyExpression.
<--condition--> is defined in XdiPolicyExpression.
<--parameter--> is an XDI message protocol parameter. See the Parameter Rules section below.
<--parameter-value--> is the value of a message parameter. See the Parameter Rules section below.
Message Envelope Rules
The entire XDI graph containing one or more XDI messages is called the XDI message envelope.
- A message envelope MAY contain more than one message subgraph.
- A message MAY contain more than one operation statement.
- An XDI endpoint MUST execute all messages in a message envelope.
- 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.
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.
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.
- Explicit ordering of messages and operations is OPTIONAL for an XDI client.
- Support for explicit ordering of messages and operations is REQUIRED for an XDI endpoint.
- 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.
- An XDI endpoint MUST guarantee that all operations in one message are executed before operations in another message are executed.
If an XDI message is required to include a FROM statement, the following rules apply.
<--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.)
<--from--> MUST be the XDI address representing the XDI authority (e.g., person, organization, device, service, etc.) originating the message.
Message ID Rules
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.
- An XDI client MUST use a different message ID for every message.
- An XDI endpoint MAY enforce uniqueness of message IDs.
If an XDI message is required to include a TO statement, the following rules apply.
<--to-peer--> MUST be the peer root address of the XDI endpoint to which the message is sent.
This peer root address SHOULD be discoverable using XDI Discovery.
- An XDI message MAY include multiple TO statements in order to deliver the message to multiple recipients.
If an XDI message is required to include a TIMESTAMP statement, the following rules apply.
<--timestamp--> MUST be an XML datetime as specified by the $t entry in the XDI $ Dictionary.
An XDI endpoint MAY enforce server-side policy requiring the message <timestamp> value to be within a certain tolerance of the server timestamp.
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:
$secret for shared secrets. Any valid XDI literal value may be used as a shared secret.
$bearer for bearer tokens as defined by RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage.
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.
XDI messages MAY be signed for authentication. See the XdiSignature page.
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.)
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.
- An XDI message MUST contain at least one operation statement.
- 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
writes context node(s)
writes context node(s)
writes literal value
Conditional Execution Rules
- An XDI message MAY also include condition statements to govern their execution at an XDI endpoint.
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.
- The message MUST only be executed if the message policy statement set evaluates to true.
Message policy evaluation MUST follow the same rules as link contract policy evaluation.
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.
- An XDI message MAY include one or more parameters that govern how an XDI endpoint processes an XDI message.
- 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.
The $deref parameter is defined in XDI Equivalence Relations. It governs whether the XDI endpoint automatically dereferences $ref statements in a response graph.
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.
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.
XdiDiscovery - message patterns for discovering the concrete URIs for XDI endpoints.
XdiMsgPatternSelfGet - The pattern for an XDI authority to request their own attributes from their own graph (e.g., their own private key).