[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Chet and Paul: Next steps on your list of all edits needed to bring XDI Core 1.0 Working Draft 06 up to CSD01
Hi Drummond - you can look at progress at:
Notes interspersed below:in the Citation format, please use :<bold>[XDI-Core-v1.0]</> (lower case "v")<ital>XDI Core Version 1.0</>. (use whole word "Version", to match the official title) the rest looks fine....well, why not fiddle one more time: for the "Acknowledgements section", unless you have a preponderance of British or Canadian English speakers, please use "Acknowledgments" (drop the "e")- Change file names to 'xdi-core-v1.0-csd01'- Change 'Working Draft 06' to 'Committee Specification Draft 01'- Change date from '19 October 2015' to '29 October 2015'I put 04 December. Should it be 29 October?
- Change urls in This version from 'http://docs.oasis-open.org/xdi/spec-1.0/xdi-core-1.0-wd06' to 'http://docs.oasis-open.org/xdi/core/v1.0/csd01/xdi-core-v1.0-csd01'- Replace links under Previous version with 'N/A'The N/A comes out linked. Would you rather remove Previous section completely?
- Change urls in Latest version from 'http://docs.oasis-open.org/xdi/spec/xdi-core' to 'http://docs.oasis-open.org/xdi/core/v1.0/xdi-core-v1.0'- Under Technical Committee, change 'OASIS XDI TC' to 'OASIS XRI Data Interchange (XDI) TC'. Link it to 'https://www.oasis-open.org/committees/xdi/'- After Technical Commmittee, add a new section labelled 'Chairs:'. Use the same format as for the other headings. Below that, put:Drummond Reed (drummond@respectnetwork.net), Respect NetworkMarkus Sabadello (markus.sabadello@xdi.org), XDI.ORGThe names are not appearing yet - not sure if the Chairs template takes particular parameter names.
For each of these entries, make the email addresses mailto links and link the organization name to its main web site- Under editors, link the organization names to the main websites.- Under Additional artifacts, under the sentence that starts with 'This prose specification...' put a bulleted item* ABNF file: http://docs.oasis-open.org/xdi/core/v1.0/csd01/abnf/xdi-core-abnf-v1.0.txt (We recommend keeping wd#s off machine readable files.- Remove the empty 'Related work' heading.- Under 'Abstract' remove the first sentence starting with 'This working draft...'- Under Citation Format, under the sentence beginning with "When referencing this..." put (formatted as indicated by the <>s)<bold>[XDI-Core-V1.0]</><ital>XDI Core V1.0</>. Edited by Joseph Boyle, Drummond Reed, and Markus Sabadello. 29 October 2015. OASIS Committee Specification Draft 01. <a>http://docs.oasis-open.org/xdi/core/v1.0/csd01/xdi-core-v1.0-csd01.html</>. Latest version: <a>http://docs.oasis-open.org/xdi/core/v1.0/xdi-core-v1.0.html</>.
- Above the table of contents, put 'Table of Contents' in the same font and color as the section label 'Notices' above.It looks like this disappears only in the PDF. I don't understand. Adding text manually might result in doubling it in the XML and HTML results.
- On the PDF, remove the header. Change the footer to read:<left side>xdi-core-v1.0-csd01 <right side>29 October 2015<left side>Standards Track Work Product <center>Copyright © OASIS Open 2015. All Rights Reserved. <right side>Page 1 of ##Still to be done; I think this is a processing change, not the document itself.
- Under 1.5 Normative References, please change the references to documents that don't yet exist: XDI-Messageing, XDI-Binding, XDI-Discovery, XDI-Policy, and XDI-Privacy.I see why you want to include them - you refer to them elsewhere in the spec. To hold their places in section 1.5, I'd prefer to see them done this way:[OASIS-XDI-Messaging-V1.0] <ital>OASIS XDI 1.0 Messaging Specification</>. TC work in progress. Not yet published.I've assumed Paul's correction also means removing OASIS from these titles.
- At the end of the document, add an Acknowledgements section. This can be Appendix A, B, whatever - in that section you should list all the active members of the TC. If there were people who participated earlier but are not now members of the TC, feel free to include them as well.
- At the very end of the document, please add an appendix with the Revision History. This are typically tables with the revision, the date, and the changes made.
<?xml version="1.0" encoding="UTF-8"?>
<!--
For use when a committee document points at the OASIS web site for publishing:
<?xml-stylesheet type="text/xsl"
href="http://docs.oasis-open.org/templates/DocBook/spec-0.6/stylesheets/oasis-specification-html.xsl";?>
<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd";
For use when a committee document points to an embedded runtime installation:
<?xml-stylesheet type="text/xsl"
href="htmlruntime/spec-0.6/stylesheets/oasis-specification-html.xsl"?>
<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"htmlruntime/spec-0.6/docbook/docbookx.dtd"
For use when a committee document is published in a local environment only
(note the instructions for local publishing require adjusting the stylesheet
and DocBook directories in these declarations):
<?xml-stylesheet type="text/xsl"
href="file:///c:/oasis/spec-0.6/stylesheets/oasis-specification-html-offline.xsl"?>
<!DOCTYPE article
PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"file:///c:/oasis/spec-0.6/docbook/docbookx.dtd"
-->
<?xml-stylesheet type="text/xsl"
href="../../htmlruntime/spec-0.6/stylesheets/oasis-specification-html.xsl"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "../../htmlruntime/spec-0.6/docbook/docbookx.dtd"[
<!ENTITY title "XDI Core V&version;">
<!ENTITY name "xdi-core">
<!ENTITY pversion "0.1">
<!ENTITY version "1.0">
<!ENTITY pubdate "29 October 2015">
<!ENTITY stage "csd01">
<!ENTITY standard "Committee Specification Draft 01">
<!ENTITY this-loc "http://docs.oasis-open.org/xdi/core/v&version;/&stage;/&name;-v&version;-&stage;";>
<!ENTITY previous-loc "N/A">
<!ENTITY latest-loc "http://docs.oasis-open.org/xdi/core/v&version;/&name;-v&version;";>
]>
<!--DOCTYPE article PUBLIC "-//OASIS//DTD DocBook SVG Module V1.1CR1//EN" "http://www.oasis-open.org/docbook/xml/svg/1.1CR1/dbsvg.dtd"-->
<!--!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "https://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"?-->
<!--!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook SVG Module V1.1CR1//EN" "http://www.oasis-open.org/docbook/xml/svg/1.1CR1/dbsvg.dtd"?-->
<!--article status="&standard;" xmlns="http://docbook.org/ns/docbook"; version="5.0" xml:lang="en"-->
<article xmlns="http://docbook.org/ns/docbook"; xmlns:xlink="http://www.w3.org/1999/xlink";
version="4.4" xml:lang="en" status="&standard;">
<articleinfo>
<title>&title;</title>
<productname>&name;</productname>
<productnumber>&version;-&stage;</productnumber>
<releaseinfo role="track">Standards Track Work Product</releaseinfo>
<releaseinfo role="OASIS-specification-this-authoritative"
>&this-loc;/&name;-&version;-&stage;.xml</releaseinfo>
<releaseinfo role="OASIS-specification-this"
>&this-loc;/&name;-&version;-&stage;.pdf</releaseinfo>
<releaseinfo role="OASIS-specification-this"
>&this-loc;/&name;-&version;-&stage;.html</releaseinfo>
<releaseinfo role="OASIS-specification-previous"
>N/A</releaseinfo>
<releaseinfo role="OASIS-specification-latest-authoritative"
>&latest-loc;/&name;.xml</releaseinfo>
<releaseinfo role="OASIS-specification-latest">&latest-loc;/&name;.pdf</releaseinfo>
<releaseinfo role="OASIS-specification-latest">&latest-loc;/&name;.html</releaseinfo>
<releaseinfo role="committee"><ulink url="http://www.oasis-open.org/committees/xdi";>OASIS XRI Data Interchange (XDI) TC</ulink></releaseinfo>
<authorgroup>
<editor>
<firstname>Joseph</firstname>
<surname>Boyle</surname>
<affiliation>
<orgname><ulink url="http://xdi.org";>XDI.org</ulink></orgname>
</affiliation>
<email><ulink url="mailto:joseph@xdi.org";>joseph@xdi.org</ulink></email>
</editor>
<editor>
<firstname>Drummond</firstname>
<surname>Reed</surname>
<affiliation>
<orgname><ulink url="http://respect.network";>Respect Network</ulink></orgname>
</affiliation>
<email><ulink url="mailto:drummond@respect.network";>drummond@respect.network</ulink></email>
</editor>
<editor>
<firstname>Markus</firstname>
<surname>Sabadello</surname>
<affiliation>
<orgname><ulink url="http://xdi.org";>XDI.org</ulink></orgname>
</affiliation>
<email><ulink url="mailto:markus.sabadello@xdi.org";>markus.sabadello@xdi.org</ulink></email>
</editor>
</authorgroup>
<pubdate>&pubdate;</pubdate>
<copyright>
<year>2015</year>
<holder>OASIS Open, Inc. All Rights Reserved.</holder>
</copyright>
<legalnotice role="additional">
<title>Additional artifacts</title>
<para>This prose specification is one component of a Work Product which also
includes:</para>
<itemizedlist spacing="compact"> <listitem><para><para>
ABNF file: <ulink url="http://docs.oasis-open.org/xdi/core/v&version;/&stage;/abnf/&name;-abnf-v&version;-&stage;.txt";></ulink></para>
</para></listitem> </itemizedlist>
</legalnotice>
<abstract>
<title>Abstract</title>
<para>This is the core specification for XDI (Extensible
Data Interchange). It defines the XDI semantic graph model, ABNF, JSON
serialization, and addressing rules.</para>
</abstract>
<legalnotice role="citation">
<title>Citation format</title>
<para>When referencing this specification the following citation format should be
used:</para>
<bibliolist> <bibliomixed>
<abbrev>XDI-Core-v1.0</abbrev>
<title>XDI Core Version 1.0</title>
<date>&pubdate;. </date>
<releaseinfo>OASIS &standard;. </releaseinfo>
<citetitle><ulink url="&latest-loc;/&name;.html">&latest-loc;/&name;.html</ulink>.</citetitle>
</bibliomixed> </bibliolist>
</legalnotice>
<legalnotice role="notices">
<title>Notices</title>
<para>Copyright © OASIS® Open 2015. All Rights Reserved. </para>
<para>All capitalized terms in the following text have the meanings assigned to them in
the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full
Policy may be found at <ulink
url="http://www.oasis-open.org/who/intellectualproperty.php";
>http://www.oasis-open.org/who/intellectualproperty.php</ulink>.</para>
<para>This document and translations of it may be copied and furnished to others, and
derivative works that comment on or otherwise explain it or assist in its
implementation may be prepared, copied, published, and distributed, in whole or in
part, without restriction of any kind, provided that the above copyright notice and
this section are included on all such copies and derivative works. However, this
document itself may not be modified in any way, including by removing the copyright
notice or references to OASIS, except as needed for the purpose of developing any
document or deliverable produced by an OASIS Technical Committee (in which case the
rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be
followed) or as required to translate it into languages other than English.</para>
<para>The limited permissions granted above are perpetual and will not be revoked by
OASIS or its successors or assigns.</para>
<para>This document and the information contained herein is provided on an "AS IS" basis
and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP
RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR
PURPOSE.</para>
<para>OASIS requests that any OASIS Party or any other party that believes it has patent
claims that would necessarily be infringed by implementations of this OASIS
Committee Specification or OASIS Standard, to notify OASIS TC Administrator and
provide an indication of its willingness to grant patent licenses to such patent
claims in a manner consistent with the IPR Mode of the OASIS Technical Committee
that produced this specification.</para>
<para>OASIS invites any party to contact the OASIS TC Administrator if it is aware of a
claim of ownership of any patent claims that would necessarily be infringed by
implementations of this specification by a patent holder that is not willing to
provide a license to such patent claims in a manner consistent with the IPR Mode of
the OASIS Technical Committee that produced this specification. OASIS may include
such claims on its website, but disclaims any obligation to do so.</para>
<para>OASIS takes no position regarding the validity or scope of any intellectual
property or other rights that might be claimed to pertain to the implementation or
use of the technology described in this document or the extent to which any license
under such rights might or might not be available; neither does it represent that it
has made any effort to identify any such rights. Information on OASIS' procedures
with respect to rights in any document or deliverable produced by an OASIS Technical
Committee can be found on the OASIS website. Copies of claims of rights made
available for publication and any assurances of licenses to be made available, or
the result of an attempt made to obtain a general license or permission for the use
of such proprietary rights by implementers or users of this OASIS Committee
Specification or OASIS Standard, can be obtained from the OASIS TC Administrator.
OASIS makes no representation that any information or list of intellectual property
rights will at any time be complete, or that any claims in such list are, in fact,
Essential Claims.</para>
<para>The name "OASIS" is a trademark of <ulink url="http://www.oasis-open.org";
>OASIS</ulink>, the owner and developer of this specification, and should be
used only to refer to the organization and its official outputs. OASIS welcomes
reference to, and implementation and use of, specifications, while reserving the
right to enforce its marks against misleading uses. Please see <ulink
url="http://www.oasis-open.org/who/trademark.php";
>http://www.oasis-open.org/who/trademark.php</ulink> for above guidance.</para>
</legalnotice>
</articleinfo>
<para><quote>I would not give a fig for the simplicity this side of complexity, but I would give
my life for the simplicity on the other side of complexity.</quote> —Oliver Wendell
Holmes, Jr.</para>
<para><quote>Everything should be made as simple as possible, but no simpler.</quote> —Albert
Einstein</para>
<para><quote>It's turtles all the way down!</quote> —Dr. Seuss</para>
<section id="introduction">
<title>Introduction</title>
<para>This is the core specification for XDI (Extensible Data Interchange). It defines the
XDI semantic graph model, ABNF, JSON serialization, and addressing rules.</para>
<section>
<title>How XDI Builds On RDF</title>
<para>RDF (Resource Description Framework) <xref linkend="rdf-concepts"/> is the W3C
standard for the foundation of the Semantic Web. It defines a core semantic graph
model based on subject-predicate-object triples for describing data. The W3C has
also defined JSON-LD <xref linkend="json-ld"/> and the W3C Linked Data Platform 1.0
<xref linkend="ldplatform"/> as W3C Recommendations. </para>
<para>XDI builds on the RDF graph model, adding several key features and constraints in
order to optimize it for semantic data interchange. The most important of these
are:</para>
<orderedlist>
<listitem>
<para><emphasis role="bold">Context. </emphasis>XDI makes context another
dimension of the graph model—to the point where contextual statements are
the third fundamental type of XDI statement along with literal and
relational statements.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Addressability. </emphasis>The XDI graph model does
not allow RDF blank nodes. It also imposes the constraint that the XDI
identifier of every XDI contextual arc must be unique it the scope of its
parent node. The result is that every node of every XDI graph has a unique
global address—and the address itself is a semantic description of that
node.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Simplified reification. </emphasis>The XDI graph
model has a standard mechanism for reification of any XDI statement, and
reified statements are also uniquely addressable.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Immutability. </emphasis>Persistent identity is so
important in distributed data sharing that XDI addressing includes special
syntax for immutable identifiers of XDI graph nodes.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Relativity. </emphasis>Identifier scope is also
critical to interoperable semantics, so XDI addressing supports explicit
syntax for both absolute and relative identifiers of XDI graph nodes.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Authority. </emphasis>Establishing a clear chain of
authority and accountability for shared data is also a key requirement of
semantic data interchange. XDI contexts and classes enable directly modeling
of real-world legal relationships and responsibilities.</para>
</listitem>
</orderedlist>
<para>The result is an addressable semantic tree model that brings together the benefits
of Semantic Web technology with the benefits of well-established directory tree
technologies, as shown in the following diagram.</para>
<svg width="500" height="300" viewBox="0 0 500 150" version="1.1"
xmlns="http://www.w3.org/2000/svg";>
<ellipse cx="250" cy="70" rx="248" ry="140" stroke="black" stroke-width="2" fill="white"/>
<g transform="translate(130,0)">
<circle cx="0" cy="70" r="105" stroke="black" fill="white"/>
<text x="0" y="0" text-anchor="middle">Semantic Web:</text>
<text x="0" y="40" text-anchor="middle">Description Logic</text>
<text x="0" y="60" text-anchor="middle">Knowledge Representation</text>
<text x="0" y="80" text-anchor="middle">Machine Learning</text>
<text x="0" y="120" text-anchor="middle">RDF, OWL, JSON-LD</text>
</g>
<g transform="translate(360,0)">
<circle cx="0" cy="70" r="105" stroke="black" fill="white"/>
<text x="0" y="0" text-anchor="middle">Directory Tree:</text>
<text x="0" y="40" text-anchor="middle">Identity Management</text>
<text x="0" y="60" text-anchor="middle">Discovery, Access Control</text>
<text x="0" y="80" text-anchor="middle">Authentication, Authorization</text>
<text x="0" y="120" text-anchor="middle">X.500, LDAP, DNS</text>
<text x="0" y="140" text-anchor="middle">XACML, OAuth</text>
</g>
<text x="250" y="-40" text-anchor="middle">Semantic Tree:</text>
<text x="250" y="180" text-anchor="middle">XDI</text>
</svg>
<para>Additional comparisons with specific features of the RDF family of specifications
will be covered throughout this specification.</para>
</section>
<section>
<title>Example XDI Graphs</title>
<para>This is an example XDI graph shown in XDI JSON serialization format. It is a
relatively simple graph showing some typical profile data for a person (Alice).
Alice’s graph also includes a reference to the peer graph for another person (Bob). </para>
<note>
<para>In the examples used in this specification: a) mutable XDI identifiers (XDI
names) will often use the "x-" prefix reserved for examples, and 2) immutable
XDI identifiers that use XDI UUID scheme will often use truncated placeholders
in the form of ":uuid:x-" for readability.</para>
</note>
<programlisting>{
"<$iri>": {
"&": "https://xdi.example.com/=!:uuid:x-alice/";
},
"=!:uuid:x-alice": {
"/#friend": [
"=!:uuid:x-bob"
],
"<#home><#email>": {
"&": "alice@example.com"
},
"<#work><#email>": {
"&": "asmith@example.net"
},
"<#personal><#email>": {
"/$ref": [
"=!:uuid:x-alice<#home><#email>"
]
}
},
"=!:uuid:x-alice#passport": {
"<#country>": {
"&": "Canada"
},
"<#name>": {
"&": "Alice Smith"
},
"<#num>": {
"&": "1234567"
}
},
"(=!:uuid:x-bob)": {
"<$iri>": {
"&": "https://xdi.example.com/=!:uuid:x-bob/";
}
}
}</programlisting>
<para>This second example adds some additional XDI statements. It also adds a simple
<glossterm>XDI link contract</glossterm>—a data sharing agreement expressed in
XDI—between Alice and Bob.</para>
<programlisting>{
"/$is$ref": [
"(=x-alice)",
"(=!:uuid:x-alice)"
],
"<$iri>": {
"&": "https://xdi.example.com/=!:uuid:x-alice/";
},
"=!:uuid:x-alice": {
"/#friend": [
"=!:uuid:x-bob",
"(=!:uuid:x-alice/#friend)"
],
"/#spouse": [
"=!:uuid:x-david"
],
"[<#email>]<!0>": {
"&": "alice@example.com"
},
"[<#email>]<!1>": {
"&": "asmith@example.net"
},
"<#email>": {
"/$ref": [
"=!:uuid:x-alice[<#email>]<!0>"
]
},
"<#home><#email>": {
"/$ref": [
"=!:uuid:x-alice[<#email>]<!1>"
]
},
"<#work><#email>": {
"/$ref": [
"=!:uuid:x-alice[<#email>]<!1>"
]
}
},
"=!:uuid:x-alice#passport": {
"<#country>": {
"&": "Canada"
},
"<#name>": {
"&": "Alice Smith"
},
"<#number>": {
"&": "1234567"
}
},
"(=!:uuid:x-alice)": {
"/$ref": [
""
]
},
"(=!:uuid:x-alice/#friend)": {
"+!:uuid:x-org#card$do": {
"/$get": [
"=!:uuid:x-alice<#home><#email>"
]
}
},
"(=!:uuid:x-alice/#friend)(+!:uuid:x-org#card$do$if/$true)": {
"{$from}": {
"/$is#friend": [
"=!:uuid:x-alice"
]
}
},
"(=!:uuid:x-bob)": {
"<$iri>": {
"&": "https://xdi.example.com/=!:uuid:x-bob/";
}
}
}</programlisting>
</section>
<section>
<title>The XDI 1.0 Specifications</title>
<para>XDI Core is the first of a series of specifications that will define XDI 1.0. The
following table lists the other planned specifications.</para>
<para>
<table frame="all">
<title>Specifications in the XDI 1.0 Suite</title>
<tgroup cols="2" align="center">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="2.4*"/>
<thead>
<row>
<entry>Specification</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>XDI Messaging 1.0</entry>
<entry>Defines the XDI protocol as an abstract pattern for
performing XDI operations using XDI messages</entry>
</row>
<row>
<entry>XDI Bindings 1.0</entry>
<entry>Defines the concrete binding of XDI messaging to specific
transport protocols, beginning with the HTTP(S) protocol</entry>
</row>
<row>
<entry>XDI Connections 1.0</entry>
<entry>Defines the specific XDI protocol for instantiating XDI link
contracts</entry>
</row>
<row>
<entry>XDI Policy 1.0</entry>
<entry>Defines the standard structure and vocabulary of XDI
authorization statements, including XDI link contracts and
policy expressions, so they are portable across all XDI
endpoints</entry>
</row>
<row>
<entry>XDI Discovery 1.0</entry>
<entry>Defines peer-to-peer discovery of XDI endpoint IRI(s) given
an XDI address (or a discoverable identifier that can be
transformed into an XDI address)</entry>
</row>
<row>
<entry>XDI Push 1.0</entry>
<entry>Defines the semantics of XDI link contracts that establish
push relationships between two or more XDI endpoints using the
XDI <code>$push</code> operation</entry>
</row>
<row>
<entry>XDI Dictionary 1.0</entry>
<entry>Defines the semantic rules for XDI dictionary definitions,
including a type dictionary </entry>
</row>
<row>
<entry>XDI Versioning 1.0</entry>
<entry>Defines the semantics for standardized versioning of any XDI
graph or subgraph using the <code>$v</code> versioning
context</entry>
</row>
<row>
<entry>XDI Cryptographic Mechanisms 1.0</entry>
<entry>Defines the standards for digitally signing and encrypting
XDI messages and graphs</entry>
</row>
<row>
<entry>XDI Security Mechanisms 1.0</entry>
<entry>Describes the mechanisms for implementing security in XDI,
including transport-level security, message-level security,
encryption, token formats, etc.</entry>
</row>
<row>
<entry>XDI Privacy Mechanisms 1.0</entry>
<entry>Describes the mechanisms for implementing privacy in XDI,
including privacy-respecting identifiers (e.g., pseudonyms),
privacy-respecting link contracts, data usage controls,
etc.</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
<section>
<title> Key Words</title>
<para>The key words <glossterm>MUST</glossterm>, <glossterm>MUST NOT</glossterm>,
<glossterm>REQUIRED</glossterm>, <glossterm>SHALL</glossterm>, <glossterm>SHALL
NOT</glossterm>, <glossterm>SHOULD</glossterm>, <glossterm>SHOULD
NOT</glossterm>, <glossterm>RECOMMENDED</glossterm>, <glossterm>MAY</glossterm>,
and <glossterm>OPTIONAL</glossterm> are to be interpreted as described in <xref
linkend="rfc2119"/>.</para>
</section>
<section>
<title>Normative References</title>
<bibliolist>
<bibliomixed id="xdi-messaging-1.0">
<abbrev>XDI-Messaging-V1.0</abbrev>
<!--date>&pubdate; </date-->
<title>XDI 1.0 Messaging Specification</title>.TC work in progress. Not yet published.
<!--releaseinfo>OASIS &standard;. </releaseinfo-->
<!--citetitle><ulink url="&latest-loc;/xdi-messaging.html">&latest-loc;/xdi-messaging.html</ulink>.</citetitle-->
</bibliomixed>
<bibliomixed id="xdi-bindings-1.0">
<abbrev>XDI-Binding-V1.0</abbrev>
<title>XDI 1.0 Bindings Specification</title>. TC work in progress. Not yet published.
</bibliomixed>
<bibliomixed id="xdi-discovery-1.0">
<abbrev>XDI-Discovery-V1.0</abbrev>
<title>XDI 1.0 Discovery Specification</title>. TC work in progress. Not yet published.
</bibliomixed>
<bibliomixed id="xdi-dictionary-1.0">
<abbrev>XDI-Dictionary-V1.0</abbrev>
<title>XDI 1.0 Dictionary Specification</title>. TC work in progress. Not yet published.
</bibliomixed>
<bibliomixed id="xdi-policy-1.0">
<abbrev>XDI-Policy-V1.0</abbrev>
<title>XDI 1.0 Policy Specification</title>. TC work in progress. Not yet published.
</bibliomixed>
<bibliomixed id="xdi-security-1.0">
<abbrev>XDI-Security-V1.0</abbrev>
<title> XDI 1.0 Security Mechanisms Specification</title>. TC work in progress. Not yet published.
</bibliomixed>
<bibliomixed id="xdi-privacy-1.0">
<abbrev>XDI-Privacy-V1.0</abbrev>
<title>XDI 1.0 Privacy Mechanisms Specification</title>. TC work in progress. Not yet published.
</bibliomixed>
<bibliomixed id="rdf-concepts">
<abbrev>rdf-concepts</abbrev><date>25 February 2014</date>
<title><ulink url="http://www.w3.org/TR/rdf11-concepts";>RDF 1.1 Concepts and
Abstract Syntax</ulink></title>
<author>
<firstname>Richard </firstname>
<surname>Cyganiak</surname>
</author>, <author>
<firstname>David </firstname>
<surname>Wood</surname>
</author>, <author>
<firstname>Markus </firstname>
<surname>Lanthaler</surname>
</author>. <releaseinfo>W3C Recommendation 25 February 2014 </releaseinfo>
</bibliomixed>
<bibliomixed id="rdf-datasets">
<abbrev>rdf-datasets</abbrev><date>25 February 2014</date>
<title><ulink url="http://www.w3.org/TR/rdf11-datasets";>RDF 1.1: On Semantics of
RDF Datasets</ulink></title>
<author>
<firstname>Antoine </firstname>
<surname>Zimmerman</surname>
</author>. <releaseinfo>W3C Working Group Note 25 February 2014 </releaseinfo>
</bibliomixed>
<bibliomixed id="rdf-schema">
<abbrev>rdf-schema</abbrev><date>25 February 2014</date>
<title><ulink url="http://www.w3.org/TR/rdf-schema";>RDF 1.1
Schema</ulink></title>
<author>
<firstname>Dan </firstname>
<surname>Brickley</surname>
</author>, <author>
<firstname>R.V. </firstname>
<surname>Guha</surname>
</author>. <releaseinfo>W3C Recommendation 25 February 2014 </releaseinfo>
</bibliomixed>
<bibliomixed id="owl">
<abbrev>owl</abbrev><date>11 December 2012</date>
<title><ulink url="http://www.w3.org/TR/owl2-overview/";>OWL 2 Web Ontology
Language Document Overview</ulink></title>
<releaseinfo>W3C Recommendation 11 December 2012 </releaseinfo>
</bibliomixed>
<bibliomixed id="rfc2119">
<abbrev>RFC 2119</abbrev><date>March 1997</date>
<title><ulink url="http://www.ietf.org/rfc/rfc2119.txt";>Key words for use in
RFCs to Indicate Requirement Levels</ulink></title>
<author>
<firstname>S. </firstname>
<surname>Bradner</surname>
</author>. <releaseinfo>IETF (Internet Engineering Task Force)</releaseinfo>
</bibliomixed>
<bibliomixed id="rfc2234">
<abbrev>RFC 2234</abbrev><date>November 1997</date>
<title><ulink url="http://www.ietf.org/rfc/rfc2234.txt";>Augmented BNF for Syntax
Specifications: ABNF</ulink></title>
<author>
<firstname>D. </firstname>
<surname>Crocker</surname>
</author>, <author>
<firstname>P. </firstname>
<surname>Overell</surname>
</author>. <releaseinfo>IETF (Internet Engineering Task Force)</releaseinfo>
</bibliomixed>
<bibliomixed id="rfc3987">
<abbrev>RFC 3987</abbrev><date>January 2005</date>
<title><ulink url="http://www.ietf.org/rfc/rfc3987.txt";>IRI</ulink></title>
<author>
<firstname>M. </firstname>
<surname>Duerst</surname>
</author>. <author>
<firstname>M. </firstname>
<surname>Suignard</surname>
</author>. <releaseinfo>IETF (Internet Engineering Task Force)</releaseinfo>
</bibliomixed>
<bibliomixed id="rfc4627">
<abbrev>RFC 4627</abbrev><date>July 2006</date>
<title><ulink url="http://www.ietf.org/rfc/rfc4627.txt";>The application/json
Media Type for JavaScript Object Notation (JSON)</ulink></title>
<author>
<firstname>D. </firstname>
<surname>Crockford</surname>
</author>. <releaseinfo>IETF (Internet Engineering Task Force)</releaseinfo>
</bibliomixed>
<bibliomixed id="rfc4122">
<abbrev>RFC 4122</abbrev><date>July 2005</date>
<title><ulink url="http://www.ietf.org/rfc/rfc4122.txt";>A Universally Unique
IDentifier (UUID) URN Namespace</ulink></title>
<author>
<firstname>D. </firstname>
<surname>Crockford</surname>
</author>. <releaseinfo>IETF (Internet Engineering Task Force)</releaseinfo>
</bibliomixed>
<!--bibliomixed id="rfc5952">
<abbrev>RFC 5952</abbrev><date>August 2010</date>
<title><ulink url="http://www.ietf.org/rfc/rfc5952.txt";>A Recommendation for
IPv6 Address Text Representation</ulink></title>
<author>
<firstname>S. </firstname>
<surname>Kawamura</surname>
</author>, <author>
<firstname>M. </firstname>
<surname>Kawashima</surname>
</author>. <releaseinfo>IETF (Internet Engineering Task Force)</releaseinfo>
</bibliomixed-->
<bibliomixed id="rfc7159">
<abbrev>RFC 7159</abbrev><date>March 2014</date>
<title><ulink url="http://rfc7159.net/rfc7159";>The JavaScript Object Notation
(JSON) Data Interchange Format</ulink></title>
<author>
<firstname>T. </firstname>
<surname>Bray</surname>
</author>. <releaseinfo>IETF (Internet Engineering Task Force)</releaseinfo>
</bibliomixed>
<bibliomixed id="ecma-404">
<abbrev>ECMA-404</abbrev><date>October 2013</date>
<title><ulink
url="http://www.ecma-international.org/publications/files/ECMA-ST/ECMA-404.pdf";
>The JSON Data Interchange Format</ulink></title>
<author>
<firstname>S. </firstname>
<surname>Kawamura</surname>
</author>, <author>
<firstname>M. </firstname>
<surname>Kawashima</surname>
</author>. <releaseinfo>IETF (Internet Engineering Task Force)</releaseinfo>
</bibliomixed>
<bibliomixed id="unicode-tr15">
<abbrev>UAX15</abbrev><date>June 2015</date>
<title><ulink url="http://unicode.org/reports/tr31/";>Unicode Normalization
Forms</ulink></title>
<author>
<firstname>Mark </firstname>
<surname>Davis</surname>
</author>, <author>
<firstname>Ken </firstname>
<surname>Whistler</surname>
</author>. <releaseinfo>Unicode Consortium</releaseinfo>
</bibliomixed>
<bibliomixed id="unicode-tr31">
<abbrev>UAX31</abbrev><date>June 2015</date>
<title><ulink url="http://unicode.org/reports/tr31/";>Unicode Identifier and
Pattern Syntax</ulink></title>
<author>
<firstname>Mark </firstname>
<surname>Davis</surname>
</author>. <releaseinfo>Unicode Consortium</releaseinfo>
</bibliomixed>
<!--bibliomixed id="fips180-4">
<abbrev>FIPS 180-4</abbrev><date>March 2012</date>
<title><ulink
url="http://csrc.nist.gov/publications/fips/fips180-4/fips-180-4.pdf";
>Secure Hash Standard (SHS)</ulink></title>
<author>
<firstname/>
<surname/>
</author>
<releaseinfo>Federal Information Processing Standards Publication (FIPS),
NIST</releaseinfo>
</bibliomixed-->
</bibliolist>
</section>
<section>
<title>Non-Normative References</title>
<bibliolist>
<bibliomixed id="erm">
<abbrev>erm</abbrev><date>1976</date>
<title><ulink url="https://en.wikiversity.org/wiki/1976/Chen";>The
Entity-Relationship Model: Toward a Unified View of Data</ulink></title>
<author>
<firstname>Peter </firstname>
<surname>Chen</surname>
</author>. <releaseinfo>ACM Transactions on Database Systems 1(1): 9–36.
doi:10.1145/320434.320440</releaseinfo>
</bibliomixed>
<bibliomixed id="uml">
<abbrev>uml</abbrev><date>1 March 2015</date>
<title><ulink url="http://www.omg.org/spec/UML/2.5/";>UML 2.5
Specifications</ulink></title>
</bibliomixed>
<bibliomixed id="webarch">
<abbrev>webarch</abbrev><date>15 December 2004</date>
<title><ulink url="http://www.w3.org/TR/webarch/#id-resources";>Architecture of
the World Wide Web, Volume One</ulink></title>
<author>
<firstname>Ian </firstname>
<surname>Jacobs</surname>
</author>, <author>
<firstname>Norman </firstname>
<surname>Walsh</surname>
</author>. <releaseinfo>W3C Recommendation</releaseinfo>
</bibliomixed>
<bibliomixed id="httprange14">
<abbrev>httprange14</abbrev>
<title><ulink url="http://en.wikipedia.org/wiki/HTTPRange-14";
>HTTPRange-14</ulink></title>
<releaseinfo>Wikipedia</releaseinfo>
</bibliomixed>
<bibliomixed id="reification">
<abbrev>reification</abbrev>
<title><ulink url="http://en.wikipedia.org/wiki/Reification_(computer_science)"
>Reification (computer science)</ulink></title>
<releaseinfo>Wikipedia</releaseinfo>
</bibliomixed>
<bibliomixed id="zooko">
<abbrev>zooko</abbrev>
<title><ulink url="http://en.wikipedia.org/wiki/Zooko's_triangle">Zooko's
triangle</ulink></title>
<releaseinfo>Wikipedia</releaseinfo>
</bibliomixed>
<bibliomixed id="sovereign-identity">
<abbrev>sovereign-identity</abbrev>
<title><ulink
url="http://blogs.law.harvard.edu/doc/2013/10/14/iiw-challenge-1-sovereign-identity-in-the-great-silo-forest/";
>Sovereign Identity in the Great Silo Forest</ulink></title>
<releaseinfo>Doc Searls Weblog</releaseinfo>
</bibliomixed>
<bibliomixed id="pbd">
<abbrev>pbd</abbrev>
<title><ulink url="https://www.privacybydesign.ca";>Privacy by
Design</ulink></title>
<releaseinfo>Privacy by Design</releaseinfo>
</bibliomixed>
<bibliomixed id="json-ld">
<abbrev>json-ld</abbrev><date>16 January 2014</date>
<title><ulink url="http://www.w3.org/TR/json-ld/";>JSON-LD 1.0: A JSON-based
Serialization for Linked Data</ulink></title>
<author>
<firstname>Manu </firstname>
<surname>Sporny</surname>
</author>, <author>
<firstname>Dave </firstname>
<surname>Longley</surname>
</author>, <author>
<firstname>Gregg </firstname>
<surname>Kellogg</surname>
</author>, <author>
<firstname>Markus </firstname>
<surname>Lanthaler</surname>
</author>, <author>
<firstname>Niklas </firstname>
<surname>Lindström</surname>
</author>. <releaseinfo>W3C Recommendation 16 January 2014</releaseinfo>
</bibliomixed>
<bibliomixed id="ldplatform">
<abbrev>ldplatform</abbrev><date>26 February 2015</date>
<title><ulink url="http://www.w3.org/TR/ldp/";>Linked Data Platform 1.0</ulink></title>
<author>
<firstname>Steve </firstname>
<surname>Speicher</surname>
</author>, <author>
<firstname>John </firstname>
<surname>Arwe</surname>
</author>, <author>
<firstname>Ashok </firstname>
<surname>Malhotra</surname>
</author>. <releaseinfo>W3C Recommendation 26 February 2015</releaseinfo>
</bibliomixed>
<bibliomixed id="jsonpath">
<abbrev>jsonpath</abbrev>
<title><ulink url="http://goessner.net/articles/JsonPath/";>JSON
Path</ulink></title>
</bibliomixed>
</bibliolist>
<para/>
</section>
</section>
<section>
<title>Design Goals</title>
<para>This section communicates the design goals that have guided the development of
XDI.</para>
<section id="addressability">
<title>100% Addressability of All Graph Nodes</title>
<para>To perform semantic data interchange with precise control over every data element,
the first requirement of the XDI TC was that every node of every XDI graph be
uniquely addressable. This architecture essentially mirrors that of the W3C in the
Architecture of the World Wide Web, where it states: <quote>"To benefit from and
increase the value of the World Wide Web, agents should provide URIs as
identifiers for resources."</quote></para>
<para>This requirement is one reason the XDI TC does not use the term “XDI document” or
compare XDI graphs to documents. A document metaphor suggests a natural division
between addressing of the document and addressing of nodes inside the document. In
Web URI architecture, this is reflected by the # fragment, which represents an
address local to the current resource, vs. an address outside this resource.</para>
<para>The XDI graph model does not have this distinction because every node of every XDI
graph is equally addressable. (Or, as members of the XDI TC have put it, “It’s
turtles all the way down.”)</para>
<para>Note that XDI addressing stops once you reach an XDI literal node—the ultimate
leaf nodes of an XDI graph which contain the literal data values. If a client needs
to address within a literal data value, it must switch from an XDI address to an
address in the native addressing syntax of the literal data (e.g., a JSON path for a
JSON document, an XML path for an XML document, a fragment for an HTML document,
etc.) Such addresses are out of scope for XDI.</para>
<para>This requirement is perhaps the most significant difference between XDI and RDF,
because unique addressability of RDF graph nodes was not part of the RDF problem
domain. This is explained in more detailed in the paper <glossterm>How XDI Builds on
RDF</glossterm> cited in the Introduction.</para>
</section>
<section id="heterarchical">
<title>Heterarchical — No Central Authority</title>
<para>A second core design goal of XDI architecture is to support heterarchy, i.e., to
not assume or rely on a central authority. This requires designing a peer-to-peer
model in which any group of peers may cooperate to create an addressing and
interchange space for its community. This addressing space may make use of existing
resolvable identifiers for those peers, or it may extend those existing addresses,
or it may be an entirely new addressing space. In all cases XDI can standardize
discovery of peers and peer addresses, including both public and private discovery.
This “radically P2P” architecture supports any deployment topology, from highly
centralized to highly decentralized, and imposes the fewest pre-existing policy
assumptions or restrictions on communities of XDI users.</para>
<para>Note: for more about this aspect of XDI, see the XDI Discovery specification.
<xref linkend="xdi-discovery-1.0"/></para>
</section>
<section>
<title id="contextual">Contextual Identification</title>
<para>It is a mantra in digital identity that “identity is contextual”, i.e., that both
the requirements for identification and the uniqueness of identifiers is relative to
the context in which identification is required. Even “global” or “absolute”
identifiers like telephone numbers, email addresses, or URIs are still relative to a
particular addressing context.</para>
<para>It is also a maxim in the privacy community that “privacy is contextual”, and thus
a data authority must be able to control the data being shared and permissions being
granted in any identification context.</para>
<para>This primacy of context means that a third core XDI design goal is that it support
the ability to model context at any degree of granularity and to enable XDI
authorities to control the sharing of identity and data by context.</para>
<para>Again, we note that modeling of context was not a requirement of the RDF problem
domain, so this has not been an aspect of digital identity or data sharing addressed
by the RDF graph model. This topic is discussed in greater depth in the
<glossterm>How XDI Builds on RDF paper</glossterm>.</para>
</section>
<section id="persistent">
<title>Persistent Identification</title>
<para>A second core quality of identification is whether it is persistent (immutable) or
reassignable (mutable). In the former case, an identifier (or other means of
identification) is bound to the resource being identified in such a way that this
association will not change over time—ideally forever. In the latter case, an
identifier bound to one resource at one point in time (such as an IP address
assigned to one computer, or a domain name registered to one owner) may subsequently
be bound to a different resource at another point in time (such as when an IP
address is reassigned to a new computer, or when a domain name is transferred to a
new owner).</para>
<para>In the context of digital identity and secure data sharing, persistent
identification is a requirement for one core reason: if an XDI authority with a
particular identifier has been granted a specific set of permissions, and the XDI
authority identified by that identifier changes, then those permissions now belong
to (and can be exercised by) a different authority.</para>
<para>Persistent identification is also important for identity and data portability (see
below), because if an identifier (or other means of identification) needs to change
when the location of an XDI graph changes, the XDI relationships described in that
XDI graph will break. For these reasons, it is critical that XDI syntactically
distinguish a class of identifiers that XDI authorities can agree will be assigned
once to a resource and never be reassigned to another resource.</para>
<para>At the same time, it is widely acknowledged that persistent identification is a
usability nightmare. The human brain is wired to use simple, memorable natural
language identifiers for our cognition and communication, and we subconsciously
adjust the mappings of those identifiers over time as we learn, grow, and evolve.
For example, the person you first think of by the name “Mary” today may be different
from the person you first thought of by that name when you were a child.</para>
<para>So a key design goal of XDI is to support the requirements of both persistent and
reassignable forms of identification; to provide precise means to map between them;
and to make it syntactically unambiguous which form is being used in which
context.</para>
</section>
<section id="serialization">
<title>Serialization Independence</title>
<para>Another goal is for the XDI graph model to be a precise logical abstract model
that is independent of any specified serialization format. For example, the XDI 1.0
specifications specify two display formats and one JSON serialization format. In
addition the XDI TC plans to specify at least one XML serialization format. All
these formats transmit 100% of the information in an XDI graph, and all must be
losslessly convertible into the others.</para>
</section>
<section id="portability">
<title>Portability and Location Independence</title>
<para>Since XDI graphs may be used to describe any data associated with any entity,
including people and businesses that are constantly changing contexts, attributes,
service providers, and endpoints on the network, another design goal is for the
semantics expressed in an XDI graph to be portable, i.e., location-independent. This
means an XDI graph may be moved to any location (endpoint) on a network without
breaking any of the descriptions or relations described in the graph.</para>
<para>This design goal is particularly important for XDI graphs representing
individuals, as it supports the ability for an individual to maintain ongoing,
sustainable control of his/her personal digital identity, data and relationships,
independent of any particular service provider or network location.</para>
<para>Note: the specialized use of the XDI protocol to provide wide-area location
independence is defined in the XDI Discovery specification. <xref
linkend="xdi-discovery-1.0"/></para>
</section>
<section id="expression">
<title>Protocol Expression and Transport Independence</title>
<para>To make semantic data interchange as simple and extensible as possible, another
design goal is to define the XDI semantic data interchange protocol in XDI itself.
This means all XDI messages are valid XDI graphs, and all XDI data sharing
operations are valid XDI graph merge operations.</para>
<para>This design goal also achieves transport independence, i.e., as a logical protocol
for the exchange of data between any two systems, the XDI protocol can be
independent of any specific transport protocol (e.g., TCP/IP, HTTP(S), XMPP, SMTP,
etc.), with bindings defined to such transport protocols as needed.</para>
<para>Note: The logical XDI protocol is defined in the XDI Messaging specification <xref
linkend="xdi-messaging-1.0"/> and bindings to specific transport protocols are
defined in the XDI Bindings specification. <xref linkend="xdi-bindings-1.0"/></para>
</section>
<section id="authorization">
<title>Authorization and Policy Expression</title>
<para>To meet the security and privacy requirements of XDI authorities, the XDI protocol
must enable them to precisely describe the rights pertaining to any shared data.
Furthermore, in order for these rights to be enforced uniformly by the all XDI
authorities to which they are granted, and also to be portable if an XDI graph is
moved to a different location or service provider, XDI authorization must be able to
be fully described in XDI itself. This includes the ability to express any policy
governing authorization as well as the ability for such policies to reference data,
variables, relations, and other statements in the relevant XDI graphs.</para>
<para>Note: the primary XDI data structure that fulfills this design goal is called a
link contract and is defined in the XDI Policy specification. <xref
linkend="xdi-policy-1.0"/></para>
</section>
<section id="schema">
<title>Schema and Ontology Expression</title>
<para>A key difference between markup languages and semantic data interchange is that
the latter is expressly intended to solve the problem of interoperable data
semantics, i.e., to provide the infrastructure necessary to map semantics between
widely disparate systems with the precision necessary for digital data to
automatically flow between them. To do that, it is a design goal of XDI to enable
definition of schemas and ontologies for XDI data in XDI.</para>
<para>Note: XDI schema and ontology definition is defined in the XDI Dictionary
specification. <xref linkend="xdi-dictionary-1.0"/></para>
</section>
<section id="extensibility">
<title>Extensibility</title>
<para>A final design goal (and the reason for the “X” in “XDI”) is for any XDI authority
to be able to extend XDI semantics without permission from any other XDI authority.
This includes the ability to establish new XDI addressing spaces, to define new XDI
dictionary vocabulary, and to create specializations of the XDI protocol for
specific types of semantic data interchange.</para>
</section>
</section>
<section>
<title>The XDI Graph Model</title>
<para>To meet the design goals in the preceding section, the XDI TC developed the semantic
graph model defined in this and the following sections.</para>
<section>
<title>Overview</title>
<para>The XDI graph model builds on the RDF
<emphasis>subject-predicate-object</emphasis> triples model <xref
linkend="rdf-concepts"/>. This model in turn builds on the
Entity-Attribute-Value (EAV) data model that dates back over 40 years. Note that in
RDF, a graph node containing a data value is called a <emphasis>literal</emphasis>.
So the RDF data model could also be termed an Entity-Attribute-Literal (EAL)
model.</para>
<para>With RDF 1.1 datasets <xref linkend="rdf-datasets"/>, the model was expanded to
<emphasis>context-subject-predicate-object</emphasis> quads. The fourth
component—context—represents a named RDF graph. The XDI graph model has an analogous
fourth component representing the root of an XDI graph. Thus it is called the
Root-Entity-Attribute-Literal (REAL) model.</para>
</section>
<section>
<title>Node Types</title>
<para>The figure below shows a simple UML class diagram (not an XDI graph) of the
highest level node types in the XDI REAL graph model.</para>
<svg xmlns="http://www.w3.org/2000/svg"; version="1.1" viewBox="0 0 500 270" width="500"
height="270">
<rect x="260" y="20" width="100" height="50" stroke="black" fill="none"/>
<text x="310" y="50" text-anchor="middle">Node</text>
<rect x="180" y="100" width="100" height="50" stroke="black" fill="none"/>
<text x="230" y="130" text-anchor="middle">Context</text>
<rect x="350" y="100" width="100" height="50" stroke="black" fill="none"/>
<text x="400" y="130" text-anchor="middle">Literal</text>
<rect x="60" y="200" width="100" height="50" stroke="black" fill="none"/>
<text x="110" y="230" text-anchor="middle">Root</text>
<rect x="180" y="200" width="100" height="50" stroke="black" fill="none"/>
<text x="230" y="230" text-anchor="middle">Entity</text>
<rect x="300" y="200" width="100" height="50" stroke="black" fill="none"/>
<text x="350" y="230" text-anchor="middle">Attribute</text>
<path d="M 240 100 l 30 -30" stroke="black"/>
<path d="M 370 100 l -30 -30" stroke="black"/>
<path d="M 100 200 l 100 -50" stroke="black"/>
<path d="M 225 200 l 0 -50" stroke="black"/>
<path d="M 350 200 l -100 -50" stroke="black"/>
</svg>
<para>All graph nodes are one of two fundamental types: <glossterm>literal
nodes</glossterm> or <glossterm>context nodes</glossterm>.</para>
<section>
<title>Literal Nodes</title>
<para>As in RDF, XDI literal nodes are the terminal leaf nodes of the graph. They
contain the raw data values described by all the other metadata in the graph.
XDI natively supports the six data types defined by JSON <xref linkend="rfc7159"
/>: <orderedlist>
<listitem>
<para>Number (double-precision floating-point format in
JavaScript)</para>
</listitem>
<listitem>
<para>String (double-quoted Unicode, with backslash escaping)</para>
</listitem>
<listitem>
<para>Boolean (<code>true</code> or <code>false</code>)</para>
</listitem>
<listitem>
<para>Array (an ordered, comma-separated sequence of values enclosed
in square brackets; the values do not need to be of the same
type)</para>
</listitem>
<listitem>
<para>Object (an unordered, comma-separated collection of key:value
pairs enclosed in curly braces, with the '<code>:</code>' character
separating the key and the value)</para>
</listitem>
<listitem>
<para><code>null</code> (empty—note that this is not the equivalent of
<emphasis>undefined</emphasis>, which is when an XDI attribute
has no literal node at all)
</para>
</listitem>
</orderedlist>In addition to the basic data type semantics provided by JSON, the
type of a literal MAY be further described using one or more XDI type statements
(see <emphasis>Type Relations</emphasis> section).</para>
</section>
<section>
<title>Context Nodes</title>
<para>All non-literal nodes in the XDI graph model are called <emphasis>context
nodes</emphasis>. In RDF the term “context” is only used to describe the top
level of semantic context available in the RDF 1.1 graph model, i.e., a named
RDF graph <xref linkend="rdf-concepts"/>. In addition, RDF blank nodes may be
used to add a type of context to the relationship between other nodes. However,
RDF does not use the term “context” for this purpose.</para>
<para>In XDI the term “context” is used uniformly across all levels of the REAL
model to describe all forms of semantic context, including when: <itemizedlist>
<listitem>
<para>A graph root node provides context for another graph root node, an
entity node, or an attribute node.</para>
</listitem>
<listitem>
<para>An entity node provides context for another entity node or an
attribute node.</para>
</listitem>
<listitem>
<para>An attribute node provides context for another attribute
node.</para>
</listitem>
</itemizedlist></para>
<para>See <glossterm>Contextual Arcs and Contextual Statements</glossterm>,
below.</para>
<para>All context nodes MUST have: <orderedlist>
<listitem>
<para>Exactly one <glossterm>context type</glossterm> identitied in XDI
syntax by a single <glossterm>context symbol</glossterm>.</para>
</listitem>
<listitem>
<para>One or more <glossterm>context roles</glossterm> identitied in XDI
syntax by zero or more pairs of <glossterm>context
brackets</glossterm>.</para>
</listitem>
</orderedlist></para>
</section>
<section>
<title>Context Types and Symbols</title>
<para>The XDI REAL model defines six global context types in two groups:</para>
<orderedlist>
<listitem>
<para><glossterm>Classes</glossterm> represent entity and attribute
types.</para>
</listitem>
<listitem>
<para><glossterm>Instances</glossterm> represent entity and attribute
individuals.</para>
</listitem>
</orderedlist>
<para>The context symbols for each type are shown in the table below:<table
frame="none">
<title>Context Symbols</title>
<tgroup cols="4" align="center">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="1.58*"/>
<colspec colname="c3" colnum="3" colwidth="1.01*"/>
<colspec colname="c4" colnum="4" colwidth="8.04*"/>
<thead>
<row>
<entry>Group</entry>
<entry>Context type</entry>
<entry>Symbol</entry>
<entry>Words With This Symbol Also Known As</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows="1">Classes</entry>
<entry>Reserved</entry>
<entry>$</entry>
<entry>keyword, dollar word</entry>
</row>
<row>
<entry>Unreserved</entry>
<entry>#</entry>
<entry>hashtag, dictionary word</entry>
</row>
<row>
<entry morerows="3">Instances</entry>
<entry>Person</entry>
<entry>=</entry>
<entry>equals name / number, person name/number</entry>
</row>
<row>
<entry>Group</entry>
<entry>+</entry>
<entry>plus name / number, group name / number</entry>
</row>
<row>
<entry>Thing</entry>
<entry>*</entry>
<entry>star name /number, thing name / number</entry>
</row>
<row>
<entry>Ordinal</entry>
<entry>@</entry>
<entry>at number, order number</entry>
</row>
</tbody>
</tgroup>
</table></para>
<para>
A definition of each context type is provided in the
<glossterm>Entity</glossterm> section below.</para>
<para>Note that XDI syntax also uses four other single-character symbols:<table
frame="none">
<title>Other XDI Symbols</title>
<tgroup cols="4" align="center">
<colspec colname="c1" colnum="1" colwidth="2.17*"/>
<colspec colname="c2" colnum="2" colwidth="1*"/>
<colspec colname="c3" colnum="3" colwidth="6.59*"/>
<colspec colname="c4" colnum="4" colwidth="3.24*"/>
<thead>
<row>
<entry>Symbol name</entry>
<entry>Symbol</entry>
<entry>Purpose</entry>
<entry>See section:</entry>
</row>
</thead>
<tbody>
<row>
<entry>Literal symbol</entry>
<entry>&</entry>
<entry>Identify a literal arc</entry>
<entry>Literal Arcs and Statements</entry>
</row>
<row>
<entry>Immutability symbol</entry>
<entry>!</entry>
<entry>Express an immutable identifier</entry>
<entry>Mutable and Immutable Identifiers</entry>
</row>
<row>
<entry>Relativity symbol</entry>
<entry>~</entry>
<entry>Express a relative identifier</entry>
<entry>Absolute and Relative Identifiers</entry>
</row>
<row>
<entry>Triple separator</entry>
<entry>/</entry>
<entry>Separate subject, predicate, object in XDI statement
formats</entry>
<entry>Statement Format</entry>
</row>
</tbody>
</tgroup>
</table></para>
</section>
<section>
<title>Context Roles and Brackets</title>
<para>The XDI REAL model defines six context roles in two groups:</para>
<orderedlist>
<listitem>
<para><glossterm>Primary roles</glossterm>: every context node MUST have
exactly one primary role.</para>
</listitem>
<listitem>
<para><glossterm>Secondary roles</glossterm>: depending on the context, a
context node MAY have one or more secondary roles.</para>
</listitem>
</orderedlist>
<para>The context brackets for each role are shown in the table below: <table
frame="none">
<title>Context Brackets</title>
<tgroup cols="4" align="center">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="2.49*"/>
<colspec colname="c3" colnum="3" colwidth="1.04*"/>
<colspec colname="c4" colnum="4" colwidth="4.98*"/>
<thead>
<row>
<entry>Group</entry>
<entry>Context role</entry>
<entry>Brackets</entry>
<entry>Also Known As</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows="2">Primary</entry>
<entry>Root</entry>
<entry><code>( )</code></entry>
<entry>parentheses, parens</entry>
</row>
<row>
<entry>Entity</entry>
<entry>none</entry>
<entry>plain, naked</entry>
</row>
<row>
<entry>Attribute</entry>
<entry><code>< ></code></entry>
<entry>chevrons, angle brackets</entry>
</row>
<row>
<entry morerows="2">Secondary</entry>
<entry>Collection</entry>
<entry><code>[ ]</code></entry>
<entry>square brackets, brackets</entry>
</row>
<row>
<entry>Definition</entry>
<entry><code>| |</code></entry>
<entry>pipes, vertical bars</entry>
</row>
<row>
<entry>Variable</entry>
<entry><code>{ }</code></entry>
<entry>braces, curly brackets</entry>
</row>
</tbody>
</tgroup>
</table></para>
<para>Each context role is defined in its own section below.</para>
</section>
</section>
<section>
<title>Arc Types and Statement Types</title>
<para>An RDF graph is a labeled directed graph in which every predicate represents a
directed arc from a subject node to an object node. Each RDF
subject/predicate/object statement represents exactly one such arc. </para>
<para>The same is true of the XDI graph model, however in XDI, an arc MUST be one of
three types:</para>
<orderedlist>
<listitem>
<para>A <glossterm>literal arc</glossterm> describes the relationship between a
context node and a literal node.</para>
</listitem>
<listitem>
<para>A <glossterm>contextual arc</glossterm> defines the identity, type, and
role of one context node in the context of another context node.</para>
</listitem>
<listitem>
<para>A <glossterm>relational arc</glossterm> describes any other relationship
between two context nodes.</para>
</listitem>
</orderedlist>
<para>Each type of arc is expressed using a specific type of XDI statement as defined in
this section.</para>
<section>
<title>Literal Arcs and Literal Statements</title>
<para>In the XDI REAL model, a literal node MUST be the object of exactly one
literal arc expressed by exactly one <emphasis>literal statement</emphasis>. The
subject of a literal arc MUST be an XDI attribute node. An XDI attribute node
MUST have no more than one literal arc. </para>
<para>There are two key differences between XDI literal arcs and RDF predicates
whose object is a literal node: <orderedlist>
<listitem>
<para><emphasis>In RDF, the semantic meaning of a literal is expressed
by its predicate arc.</emphasis> In XDI, the semantic meaning of
a literal is expressed by the sequence of XDI attribute node(s) that
precede the literal arc.</para>
</listitem>
<listitem>
<para><emphasis>In RDF, a literal may have its own datatype and language
attributes.</emphasis> In XDI, a literal node is always an
atomic leaf node. Any other semantic description of a literal node
MUST be expressed using one or more XDI type statements about the
parent attribute node (see <emphasis>Relational Arcs and Relational
Statements</emphasis> section).</para>
</listitem>
</orderedlist>Because of the first difference above, an XDI literal arc is the
semantic equivalent of the <code>rdf:value</code> property in RDF <xref
linkend="rdf-schema"/>. Thus in XDI, all literal arcs MUST have the same XDI
identifier: the ampersand character <code>&</code>. This is called the
literal symbol. All XDI literal statements MUST use the literal symbol as the
predicate. Examples:
<table frame="none" colsep="1" floatstyle="left">
<title>Examples of Literal Statements</title>
<tgroup cols="3" align="center">
<colspec colname="c1" colnum="1" colwidth="3.82*" align="center"/>
<colspec colname="c2" colnum="2" colwidth="1*" align="center"/>
<colspec colname="c3" colnum="3" colwidth="3.73*" align="center"/>
<thead>
<row>
<entry>Subject</entry>
<entry>Predicate</entry>
<entry>Object</entry>
</row>
</thead>
<tbody>
<row>
<entry><code>=example<#email></code></entry>
<entry><code>&</code></entry>
<entry><code>"foo@example.com"</code></entry>
</row>
<row>
<entry><code>+example<#main><#phone></code></entry>
<entry><code>&</code></entry>
<entry><code>"+44-2222-888888"</code></entry>
</row>
<row>
<entry><code>*!1234[<#event>]<@~78><$t></code></entry>
<entry><code>&</code></entry>
<entry><code>"2010-09-20T10:11:12Z"</code></entry>
</row>
</tbody>
</tgroup>
</table> In XDI JSON serialization format:
<programlisting>{
"=example<#email>": {
"&": "foo@example.com"
},
"+example<#main><#phone>": {
"&": "+44-2222-888888"
},
"*!1234[<#event>]<@78><$t>": {
"&": "2010-09-20T10:11:12Z"
}
}
</programlisting>Because
an XDI attribute node may only contain one literal node, that literal node may
be uniquely addressed by appending the literal symbol & to the XDI address
of the attribute node. Examples:
<table frame="none">
<title>Addressing a Literal Node</title>
<tgroup cols="2">
<colspec colname="c1" colnum="1" colwidth="1.0*" align="center"
colsep="1" rowsep="1"/>
<colspec colname="c2" colnum="2" colwidth="1.0*" align="center"
rowsep="1" colsep="1"/>
<thead>
<row>
<entry>XDI Address of Attribute Node</entry>
<entry>XDI Address of Literal Node</entry>
</row>
</thead>
<tbody>
<row>
<entry align="center"><code>=example<#email></code></entry>
<entry><code>=example<#email>&</code></entry>
</row>
<row>
<entry><code>+example<#main><#tel></code></entry>
<entry><code>+example<#main><#tel>&</code></entry>
</row>
<row>
<entry><code>*!1234[<#event>]<@~78><$t></code></entry>
<entry><code>*!1234[<#event>]<@~78><$t>&</code></entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
<section>
<title>Contextual Arcs and Contextual Statements</title>
<para>In the RDF graph model, a blank node exists to provide context for other
nodes. A blank node does not have a URI. It can only be identified relative to
the RDF graph in which it exists. <xref linkend="rdf-concepts"/>
</para>
<para>In the XDI graph model, all context nodes can provide context for other
context nodes, and all context nodes are uniquely addressable. With the
exception of the common root node, a context node MUST be the object of exactly
one <glossterm>contextual arc</glossterm> expressed by exactly one contextual
statement. The subject of a contextual statement MUST be another context node,
called the parent node or <glossterm>supercontext</glossterm>. Only the common
root node has no parent. The predicate of a contextual statement MUST be empty.
The object of a contextual statement MUST be another context node, called the
<glossterm>child node</glossterm> or <glossterm>subcontext</glossterm>. The
object of a contextual statement MUST have an XDI identifier that is unique in
the parent context. </para>
<para>The result of these requirements is that XDI context nodes form a rooted
directed acyclic graph, called a <glossterm>semantic tree</glossterm>, in which
every node is uniquely addressable and every node has a semantic meaning. The
absolute XDI address of a context node is the sequence of XDI identifiers for
each contextual arc that must be traversed from the common root node to the
target context node. </para>
<para>If the common root node of an XDI graph is itself assigned a URI, all nodes in
the graph become globally addressable in the universal URI addressing space as
recommended by <xref linkend="webarch"/>. See the XDI Addressing section for
details. </para>
<para>Following is an example of three contextual statements (each with the empty
predicate) that establish the context for the final literal statement. In this
example, =example and #car are XDI entities; <code><#interior></code> and
<code><#color></code> are XDI attributes. <table frame="none">
<title>Contextual Statements Defining A Context Path</title>
<tgroup cols="3" align="center">
<colspec colname="subject" colnum="1" colwidth="3.73*"/>
<colspec colname="predicate" colnum="2" colwidth="1*"/>
<colspec colname="object" colnum="3" colwidth="3.73*"/>
<thead>
<row>
<entry>Subject</entry>
<entry>Predicate</entry>
<entry>Object</entry>
</row>
</thead>
<tbody>
<row>
<entry><code>=example</code></entry>
<entry/>
<entry><code>#car</code></entry>
</row>
<row>
<entry><code>=example#car</code></entry>
<entry/>
<entry><code><#interior></code></entry>
</row>
<row>
<entry><code>=example#car<#interior></code></entry>
<entry/>
<entry><code><#color></code></entry>
</row>
<row>
<entry><code>=example#car<#interior><#color></code></entry>
<entry><code>&</code></entry>
<entry><code>“black”</code></entry>
</row>
</tbody>
</tgroup>
</table></para>
<para>Below is the same set of statements in XDI JSON serialization format. Note
that when serialized the empty predicate in a contextual statement is
represented by two forward slashes:
<programlisting>{
"=example": {
"//": [
"#car"
]
},
"=example#car": {
"//": [
"<#interior>"
],
"<#interior>": {
"//": [
"<#color>"
]
},
"<#interior><#color>": {
"&": "black"
}
}
}
</programlisting></para>
<para>Contextual statements are inherent in the XDI addresses of the subjects and
objects of literal or relational statements. Therefore contextual statements are
not included in the JSON serialization by default and are only added if they are
explicitly requested using the <code>implied</code> parameter (see the
Serialization section for details). Below is the same example graph without the
contextual statements:
<programlisting>{
"=example#car": {
"<#interior><#color>": {
"&": "black"
}
}
}</programlisting></para>
</section>
<section>
<title>Relational Arcs and Relational Statements</title>
<para>Any relationship between two XDI graph nodes that is not described by a
literal or contextual arc is described by a <glossterm>relational
arc</glossterm> expressed by a <glossterm>relational statement</glossterm>.
The predicate of a relational statement MUST be a sequence of one or more XDI
entities. </para>
<para> XDI relational arcs are the equivalent of RDF properties that describe the
relationship between two RDF resources. Examples:
<table frame="none">
<title>Examples of Relational Statements</title>
<tgroup cols="3" align="center">
<colspec colname="c1" colnum="1" colwidth="1.0*"/>
<colspec colname="c2" colnum="2" colwidth="1.0*"/>
<colspec colname="c3" colnum="3" colwidth="1.0*"/>
<thead>
<row>
<entry>Subject</entry>
<entry>Predicate</entry>
<entry>Object</entry>
</row>
</thead>
<tbody>
<row>
<entry><code>=person-1</code></entry>
<entry><code>#friend</code></entry>
<entry><code>=person-2</code></entry>
</row>
<row>
<entry><code>=person-1</code></entry>
<entry><code>#friend</code></entry>
<entry><code>=person-3</code></entry>
</row>
<row>
<entry><code>=person-1</code></entry>
<entry><code>#best#friend</code></entry>
<entry><code>=person-3</code></entry>
</row>
<row>
<entry><code>=person-1</code></entry>
<entry><code>#employer</code></entry>
<entry><code>+example.company</code></entry>
</row>
<row>
<entry><code>[#device]*!:uuid:...</code></entry>
<entry><code>#owner</code></entry>
<entry><code>=person-1</code></entry>
</row>
</tbody>
</tgroup>
</table></para>
<para>In the XDI JSON serialization, a predicate expressing a relational arc is
prefixed with a forward slash character:
<programlisting>{
"=person-1": {
"/#friend": [
"=person-2",
"=person-3"
],
"/#best#friend": [
"=person-3"
],
"/#employer": [
"+example.company"
]
},
"[#device]*!:uuid:...": {
"/#owner": [
"=person-1"
]
}
}
</programlisting>
Relational statements may also be used to assert type or subclass relationships.
See Type Relations. </para>
</section>
</section>
<section>
<title>Visual Graph Diagramming Notation</title>
<para>For consistency across implementations, the XDI Technical Committee RECOMMENDS the
notation shown in the figure below for visual diagramming of XDI graphs. <figure>
<title>Visual Graph Symbols</title>
<mediaobject>
<imageobject>
<imagedata fileref="xdi-core-diagrams-2015-10-05.001.jpg"/>
</imageobject>
</mediaobject>
</figure>The root node symbol (a circle) is suggestive of the parentheses <code>(
)</code> used in XDI syntax, and the attribute node symbol (a diamond) is
suggestive of the chevron brackets <code>< ></code>. The root node symbol is open
to represent that an XDI graph is only a container of XDI statements. The entity and
attribute node symbols are solids to represent concrete identities and properties. </para>
<para>For diagrams that support color, it is RECOMMENDED to use: <itemizedlist>
<listitem>
<para>A red outlined circle for the common root node.</para>
</listitem>
<listitem>
<para>A blue outlined circle for a peer root node.</para>
</listitem>
<listitem>
<para>A green outlined circle for an inner root node.</para>
</listitem>
</itemizedlist>Literal nodes are a direct representation of the JSON value. If the
value is truncated to save space, it is RECOMMENDED that the portion shown end in
ellipses.</para>
<para>All contextual and relational arcs MUST be labeled. A literal arc MAY be labeled
with the ampersand symbol, but it is not recommended. For a contextual arc, the
label MUST be the unique XDI identifier of the object context node. For a relational
arc, the label MUST be the predicate of the relational statement it
represents.</para>
<para>Since there are many ways to organize an XDI graph diagram that uses this
notation, the following two forms are RECOMMENDED: <orderedlist>
<listitem>
<para><emphasis role="bold">Free form.</emphasis> In this organization, the
common root appears roughly in the center of the diagram, and arcs are
arranged radiating outward from it so as to best communicate the
semantic information in the graph.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Tree form.</emphasis> This organization mimics a
typical file or directory tree layout. The common root node appears in
the upper-left-hand corner, contextual and literal arcs follow a grid,
and only relational arcs are curved.</para>
</listitem>
</orderedlist>The choice of form depends on the particular XDI graph being shown. It
is RECOMMENDED that viewing/editing tools support both forms and enable viewers to
switch between them dynamically. </para>
<para>This figure shows the example XDI graph from the Introduction section in free form:<figure>
<title>Graph in free form</title>
<mediaobject>
<imageobject>
<imagedata fileref="freeformgraph.jpg"/>
</imageobject>
</mediaobject>
</figure>This figure shows the same graph in tree form:<figure>
<title>Graph in tree form</title>
<mediaobject>
<imageobject>
<imagedata fileref="treeformgraph.jpg"/>
</imageobject>
</mediaobject>
</figure>
</para>
</section>
</section>
<section>
<title>Entities</title>
<para>In the XDI REAL model (and the Entity-Attribute-Value model upon which it is based),
an <glossterm>entity</glossterm> is anything (except an XDI graph itself) that can be
independently identified and described, whether tangible or intangible. An entity may
represent a person, group/organization, physical or digital object, concept, definition,
or even a variable that may itself represent any set of these things. </para>
<para>From a linguistic perspective, entities are the “nouns” of XDI. However, this does not
mean an entity is the only type of node that can serve as the subject of an XDI
statement. In the XDI REAL model, both a root node (representing an entire XDI graph)
and an attribute node may also serve as an XDI subject (and both are disjoint from
entities). Thus an XDI entity is not exactly the same thing as an RDF resource—the
latter may be anything with a URI (which would include XDI root and attribute nodes). </para>
<para> XDI entities fall into two groups: classes and instances.</para>
<section>
<title>Classes</title>
<para>A <glossterm>class</glossterm>, also known as a <glossterm>concept</glossterm> in
description logic, is a set of entities that have some attribute(s) or propert(ies)
in common. The set of entities belonging to the class are its
<glossterm>members</glossterm>. In XDI, the instances of a class share the same
<glossterm>definition</glossterm>.</para>
<para>XDI classes fall into two groups: reserved and unreserved.</para>
<section>
<title>Reserved ($ Symbol)</title>
<para> A <glossterm>reserved class</glossterm> is a class defined by the XDI
Technical Committee to establish the universal grammar of XDI. The goal of the
XDI TC is to define the smallest set of reserved classes that produce the
greatest degree of semantic interoperability across XDI graphs.</para>
<para>The XDI identifier of a reserved class MUST begin with the <code>$</code>
context symbol. The <code>$</code> context symbol by itself represents the class
of all reserved classes. Reserved class names are also known as
<glossterm>dollar words</glossterm> or <glossterm>keywords</glossterm>.
Examples: <programlisting>$iri
$do
$and
$or
$not
$public</programlisting>A
reserved class name MUST be immutable and MUST NOT use the XDI immutability
symbol. A reserved class name MUST be defined in a specification from either: 1)
the OASIS XDI Technical Committee (including this specification), 2) another
OASIS Technical Committee specified by the OASIS XDI Technical Committee, or 3)
another standards body specified by the OASIS XDI Technical Committee. </para>
</section>
<section>
<title>Unreserved (# Symbol)</title>
<para>An unreserved class is a class defined by any XDI authority other than the
OASIS XDI Technical Committee or its specified delegate. The XDI identifier of
an unreserved class MUST begin with the <code>#</code> context symbol. The
<code>#</code> context symbol by itself represents the class of all
unreserved classes. Unreserved class names are also known as
<glossterm>tags</glossterm>, <glossterm>hashtags</glossterm>, or
<glossterm>dictionary words</glossterm>. Examples:
<programlisting>#email
#passport
#home
#work
#friend
#enemy</programlisting></para>
<para>An unreserved class name MUST be immutable and MUST NOT use the XDI
immutability symbol. </para>
<para>In a dictionary context, unreserved class names are called
<glossterm>dictionary words</glossterm>. Dictionary words MAY be defined by
any XDI authority in any XDI context. Dictionary words whose semantics are
intended to be confined to a specific set of XDI contexts SHOULD be defined in
the context of the XDI authority (person or group) responsible for those
contexts. Dictionary words that are intended to be generic, i.e., to share the
same semantics in all XDI graphs, SHOULD be defined directly in the common root
context. See Roots, below. </para>
<para>This begs the question of authority for generic XDI dictionary words. Like the
nouns in a human language, such words represent a community consensus about
shared semantics. Thus it is RECOMMENDED that generic XDI dictionary words be
specified in an XDI community dictionary cooperatively maintained by the XDI
authorities contributing to that community. </para>
<para>This is the model popularized (and proven to scale) by Wikipedia for
human-readable concept definitions, and also being followed by machine-readable
community ontologies such as schema.org.</para>
</section>
</section>
<section>
<title>Instances</title>
<para>An instance, also known as an <glossterm>individual</glossterm> in description
logic, is a member of a class. The four XDI context symbols for instances are based
on the fundamental nature of the context being identified:<table frame="none">
<title>Instance Types</title>
<tgroup cols="5" align="center">
<colspec colname="c1" colnum="1" colwidth="1.0*"/>
<colspec colname="c2" colnum="2" colwidth="1.0*"/>
<colspec colname="c3" colnum="3" colwidth="1.0*"/>
<colspec colname="c4" colnum="4" colwidth="1.0*"/>
<colspec colname="c5" colnum="5" colwidth="1.0*"/>
<thead>
<row>
<entry>Instance type</entry>
<entry>Symbol</entry>
<entry>Personal authority?</entry>
<entry>Legal authority?</entry>
<entry>Ordered</entry>
</row>
</thead>
<tbody>
<row>
<entry>Person</entry>
<entry><code>=</code></entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>Group</entry>
<entry><code>+</code></entry>
<entry>No</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>Thing</entry>
<entry><code>*</code></entry>
<entry>No</entry>
<entry>No</entry>
<entry>No</entry>
</row>
<row>
<entry>Ordinal</entry>
<entry><code>@</code></entry>
<entry>No</entry>
<entry>No</entry>
<entry>Yes</entry>
</row>
</tbody>
</tgroup>
</table>The first three instance types are based on authority and accountability. </para>
<orderedlist>
<listitem>
<para>A <glossterm>person</glossterm> is the only entity instance that can be
held personally accountable for actions taken using the XDI protocol.
</para>
</listitem>
<listitem>
<para>A <glossterm>group</glossterm> of people (in any form) is the only entity
instance that may be held legally but not personally accountable for actions
taken using the XDI protocol. </para>
</listitem>
<listitem>
<para>A <glossterm>thing</glossterm> is an entity instance that may initiate an
XDI action but cannot be held legally accountable it, such as a physical
device or a software program that cannot act “of its own accord”.</para>
</listitem>
</orderedlist>
<para>Since legal accountability plays a significant role in XDI policies and link
contracts, the table below defines terms for referring to precise subsets of these
three types of entity instances:<table frame="none">
<title>Terminology for Instance Types</title>
<tgroup cols="4" align="center">
<colspec colname="c1" colnum="1" colwidth="1.0*"/>
<colspec colname="c2" colnum="2" colwidth="1.0*"/>
<colspec colname="c3" colnum="3" colwidth="1.0*"/>
<colspec colname="c4" colnum="4" colwidth="1.0*"/>
<thead>
<row>
<entry>XDI term</entry>
<entry>Includes Person?</entry>
<entry>Includes Group?</entry>
<entry>Includes Thing?</entry>
</row>
</thead>
<tbody>
<row>
<entry>XDI person</entry>
<entry>Yes</entry>
<entry>No</entry>
<entry>No</entry>
</row>
<row>
<entry>XDI authority</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>No</entry>
</row>
<row>
<entry>XDI actor</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
</tbody>
</tgroup>
</table></para>
<para>The legal implications of each of these terms with regard to XDI link contracts
and policies is further discussed in the XDI Policy 1.0 specification <xref
linkend="xdi-policy-1.0"/>. </para>
<svg xmlns="http://www.w3.org/2000/svg"; viewBox="0 0 200 200" width="200" height="200"
version="1.1" style="float:right">
<g transform="translate(100,100)" style="stroke-width:2">
<circle stroke="black" r="90" fill="none"/>
<circle stroke="blue" r="65" fill="none"/>
<circle stroke="red" r="35" fill="none"/>
</g>
<g transform="translate(100,87)">
<text y="20" text-anchor="middle">Person</text>
<text y="65" text-anchor="middle">Authority</text>
<text y="95" text-anchor="middle">Actor</text>
</g>
</svg>
<para>The final type of instance identifiers are used to specify logical order. Since
XDI graphs, like RDF graphs, are unordered by default, a special class of instance
identifiers called <glossterm>ordinal identifiers</glossterm> is needed to define
explicit ordering within an XDI context.</para>
<section>
<title>Personal (= Symbol)</title>
<para>The XDI identifier of a natural person is called a personal authority. A
personal authority MUST begin with the <code>=</code> context symbol (selected
to suggest equality among peers). The = context symbol by itself represents the
class of all personal authorities. Personal authority identifiers are also known
as equal names (mutable) or equal numbers (immutable). </para>
<para>As explained in the XDI Addressing section, the XDI identifier for a person
may be either an XDI name, an XDI number, or an encapsulated IRI. Examples of
personal XDI names:</para>
<programlisting>=example
=example-name
=example.name</programlisting>
<para>Example of a personal XDI number (in this case, using the XDI UUID
scheme):</para>
<programlisting>=!:uuid:33ad7beb-1abc-4a26-b892-466df4379a51</programlisting>
<para> Examples of personal encapsulated IRIs:</para>
<programlisting>=(https://example.name/)
=(mailto:foo@example.com)</programlisting>
<para>A personal XDI identifier represents a new form of digital identity for
individuals. This can be referred to as <glossterm>sovereign
identity</glossterm> because XDI’s heterarchical and contextual graph model
enables an individual to interact with other XDI authorities (both persons and
groups) as an independent autonomous peer. <xref linkend="sovereign-identity"/>.
</para>
</section>
<section>
<title>Group (+ Symbol)</title>
<para>The second class of actor that may be held legally responsible for XDI
interactions is a group — a set of people whose existence is independent of any
one person. The XDI identifier of any group MUST begin with the <code>+</code>
context symbol. The <code>+</code> context symbol by itself represents the class
of all groups. Group identifiers are also known as <glossterm>plus
names</glossterm> (mutable) or <glossterm>plus numbers</glossterm>
(immutable). Examples:
<programlisting>+example
+example-company
+example.org
+!:uuid:f336a645-f5a9-41b7-ab80-ace41a8f69c2
+(https://example.com/)
+(mailto:division@example.com)</programlisting>An
XDI group identifier may represent any type of “legal person” that is not a
natural person, including a group, an association, sole proprietorship,
partnership, corporation, or any type of governing, political, or social body.
</para>
</section>
<section>
<title>Thing (* Symbol)</title>
<para>Any unordered XDI instance that does not represent a person or a group
represents an XDI <glossterm>thing</glossterm>. This includes any device,
sensor, or other object that when connected to a network are commonly referred
to as the Internet of Things. However it also includes any other logical “thing”
such as a software program, a database, a data structure, a concept, or a unique
member of a set. </para>
<para>Note: an XDI thing is not the same as an owl:Thing, which is the root class of
all classes in OWL <xref linkend="owl"/>.</para>
<para>The XDI identifier of an thing MUST begin with the <code>*</code> context
symbol. The <code>*</code> context symbol by itself represents the class of all
things. XDI thing identifiers are also known as <glossterm>star
names</glossterm> (mutable) or <glossterm>star numbers</glossterm>
(immutable). </para>
<para>A set of unordered instance nodes in a context MUST NOT be interpreted as
having any logical order regardless of their XDI identifiers or their document
order in a serialized XDI JSON document. </para>
<para>By itself, an XDI thing identifier does not convey any semantics about its
type. The relationship of an XDI thing to a class of which it is an instance MAY
be asserted in two ways: <orderedlist>
<listitem>
<para><emphasis role="bold">By making the thing a member of a
collection.</emphasis> By definition a member of a collection is
an instance of the collection class. See Collections. </para>
</listitem>
<listitem>
<para><emphasis role="bold">By describing a thing instance with one or
more XDI type statements.</emphasis> See Type Relations.</para>
</listitem>
</orderedlist></para>
<para>Following is an example of XDI things serving as entity instances (in thsi
case identified using immutable UUIDs):
<programlisting>{
"+example[#item]*!:uuid:33ad7beb-1abc-4a26-b892-466df4379a51": {
"<#price>": {
"&": "24,995"
}
},
"+example[#item]*!:uuid:f336a645-f5a9-41b7-ab80-ace41a8f69c2": {
"<#price>": {
"&": "36,995"
}
},
"+example[#item]*!:uuid:1c958708-d5aa-4213-a6a9-73dd423502b3": {
"<#price>": {
"&": "18,495"
}
}
}</programlisting></para>
<para>Following is an example of XDI things serving as attribute instances. This
example also uses immutable identifiers with the XDI UUID scheme (see XDI
Schemes). Note that these instance identifiers will not change even if the
literal value changes.
<programlisting>{
"=example": {
"[<#email>]<*!:uuid:35bcc3c0-da48-df9b-a16b-0002a5d557c4>": {
"&": "alice#example.com"
},
"[<#email>]<*!:uuid:fbc71e40-da47-47a6-a00e-0002a5d577b5>": {
"&": "alice.roth@example.net"
},
"[<#email>]<*!:uuid:62079220-da48-21cc-aca9-0002a5d51fe6>": {
"&": "stillalice@example.org"
}
}
}</programlisting></para>
</section>
<section>
<title>Ordinal (@ Symbol)</title>
<para>In the absence of ordinal identifiers, the set of nodes in an XDI context or
the document order of XDI statements in a serialized XDI JSON document MUST NOT
be interpreted as having any logical order. </para>
<para>Since the order of a set of subcontexts is always relative to the parent
context, to express logical order within an XDI context, the ordered subcontexts
MUST use a relative ordinal identifier. A relative ordinal identifier: <orderedlist>
<listitem>
<para>MUST begin with the <code>@</code> context symbol. </para>
</listitem>
<listitem>
<para>MUST include the <code>~</code> relativity symbol. </para>
</listitem>
<listitem>
<para>MUST be a nested identifier.</para>
</listitem>
</orderedlist>See Absolute and Relative Identifiers and Rooted and Nested
Identifiers. </para>
<para>The @ context symbol by itself represents the class of all ordered instances. </para>
<para>An absolute ordinal identifier (one that does not use the ~ relativity symbol)
represents the concept of a particular order position (e.g., the concept of the
number “3”) and not the actual relative position in an ordered sequence.
Absolute ordinal identifiers MUST NOT be interpreted as being members of an
ordered set.</para>
<para>By default, ordinal identifiers are non-negative integers, called
<glossterm>order numbers</glossterm>. The logical order of a set of order
numbers MUST begin with the number zero if present. The document order of the
ordered instances in a serialized XDI JSON document MUST be ignored. An example
of ordered entity instances (in this case inside a collection):
<programlisting>{
"=example#favorite[#car]@~0": {
"$ref": [
"=example[#car]*!:uuid:33ad7beb-1abc-4a26-b892-466df4379a51"
]
},
"=example#favorite[#car]@~1": {
"$ref": [
"=example[#car]*!:uuid:f336a645-f5a9-41b7-ab80-ace41a8f69c2"
]
},
"=example#favorite[#car]@~2": {
"$ref": [
"=example[#car]*!:uuid:1c958708-d5aa-4213-a6a9-73dd423502b3"
]
}
}</programlisting>
Order numbers also apply to attribute instances as shown in this example:
<programlisting>{
"=example": {
"<#pref>[<#email>]<@~0>": {
"&": "alice#example.com"
},
"<#pref>[<#email>]<@~1>": {
"&": "alice.roth@example.net"
},
"<#pref>[<#email>]<@~2>": {
"&": "stillalice@example.org"
}
}
}</programlisting>Although
order numbers are the default type of ordinal identifier, they are not the only
ordering algorithm. By appending an XDI scheme, ordinal identifiers may use
other ordering algorithms, such as alphabetic, alphanumeric, or byte order. See
XDI Schemes. </para>
<para>Note: Explicit ordering of XDI graph nodes within a context using ordinal
identifiers is different than canonical ordering of XDI statements for purposes
of digital signatures. Canonical ordering is specified in the XDI Cryptographic
Mechanisms 1.0 specification. <xref linkend="xdi-security-1.0"/></para>
</section>
</section>
</section>
<section>
<title>Attributes < ></title>
<para>In the Entity-Attribute-Value (EAV) model, an attribute is a property of an entity
that does not exist independently of the entity it describes. An attribute (and only an
attribute) may have a literal value; an entity by itself cannot have a literal value. </para>
<para>In the RDF subject-predicate-object graph model, an attribute of a resource node is
described by a predicate whose object is a literal node. In RDF, an attribute is not
required to be unique; a resource may have multiple predicates with the same URI
describing multiple literal values for the same attribute (e.g., multiple email
addresses for a person). </para>
<para>In the XDI REAL model, all attributes are uniquely addressable because they are
modeled as context nodes in an attribute role. The XDI identifier of an attribute
context node MUST be an entity class or entity instance enclosed in chevron brackets
<code>< ></code>. Examples:
<programlisting>=example<#email>
+example-company<#support><#tel>
+(https://example.com/)#shipping#address<#city>
*!: uuid:9ce739f0-7665-11e2-bcfd-0800200c18f2<#price>
</programlisting>Any
type of XDI context node in any role (root, entity, attribute, collection, definition,
variable) MAY have an attribute node. Note that attributes of a root node are attributes
of that XDI graph as a whole and not attributes of any entity within that graph. </para>
<para>There are three reasons to model attributes as context nodes. First, it means all XDI
attributes, like all XDI contexts, are uniquely addressable. This applies even if an
entity has multiple values of the same attribute, e.g. a person with multiple email
address attributes. This can be modeled as a collection where each instance is uniquely
identified, as shown below.
<programlisting>{
"=example": {
"[<#email>]<*!:uuid:35bcc3c0-da48-df9b-a16b-0002a5d557c4>": {
"&": "alice#example.com"
},
"[<#email>]<*!:uuid:fbc71e40-da47-47a6-a00e-0002a5d577b5>": {
"&": "alice.roth@example.net"
},
"[<#email>]<*!:uuid:62079220-da48-21cc-aca9-0002a5d51fe6>": {
"&": "stillalice@example.org"
}
}
}</programlisting></para>
<para>Secondly, attributes can specialize other attributes (see <emphasis>Specialization and
Generalization</emphasis> section). For example, <code><#home></code> and
<code><#work></code> can be used to to specialize <code><#email></code>.
<programlisting>=example<#home><#email>
=example<#work><#email>
</programlisting>Thirdly,
an attribute may itself have attributes. For example, to express the timestamp when the
literal value of an attribute was assigned, add the <code><$t></code> (timestamp)
attribute.
<code>=example<#work><#email><$t>
</code><programlisting>{
"=example": {
"<#work><#email>": {
"&": "alice.roth@example.net"
},
"<#work><#email><$t>": {
"&": "2010-09-20T10:11:12Z"
}
}
}</programlisting>Standard
XDI attributes like <code>$t</code> are defined in the XDI Dictionary specification
<xref linkend="xdi-dictionary-1.0"/>.</para>
<para>As defined in Literal Arcs and Literal Statements, only an attribute node may have a
literal node, and it may have exactly zero or one literal node. The semantics of the
relationship between an attribute node, its literal node, and the value of that literal
node are very precise: <orderedlist>
<listitem>
<para>If an attribute node does not have a literal node, then the value of that
attribute is <glossterm>undefined</glossterm>.</para>
</listitem>
<listitem>
<para>If an attribute node has a literal node, then its value is the literal
JSON value of the literal node, including: <orderedlist>
<listitem>
<para><code>null</code> for a null value. </para>
</listitem>
<listitem>
<para><code>""</code> for an empty string. </para>
</listitem>
</orderedlist></para>
</listitem>
</orderedlist> The following example in JSON illustrates these rules. <orderedlist>
<listitem>
<para><code>=example<#home><#email></code> is undefined. Note that in this
case, the attribute node must be defined with an explicit contextual
statement because no statement with the literal symbol will exist.</para>
</listitem>
<listitem>
<para><code>=example<#work><#email></code> has the literal JSON value of
null.</para>
</listitem>
<listitem>
<para><code>=example<#student><#email></code> has the literal JSON value
of the empty string.</para>
</listitem>
<listitem>
<para><code>=example<#employed></code> has the literal JSON value
false.</para>
</listitem>
</orderedlist>
<programlisting>{
"=example": {
"<#home>": {
"//": [
"<#email>"
]
},
"<#work><#email>": {
"&": null
},
"<#student><#email>": {
"&": ""
},
"<#employed>": {
"&": false
}
}
}
</programlisting></para>
</section>
<section>
<title>Roots ( )</title>
<para>After entities and attributes, the third primary role for a context node in the XDI
REAL model is to represent the root of an XDI graph. While there is exactly one ultimate
root node for all XDI graphs—the common root node—the heterarchical design of XDI means
that it also has two other types of root nodes: peer roots and inner roots.</para>
<section>
<title>The Common Root</title>
<para>Every XDI graph MUST have exactly one common root node. It is so named because it
the one logical node shared by all XDI graphs. To use the analogy of trees in a
forest, if every tree represents an XDI graph, the common root node is the earth. </para>
<para>The XDI address of the common root node is the empty address. Thus any XDI
statement that does not begin with a peer root address or an inner root address is
by definition relative to the common root node. The set of all XDI context nodes
that are relative only to the common root node and not to a peer root node is called
the common graph. </para>
<para>The common root node MUST NOT be the object of a direct contextual statement. It
MAY be the object of an inverse contextual statement. See Inverse Relations. </para>
<para>The common root node of any XDI graph MAY describe the location of its own XDI
endpoint using the <code><$iri></code> attribute as defined in the XDI Discovery
specification <xref linkend="xdi-discovery-1.0"/>. Note that all attributes of a
root node are attributes of an XDI graph as a whole and not attributes of any entity
within that graph.</para>
</section>
<section>
<title>Peer Roots</title>
<para>A peer root node is a context node in one XDI graph that represents the common
root node of another independent XDI graph. This concept is fundamental to XDI
architecture—peer root nodes are how the XDI graph model is able to represent
peer-to-peer relationships between independent XDI graphs where each graph is its
own rooted tree. A node that serves as a peer root node in one XDI graph MUST serve
as the common root node of its own XDI graph. </para>
<para>Peer root nodes may be nested to any depth within a single XDI graph. The set of
contextual arcs describing these peer root nodes forms a hierarchical rooted tree.
However each peer root node can be envisioned as a point on a global circle
representing the logical common root node of all XDI graphs. Pick any specific
starting point on this circle, and the references to the other starting points (peer
roots) may be arranged hierarchically. However if you move to a different starting
point, you will discover a different hierarchy. Each hierarchy represents the set of
XDI peer root nodes known to a particular peer. </para>
<para>
<figure>
<title>Conceptual Diagram of Peer Roots</title>
<mediaobject>
<imageobject>
<imagedata fileref="xdi-core-diagrams-2015-10-05.004.jpg"/>
</imageobject>
</mediaobject>
</figure>The graph contained by a peer root node is called a peer graph. A peer
graph MUST be a subset of the independent XDI graph which the peer root node
represents. Every peer graph is a subset of the logical XDI common graph. Thus the
XDI statements in every peer graph MUST be logically consistent. (The same is not
true for Inner Graphs, below). </para>
<para>The XDI identifier of a peer root node MUST be enclosed in parentheses ( ) and
MUST NOT be preceded by an XDI context symbol. The identifier contained within the
parentheses MUST be either an XDI entity identifier or an absolute URI. Examples:
<programlisting>(=example)
(+example-company)
(*!: uuid:9ce739f0-7665-11e2-bcfd-0800200c18f2)
(https://example.com/)
</programlisting>Like
other context nodes, peer root nodes may be nested to any depth. This enables XDI
authorities to create different XDI graphs at different XDI endpoints for different
purposes and link them for the purpose of discovery. Examples:
<programlisting>(=example)(#household)
(+example-company)(#legal)(#mexico)
</programlisting>In
keeping with the XDI REAL model, peer root and inner root nodes MUST precede entity
or attribute nodes in the context tree. Like the common root node, a peer root node
MAY use the <code><$iri></code> attribute to describe the network location of its
XDI endpoint. Using the XDI protocol to discover the IRI for XDI peer root nodes is
defined in the XDI Discovery specification <xref linkend="xdi-discovery-1.0"/>.
Following is an example XDI graph from which the IRI of two peer roots can be
discovered:
<programlisting>{
"(=example)": {
"<#iri>": {
"&": "https://xdi.example.com/";
}
},
"(=example)(#household)": {
"<#iri>": {
"&": "https://xdi.example.com/household/";
}
}
}</programlisting>The
common root node of an XDI graph may also describe its own XDI address using a
direct or inverse XDI equivalence statement to a peer root node (see Equivalence
Relations). This is called the graph self-description pattern and illustrated in the
two example statements below. <orderedlist>
<listitem>
<para>Direct equivalence statement: the peer root is the subject and the
common root is the object; the address of the common root is the empty
string.</para>
</listitem>
<listitem>
<para>Inverse equivalence statement: the common root is the subject and the
peer root is the object; the common root is represented by the outermost
JSON object enclosing the entire JSON document.</para>
</listitem>
</orderedlist>
<programlisting>{
"(=example)": {
"/$ref": [
""
]
},
"/$is$ref": [
"(=example)"
]
}</programlisting>Note:
in the XDI Messaging specification, the term “peer” is used for an XDI agent or
endpoint that sends and receives XDI messages between XDI graphs.</para>
</section>
<section>
<title>Inner Roots and Reification</title>
<para>The third type of root node plays a special role in XDI architecture. An
<glossterm>inner root node</glossterm> represents the root of an XDI graph that
is itself the object of an XDI relational statement. The graph contained by an inner
root node is called an inner graph. </para>
<para>The XDI identifier of an inner root node MUST be enclosed in parentheses ( ) and
MUST NOT be preceded by an XDI context symbol. The identifier contained within the
parentheses MUST include the subject and predicate of the XDI relational statement
whose object is the root node of the inner graph. The subject comes first and is
separated from the predicate by a forward slash:
<programlisting>(=example/#nominated)
(+example-company/#hired)
(*!: uuid:9ce739f0-7665-11e2-bcfd-0800200c18f2/#buyer)</programlisting>In
RDF terms, each context node in an inner graph represents a reification of an XDI
statement. <xref linkend="reification"/> The subject and predicate of the reified
statement are expressed by the XDI identifier of the inner root node. The object of
the statement is a context node below the inner graph. Examples: <table frame="none">
<title>Reifying XDI Statements with Inner Roots</title>
<tgroup cols="2" align="center">
<colspec colname="c1" colnum="1" colwidth="1.0*"/>
<colspec colname="c2" colnum="2" colwidth="1.0*"/>
<thead>
<row>
<entry>XDI Statement</entry>
<entry>XDI Address of Reified Statement</entry>
</row>
</thead>
<tbody>
<row>
<entry><code>=a/#b/=c</code></entry>
<entry><code>(=a/#b)=c</code></entry>
</row>
<row>
<entry><code>=alice/#buddy/=charlie</code></entry>
<entry><code>(=alice/#buddy)=charlie</code></entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>As in RDF, once a statement has been reified, it is now a new XDI statement that
can serve as subject for other statements that describe the reified statement. This
<glossterm>inner graph pattern</glossterm> is very common in XDI graphs since
reification can be used to describe any relationship between two entities. Examples:
<programlisting>(=a/#b)=c/#d/=e
(=alice/#buddy)=charlie/#dentist/=edith
(=example/#hired)=abc/#employer/+example-company
(+example-company/+acquired)+other-co<$year>/&/"2014"
</programlisting>The
inner graph pattern is fundamental to the structure of <glossterm>link
contract</glossterm>s, the primary control structure in the XDI protocol. Link
contracts are defined in the XDI Policy specification <xref linkend="xdi-policy-1.0"
/>. </para>
<para>An inner root node or a context node within it can also serve as the object of an
XDI
statement:<programlisting>=a/#b/(=c/#d)=e
=alice/#buddy/(=charlie/#dentist)=edith
</programlisting>
Like other context nodes, peer root nodes MAY be nested to any depth. This enables
“statements about statements about statements”. Examples:
<programlisting>(=a/#b)(=c/#d)=e/#f/=g
(=alice/#buddy)(=charlie/#dentist)=edith/#friend/=greg
</programlisting>
In the JSON serialization, when a sequence of peer roots and/or inner roots serves
as an XDI subject, they are serialized as first level nested JSON objects. See
Serialization.
<programlisting>{
"(=alice/#buddy)": {
"=charlie": {
"/#dentist": [
"=edith"
]
}
},
"(=example/#hired)": {
"=abc": {
"/#employer": [
"+example-company"
]
}
},
"(+example-company/+acquired)": {
"+other-co": {
"<$year>": {
"&": "2014"
}
}
},
"=alice": {
"/#buddy": [
"(=charlie/#dentist)=edith"
]
}
}</programlisting>
</para>
<para>There is an important distinction between peer graphs and inner graphs. Peer
graphs are independent graphs that each contain a subset of the logical XDI common
graph. By contrast, an inner graph can only be understood in the context of the
unique XDI subject/predicate relationship that defines it. Therefore XDI statements
in inner graphs are not required to be logically consistent with statements in the
logical XDI common graph. XDI statements contained by an inner graph are relative to
its specific inner root node and can only be merged with another XDI graph by also
merging the containing inner root node. </para>
<para>Therefore inner graphs are part of the XDI common graph and can be visualized as
wholly contained “graphs within graphs”.
Because peer graphs are all subsets of the
logical XDI common graph, peer graphs may also contain inner graphs.</para>
<figure>
<title>Inner Root Circle Diagram</title>
<mediaobject>
<imageobject>
<imagedata fileref="xdi-core-diagrams-2015-10-05.005.jpg"/>
</imageobject>
</mediaobject>
</figure>
</section>
</section>
<section>
<title>Collections [ ]</title>
<para>In the XDI REAL model, a context node whose role is to define a set of other context
nodes of the same type is called a <glossterm>collection</glossterm>. The XDI identifier
of an collection node MUST be enclosed with square brackets [ ]. </para>
<para>A collection is either an entity collection or an attribute collection. In either case
the XDI identifier of the collection node MUST be a class (i.e must start with the $ or
# context symbol), called the collection class. </para>
<para>The set of context nodes that belong to the collection are called its members. To be a
member of a collection, a context node MUST be: a) a child subcontext of the collection
node, and b) a valid instance of the collection class.</para>
<para>A collection MAY be any class in a primary role, e.g., a root collection, an entity
collection, or an attribute collection. Member instances of a collection MUST be of the
same type as the collection, e.g., members of a <code>[#passport]</code> entity
collection must represent instances of a passport, and members of a
<code>[<#color>]</code> attribute collection must represent instances of a color. </para>
<para>A collection MAY contain other child nodes, however any child node that is not an
ordered or unordered instance of the collection class is not a member of the collection,
but a descriptor of the collection. The following example shows a collection of email
address attributes with three thing instances as members, plus a timestamp attribute not
a member of the collection but that describes the collection.
<programlisting>{
"=example": {
"[<#email>]<*!:uuid:35bcc3c0-da48-df9b-a16b-0002a5d557c4>": {
"&": "alice@example.com"
},
"[<#email>]<*!:uuid:fbc71e40-da47-47a6-a00e-0002a5d577b5>": {
"&": "alice.roth@example.net"
},
"[<#email>]<*!:uuid:62079220-da48-21cc-aca9-0002a5d51fe6>": {
"&": "stillalice@example.org"
},
"[<#email>]<$t>": {
"&": "2010-09-20T10:11:12Z"
}
}
}</programlisting>A
collection may also consist of ordered member instances, for example to indicate the
priority or preference of those instances. Here is the same example showing ordered
member instances:
<programlisting>{
"=example": {
"[<#email>]<@0>": {
"&": "alice@example.com"
},
"[<#email>]<@1>": {
"&": "alice.roth@example.net"
},
"[<#email>]<@2>": {
"&": "stillalice@example.org"
},
"[<#email>]<$t>": {
"&": "2010-09-20T10:11:12Z"
}
}
}</programlisting>Note
that in this example the order in the collection is mutable because the addresses of the
ordered member instances do not include the immutability symbol. Ordering may be made
immutable by adding the symbol, as shown below.
<programlisting>{
"=example": {
"[<#email>]<@!~0>": {
"&": "alice@example.com"
},
"[<#email>]<@!~1>": {
"&": "alice.roth@example.net"
},
"[<#email>]<@!~2>": {
"&": "stillalice@example.org"
},
"[<#email>]<$t>": {
"&": "2010-09-20T10:11:12Z"
}
}
}</programlisting>In
some cases, an XDI authority may wish to combine both mutable ordering and immutable
addressing within the same collection—for example, where the order of preference is
mutable but a reference to a specific unordered member of the collection will be
immutable. In the XDI REAL model, the advantages of both can be combined in the same
collection using $ref relations (see Equivalence Relations). This is called the
ordered/unordered reference pattern. An example using email address attributes is shown
below (with UUIDs shortened for readability):
<programlisting>{
"=example": {
"[<#email>]<@~0>": {
"/$ref": [
"=example[<#email>]<*!:uuid:x-1>"
]
},
"[<#email>]<@~1>": {
"/$ref": [
"=example[<#email>]<*!:uuid:x-2>"
]
},
"[<#email>]<@~2>": {
"/$ref": [
"=example[<#email>]<*!:uuid:x-3>"
]
},
"[<#email>]<*!:uuid:x-1>": {
"&": "alice@example.com"
},
"[<#email>]<*!:uuid:x-2>": {
"&": "alice.roth@example.net"
},
"[<#email>]<*!:uuid:x-3>": {
"&": "stillalice@example.org"
},
"[<#email>]<$t>": {
"&": "2010-09-20T10:11:12Z"
}
}
}</programlisting>A
context node that is not explicitly a collection is a singleton, i.e., a single instance
of that context node type. Singletons and collections in XDI are analogous to singular
and plural nouns in English, e.g., “passport” and “passports”. The following example
shows the same three email address attribute values as in the previous example, only
each one is expressed as an <#email> singleton in a different context:
<programlisting>{
"=example": {
"<#email>": {
"&": "alice#example.com"
},
"<#home><#email>": {
"&": "alice.roth@example.net"
},
"<#work><#email>": {
"&": "stillalice@example.org"
}
}
}</programlisting>By
definition an attribute singleton may have only one literal value, whereas an attribute
collection may contain multiple values. Again, the advantages of both can be combined in
the same context using $ref relations. This is called the singleton/collection reference
pattern. An example using email address attributes is shown below (with UUIDs shortened
for readability):
<programlisting>{
"=example": {
"<#email>": {
"/$ref": [
"=example[<#email>]<*!:uuid:x-1>"
]
},
"<#home><#email>": {
"/$ref": [
"=example[<#email>]<*!:uuid:x-2>"
]
},
"<#work><#email>": {
"/$ref": [
"=example[<#email>]<*!:uuid:x-3>"
]
},
"[<#email>]<*!:uuid:x-1>": {
"&": "alice@example.com"
},
"[<#email>]<*!:uuid:x-2>": {
"&": "alice.roth@example.net"
},
"[<#email>]<*!:uuid:x-3>": {
"&": "stillalice@example.org"
},
"[<#email>]<$t>": {
"&": "2010-09-20T10:11:12Z"
}
}
}</programlisting></para>
</section>
<section>
<title>Definitions | |</title>
<para>XML has schemas; RDF has ontologies; XDI has <glossterm>dictionaries</glossterm>. XDI
uses the term “dictionary” for XDI ontology definitions because an XDI ontology term may
be reused in many different XDI contexts just like a natural language word may be reused
in many different linguistic contexts.</para>
<para>As with a natural language dictionary, a subject node in an XDI dictionary is called a
<glossterm>definition</glossterm>. Each XDI definition is the subject of one or more
definition statements. The XDI identifier of a definition context node MUST be enclosed
with pipe symbols <code>| |</code>.</para>
<para>Definitions only apply to XDI entities or attributes. Certain definition statement
types apply to each. For example, only an attribute definition may define the datatype
of a literal value.</para>
<para>The standard attributes and relations for XDI definition statements are defined in the
XDI Dictionary 1.0 specification. These include the same basic ontological building
blocks as in RDFS <xref linkend="rdf-schema"/> and OWL <xref linkend="owl"/>,
e.g.:</para>
<itemizedlist>
<listitem>
<para>types</para>
</listitem>
<listitem>
<para>subtypes</para>
</listitem>
<listitem>
<para>supertypes</para>
</listitem>
<listitem>
<para>entities (for roots)</para>
</listitem>
<listitem>
<para>subentities (for entities)</para>
</listitem>
<listitem>
<para>superentities (for entities and attributes)</para>
</listitem>
<listitem>
<para>attributes (for roots and entities)</para>
</listitem>
<listitem>
<para>subattributes (for attributes)</para>
</listitem>
<listitem>
<para>superattributes (for attributes)</para>
</listitem>
<listitem>
<para>datatypes (for literals)</para>
</listitem>
<listitem>
<para>incoming relations (range)</para>
</listitem>
<listitem>
<para>outgoing relations (domain)</para>
</listitem>
<listitem>
<para>cardinality</para>
</listitem>
</itemizedlist>
<para>Following is an example generic dictionary definition illustrating a number of common
dictionary statement types (in order: entity type, outgoing relations, subentities and
attributes, cardinality, and attribute types).
<programlisting>{
"|#car|": {
"/$is#": [
"|#vehicle|"
],
"(/)": [
"|#owner|",
"|#driver|",
"|#insurer|"
],
"//": [
"|#engine|",
"|#door|",
"|<#model>|",
"|<$year>|"
]
},
"|#car||#engine|": {
"<$n>": {
"&": "1"
}
},
"|#car||#door|": {
"<$n>": {
"&": "2-4"
}
},
"|#car||<#model>|": {
"$is#": [
"|<$string>|"
]
},
"|#car||<#year>|": {
"$is#": [
"|<$number>|"
]
}
}</programlisting>Using
contextual statements, XDI dictionaries can also define superentities and
superattributes. Following is an example of defining superentities for a
<code>#car</code>:
<programlisting>{
"|#car|": {
"/$is()": [
"|#sports|",
"|#race|",
"|#economy|",
"|#luxury|"
]
}
}</programlisting>These
dictionary statements define the following specializations of the entity
<code>#car</code>:
<programlisting>#sports#car #race#car #economy#car #luxury#car</programlisting>The same
can be done for attributes:
<programlisting>{
"|<#email>|": {
"/$is()": [
"|<#home>|",
"|<#work>|",
"|<#school>|",
"|<#priority>|"
]
}
}</programlisting>These
dictionary statements define the following specializations of the attribute
<code><#email></code>:
<programlisting>#home#email #work#email #school#email #priority#email</programlisting>Not
all XDI dictionary definitions are generic, i.e., at the top level. The reason for the
“X” in XDI (“extensibility”) is that any XDI authority may define its own XDI vocabulary
in its own XDI namespace. To do this, the enclosing pipe <code>| |</code> syntax is used
with an XDI authority (personal or grooup) identifier to define a <glossterm>dictionary
space</glossterm>. Following is an example of the <code><#email></code> attribute
being specialized by the group <code>+(https://xdi.org/)</code> in its own dictionary
space:
<programlisting>{
"|<+(https://xdi.org/)>||<#email>|": {
"/$is#": [
"|<$string>|"
]
},
"|<+(https://xdi.org/)>||<#email>|<$xbnf>": {
"&": "1*( ALPHA / DIGIT ) %22@xdi.org%22"
}
}</programlisting>Note
that <code>$xbnf</code> is an XDI-addressable variant of BNF that will be defined in the
XDI Dictionary 1.0 specification. This specialized dictionary definition may now be used
in XDI statements by prefixing the <code><#email></code> attribute with the
<code>|+(https://xdi.org/)|</code> attribute dictionary space. For example:
<programlisting>{
"=example": {
"|<+(https://xdi.org/)>|<#email>": {
"&": "example@xdi.org"
}
}
}</programlisting>
In English the same type of specialization would be expressed by prefixing an entity or
attribute name with a proper noun. For example, the generic concept of an “email
address” could be specialized by calling it an “XDI.org email address”. </para>
</section>
<section>
<title>Variables { }</title>
<para>A variable is an XDI context node that represents a set of XDI context nodes that will
replace the variable context node when it is instantiated. Variables are needed in XDI
policies, queries, and other expressions that need to reference a set of XDI nodes that
meet specified parameters. The XDI identifier of a variable context node MUST be
enclosed with curly brackets <code>{ }</code>. </para>
<para>When instantiated, a variable is matched against a target graph. The matching rules
depend on the type of variable. All variables except the common variable MUST match at
least one arc to have a match. The common variable always has a match because it can
also match zero arcs. </para>
<section>
<title>The Common Variable</title>
<para>The common variable is the simplest of all XDI variables. Like the common root
node, it is empty, consisting of only a pair of curly brackets. By definition, the
common variable matches any subgraph rooted in the context node where the common
variable appears. The common variable MAY match any number of arcs, including zero.
For example, the following XDI operation will return the entire subgraph rooted in
<code>=example<#home></code>: </para>
<para><code>.../$get/=example<#home>{}</code>
</para>
</section>
<section>
<title>Typed Variables </title>
<para>A typed variable is a variable containing an XDI class identifier. The matching
rules for typed variables are: <orderedlist>
<listitem>
<para>A matching instance of a typed variable MUST be a member of the XDI
class identified by the variable.</para>
</listitem>
<listitem>
<para>By default, a matching instance MAY be at any depth in the subgraph
rooted on the typed variable. (To constrain the depth of matching
requires using a defined variable—see Defined Variables).</para>
</listitem>
<listitem>
<para>A typed variable containing a singleton class identifier MUST match
either a singleton instance of that class or a member instance of a
collection of that class.</para>
</listitem>
<listitem>
<para>A typed variable containing a collection class identifier MUST match
an instance of that collection class.</para>
</listitem>
</orderedlist> Examples: <table frame="none">
<title>Typed Variables</title>
<tgroup cols="2">
<colspec colnum="1" colname="col1" colwidth="1*" align="center"/>
<colspec colnum="2" colname="col2" colwidth="4.56*"/>
<tbody>
<row>
<entry><emphasis role="bold">Variable</emphasis></entry>
<entry><emphasis role="bold">Matches an instance
of</emphasis></entry>
</row>
<row>
<entry><code>{()}</code></entry>
<entry>A peer root node</entry>
</row>
<row>
<entry><code>{(/)}</code></entry>
<entry>An inner root node</entry>
</row>
<row>
<entry><code>{=}</code></entry>
<entry>A person </entry>
</row>
<row>
<entry><code>{+}</code></entry>
<entry>A group </entry>
</row>
<row>
<entry><code>{*}</code></entry>
<entry>A thing </entry>
</row>
<row>
<entry><code>{@}</code></entry>
<entry>An ordinal</entry>
</row>
<row>
<entry><code>{[]}</code></entry>
<entry>An entity collection</entry>
</row>
<row>
<entry><code>{<>}</code></entry>
<entry>An attribute</entry>
</row>
<row>
<entry><code>{[<>]}</code></entry>
<entry>An attribute collection</entry>
</row>
<row>
<entry><code>{<*>}</code></entry>
<entry>An attribute instance</entry>
</row>
<row>
<entry><code>{<@>}</code></entry>
<entry>An attribute ordinal</entry>
</row>
<row>
<entry><code>{$}</code></entry>
<entry>A reserved class</entry>
</row>
<row>
<entry><code>{#}</code></entry>
<entry>An unreserved class</entry>
</row>
<row>
<entry><code>{#vehicle}</code></entry>
<entry>A specific unreserved class—<code>#vehicle</code></entry>
</row>
<row>
<entry><code>{[$]}</code></entry>
<entry>A reserved entity collection</entry>
</row>
<row>
<entry><code>{[$to]}</code>
</entry>
<entry>A specific reserved entity
collection—<code>$to</code></entry>
</row>
<row>
<entry><code>{[#]}</code></entry>
<entry>An unreserved entity collection</entry>
</row>
<row>
<entry><code>{[#vehicle]}</code>
</entry>
<entry>A specific unreserved entity
collection—<code>$vehicle</code></entry>
</row>
<row>
<entry><code>{<$>}</code></entry>
<entry>A reserved attribute</entry>
</row>
<row>
<entry><code>{<$iri>}</code></entry>
<entry>A specific reserved attribute—<code>$iri</code></entry>
</row>
<row>
<entry><code>{<#>}</code></entry>
<entry>An unreserved attribute</entry>
</row>
<row>
<entry><code>{<#email>}</code></entry>
<entry>A specific unreserved attribute—<code>#email</code></entry>
</row>
<row>
<entry><code>{[<$>]}</code></entry>
<entry>A reserved attribute collection</entry>
</row>
<row>
<entry><code>{[<$iri>]}</code>
</entry>
<entry>A specific reserved attribute
collection—<code>$iri</code></entry>
</row>
<row>
<entry><code>{[<#>]}</code></entry>
<entry>An unreserved attribute collection</entry>
</row>
<row>
<entry><code>{[<#email>]}</code>
</entry>
<entry>A specific unreserved attribute
collection—<code>$email</code></entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
<section>
<title>Defined Variables</title>
<para>A defined variable is a variable that has additional constraints defined by a set
of XDI statements using XDI dictionary vocabulary. The syntax for defined variables
is the same as for typed variables except the class identifier uses XDI definition
syntax, i.e., is enclosed in pipe characters. Examples:
<programlisting>{|=|}
{|+|}
{|*|}
{|#vehicle|}
{|<$iri>|}
{|<#email>|}
</programlisting>Note
that the common variable may also serve as a defined variable by including a pair of
pipe characters inside the curly brackets, i.e.:
<programlisting>{||}</programlisting>In this case the defined variable itself
imposes no type constraint on the instance; all constraints will be defined by the
variable definition. </para>
<para>The location of the definition of a defined variable depends on the location of
the defined variable. <orderedlist>
<listitem>
<para>If the defined variable appears in an XDI subject, the definition MUST
appear in the same context as the defined variable. </para>
</listitem>
<listitem>
<para>If the defined variable appears in an XDI object, the definition MUST
appear in the same context as the defined variable within an inner graph
of that XDI statement.</para>
</listitem>
</orderedlist>The defined variable definition MUST be expressed using additional XDI
statements as defined in the XDI Dictionary specification. For example, in the
following XDI statement, the typed variable <code>{<#phone>}</code> will match
any instances of a phone number to any depth below <code>=example</code>.
<programlisting>.../$get/=example{<#phone>}</programlisting>To constrain: a) the
match to only one instance, and b) the maximum depth of matching nodes to three, use
the defined variable <code>{|<#phone>|}</code> with two definition statements in
an inner graph: <orderedlist>
<listitem>
<para>The first definition statement constrains the number of matches using
the XDI dictionary cardinality attribute <code><$n></code>.</para>
</listitem>
<listitem>
<para>The second definition statement constrains the depth of matches using
the XDI dictionary attribute <code><$depth></code>.</para>
</listitem>
</orderedlist>Example:
<programlisting>{
"...": {
"/$get": [
"=example{|<#phone>|}"
]
},
"(.../$get)": {
"=example": {
"|<#phone>|<$n>": {
"&": "1"
},
"|<#phone>|<$depth>": {
"&": "1-3"
}
}
}
}</programlisting>Note:
when there are more matches for a variable than a definition constraint allows, it
is up to the XDI endpoint (or the XDI authority for queried graph) to select the
matches.</para>
</section>
<section>
<title>Reserved Variables</title>
<para>Reserved variables are typed variables that use an XDI reserved class name
(keyword) and have a specified function in the XDI protocol. Examples:
<programlisting>{$to}
{$from}
{$do}</programlisting>Reserved variables are not
defined variables because their definitions are not expressed as a set of XDI
statements. Instead their function is specified in one or more XDI specifications,
e.g., XDI Messaging, XDI Policy, XDI Connection, etc. <xref
linkend="xdi-messaging-1.0"/>
</para>
</section>
<section>
<title>Metavariables</title>
<para>Variables are commonly used in XDI templates— XDI subgraphs used as the model for
creating other XDI subgraphs. When an XDI template is instantiated, the variables it
contains are replaced with a valid instance of each variable. </para>
<para>In some cases, an XDI template must contain a variable whose instantiation will be
another variable. To enable this, XDI supports metavariables—one variable that
contains another. Metavariables are expressed with a double pair of curly brackets.
The outer pair represents the containing variable; the inner pair represents the
metavariable. Following is an example of a reserved metavariable:
<programlisting>{{$from}}</programlisting> To avoid recursion, variables may only be
nested one level deep.</para>
</section>
<section>
<title>The Literal Variable</title>
<para>XDI templates may need a variable to be instantiated with a literal value. This is
called a literal variable and is expressed using the XDI literal symbol:
<code>{&}</code>. </para>
<para>The literal variable MUST only be used as an XDI predicate. The XDI object of this
predicate MUST be an attribute variable. When instantiated, the attribute variable
MUST be instantiated with a valid attribute value. </para>
<para>Following is an example of an XDI template that uses a literal variable to specify
that a minimum age value is required when the template is instantiated.
<programlisting>{
"{{$to}}": {
"<#minimum><#age>": {
"/{&}": [
"{<#age>}"
]
}
}
}</programlisting>
Following is an example instantiation of this template.
<programlisting>{
"{$to}": {
"<#minimum><#age>": {
"&": 13
}
}
}</programlisting></para>
</section>
</section>
<section>
<title>Core Relations</title>
<para>This section defines the set of XDI relations that express standard relationship types
in a semantic graph. These together with the XDI ABNF rules define the universal grammar
of XDI. As shown in thetable below, many of the core relations correspond to the basic
types of relationships defined in UML <xref linkend="uml"/> and other object modeling
languages.
</para>
<para>
<table frame="none">
<title>Summary of Core Relations</title>
<tgroup cols="6" align="center">
<colspec colname="c1" colnum="1" colwidth="2.4*"/>
<colspec colname="c2" colnum="2" colwidth="3.04*"/>
<colspec colname="c3" colnum="3" colwidth="5.31*"/>
<colspec colname="c4" colnum="4" colwidth="2.62*"/>
<colspec colname="c5" colnum="5" colwidth="1.17*"/>
<colspec colname="c6" colnum="6" colwidth="1*"/>
<thead>
<row>
<entry>Category</entry>
<entry>Relationship </entry>
<entry>Expresses</entry>
<entry>Relation name</entry>
<entry>Predicate</entry>
<entry>Inverse</entry>
</row>
</thead>
<tbody>
<row>
<entry morerows="2">Equivalence</entry>
<entry>Transitive equivalence</entry>
<entry>Logical union of subject and object nodes</entry>
<entry>Identity relation</entry>
<entry>/$is/</entry>
<entry>/$is/</entry>
</row>
<row>
<entry>Visible canonical equivalence</entry>
<entry>Transpose subject node onto object node</entry>
<entry>Reference relation</entry>
<entry>/$ref/</entry>
<entry>/$is$ref/</entry>
</row>
<row>
<entry>Hidden canonical equivalence</entry>
<entry>Transpose object node onto subject node</entry>
<entry>Replacement relation</entry>
<entry>/$rep/</entry>
<entry>/$is$rep/</entry>
</row>
<row>
<entry>Hypernym-hyponym; supertype-subtype; superclass-subclass</entry>
<entry>Subsumption; is-a, type-of</entry>
<entry>Taxonomic hierarchy; inheritance</entry>
<entry>Type relation (between classes)</entry>
<entry morerows="1">/#/</entry>
<entry morerows="1">/$is#/</entry>
</row>
<row>
<entry>Class-instance; concept-object; type-token</entry>
<entry>Instantiation; instance-of</entry>
<entry>Instance belongs to a class</entry>
<entry>Type relation (between class and instance)</entry>
</row>
<row>
<entry morerows="2">Holonym-meronym</entry>
<entry>Aggregation; has-a</entry>
<entry>Possession without ownership</entry>
<entry>Aggregation relation</entry>
<entry>/$has/</entry>
<entry>/$is$has/</entry>
</row>
<row>
<entry>Composition; part-of</entry>
<entry>Possession with ownership</entry>
<entry>Contextual relation</entry>
<entry morerows="1">//</entry>
<entry morerows="1">/$is()/</entry>
</row>
<row>
<entry>Containment; member-of</entry>
<entry>Set membership</entry>
<entry>Collection relation</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<section>
<title>Equivalence Relations</title>
<para>The same resource may be represented by multiple context nodes within an XDI
graph. The XDI graph model provides two ways such equivalence may be asserted: <orderedlist>
<listitem>
<para>Equivalent identifiers may be used in different XDI contexts.</para>
</listitem>
<listitem>
<para>Equivalence statements may be made between different XDI
contexts.</para>
</listitem>
</orderedlist> Equivalence statements are made using using three types of
equivalence relations: <orderedlist>
<listitem>
<para>An identity relation asserts that two context nodes represent the same
logical resource and that neither context is canonical. In this case a
complete description of the resource requires a union of both subgraphs.
</para>
</listitem>
<listitem>
<para>A reference relation asserts that two context nodes represent the same
logical resource and the object node is canonical. In this case only the
object node may contain a subgraph describing the resource. </para>
</listitem>
<listitem>
<para>A replacement relation is the same as a reference relation except that
XDI address of the object node is replaced by the XDI address of the
subject node. In this case it will appear as if the subject node is
canonical, i.e., the object subgraph will appear as if it was the
subject subgraph, and the replacement relation will be invisible to a
requestor.</para>
</listitem>
</orderedlist></para>
<section>
<title>Equivalent Identifiers </title>
<para>The first way equivalence may be established between two context nodes is by
using the same absolute XDI identifier to identify the final arc in the context
path. If two XDI context node addresses terminate in the same absolute XDI
identifier, those XDI addresses MUST represent the same logical resource in
different contexts. The two nodes MAY also have an explicit equivalence
relation, but such a relation is not required to establish equivalence. </para>
<para>Absolute XDI identifiers are defined in <emphasis>Absolute and Relative
Identifiers</emphasis> section.</para>
<para>Following is an example of the same natural person represented by the same
absolute XDI name <code>=alice</code> in three different contexts (the common
root context and two group contexts).
<programlisting>{
"=alice": {
"<#email>": {
"&": "alice@example.name"
}
},
"+example-company=alice": {
"<#email>": {
"&": "asmith@example-company.com"
}
},
"+example-club=alice": {
"<#email>": {
"&": "alice.smith@example-club.com"
}
}
} </programlisting></para>
<para>Since XDI names are mutable (reassignable), immutable references require XDI
numbers. Here is the same example using XDI numbers in the form of UUIDs.
<programlisting>{
"=!:uuid:33ad7beb-1abc-4a26-b892-466df4379a51": {
"<#email>": {
"&": "alice@example.name"
}
},
"+!:uuid:f336a645-f5a9-41b7-ab80-ace41a8f69c2=!:uuid:33ad7beb-1abc-4a26-b892-466df4379a51": {
"<#email>": {
"&": "asmith@example-company.com"
}
},
"+!uuid:1c958708-d5aa-4213-a6a9-73dd423502b3=!:uuid:33ad7beb-1abc-4a26-b892-466df4379a51": {
"<#email>": {
"&": "alice.smith@example-club.com"
}
}
} </programlisting></para>
</section>
<section>
<title>Identity Relations ($is)</title>
<para>It may not be possible or desirable to use the same absolute XDI identifier
for the same resource in different XDI contexts. In this case the same type of
equivalence MAY be established using an identity relation. An identity relation
MUST be expressed using the XDI predicate <code>$is</code>. </para>
<para>Unlike all other XDI predicates, there is no inverse form—<code>$is</code> is
its own inverse. See <emphasis>Inverse Relations</emphasis>. </para>
<para>A <code>$is</code> assertion of equivalence is reflexive, symmetric and
transitive. It is not canonical, meaning that both the subject node and object
node MAY have their own subgraphs without restriction. This means a full
description of the described resource requires a union of both subgraphs. </para>
<para>A <code>$is</code> statement does not have any special XDI processing rules.
Therefore if an XDI endpoint returns a <code>$is</code> statement, it is the
requestor’s responsibility to determine if it needs to request the subgraph
identified by the object of that statement. </para>
<para>Following are two examples of <code>$is</code> identity relations. The first
asserts equivalence between two XDI names—a rooted absolute person name and a
nested relative personal name (in the context of a rooted absolute group name).
<programlisting>{
"=alice": {
"/$is": [
"+example.club=~alice.smith"
]
}
} </programlisting>The
second asserts equivalence between two XDI numbers (in the form of UUIDs)—a
rooted absolute person number and a nested absolute person number (in the
context of a rooted absolute group
number).<programlisting>{
"=!:uuid:33ad7beb-1abc-4a26-b892-466df4379a51": {
"/$is": [
"+!:uuid:1c958708-d5aa-4213-a6a9-73dd423502b3=!:uuid:8ded2f7e-afb4-4494-9918-0fecf38f80d5"
]
}
}</programlisting></para>
<section>
<title>Replacement Relations ($rep)</title>
<para>A replacement relation is identical to a reference relation except for the
XDI addressing rules. With a reference relation, the XDI address of the
object node is canonical—the <code>$ref</code> relation on the subject node
“redirects” to the object node. With a replacement relation, the XDI address
of the subject node is canonical, and the subgraph of the object node is
logically transposed onto the subject node. The XDI address of the object
node is never revealed—nor is the replacement relation. It is only visible
to the XDI authority for the graph. A replacement relation MUST be expressed
using the XDI predicate <code>$rep</code>. An inverse replacement relation
MUST be expressed with the XDI predicate <code>$is$rep</code>. See Inverse
Relations. </para>
<para>A <code>$rep</code> assertion of equivalence is irreflexive, asymmetric
and transitive. Because it is canonical, a context node described by a
<code>$rep</code> relation MUST be the subject of exactly one
<code>$rep</code> statement and MUST NOT be the subject of any other XDI
statements. </para>
<para>An inverse replacement relation is not canonical, so a context node
described by an <code>$is$rep</code> relation MAY be the subject of more
than one <code>$is$rep</code> statement and MAY contain its own subgraph. </para>
<para>When a <code>$rep</code> relation is reached while traversing an XDI
address, the <code>$rep</code> relation MUST be followed to the object node,
and traversal of the XDI address MUST continue from the object node. When an
XDI operation requests a subgraph containing a <code>$rep</code> relation,
the $rep relation MUST NOT be included in the returned subgraph. Instead the
object’s subgraph MUST be transposed to become the subject’s subgraph. </para>
<para>Replacement relations are fundamental to Privacy by Design <xref
linkend="pbd"/> [http://privacybydesign.ca/]. In particular,
<code>$rep</code> relations enable XDI authorities to publish pseudonyms
in order to control correlation between different XDI contexts. Following is
an example of a private XDI number used as a pseudonym to share a person’s
age using a $rep relation without revealing the individual’s public XDI
number. See <emphasis>Public and Private
Identifiers</emphasis>.<programlisting>{
"=!:uuid:33ad7beb-1abc-4a26-b892-466df4379a51": {
"<#age>": {
"/$rep": [
"+!:uuid:1c958708-d5aa-4213-a6a9-73dd423502b3<#age>"
]
}
},
"+!:uuid:1c958708-d5aa-4213-a6a9-73dd423502b3": {
"<#name>": {
"&": "Alice Smith"
},
"<#email>": {
"&": "alice@example.com"
},
"<#age>": {
"&": 33
}
}
}</programlisting>If
the following XDI $get request was performed on the graph above: </para>
<para><code>.../$get/=!:uuid:33ad7beb-1abc-4a26-b892-466df4379a51<#age></code>
</para>
<para>Then the following XDI graph would be
returned:<programlisting>{
"=!:uuid:33ad7beb-1abc-4a26-b892-466df4379a51": {
"<#age>": {
"&": 33
}
}
}</programlisting></para>
</section>
</section>
<section>
<title>Equivalence and Directed Graph Cycles </title>
<para>The contextual arcs in an XDI graph form a rooted tree. To ensure
deterministic traversal, this rooted tree must be
<glossterm>acyclic</glossterm>—it cannot allow a chain of contextual arcs to
loop around in a circle, i.e., that start at one node and end up back at that
same node. In graph theory, such a loop is called a
<glossterm>cycle</glossterm>. </para>
<para>Cycles would not be a problem if an XDI rooted tree consisted of only
contextual arcs where all the labels were relative (like DNS). However if
either: a) equivalent identifiers are used for nodes within the rooted tree, or
b) equivalence relations are added between nodes in the rooted tree, then it
becomes possible to form a cycle. Therefore, if an XDI agent or an XDI endpoint
adds an equivalent identifier or an equivalence statement to an XDI graph, it
MUST NOT create a cycle.</para>
</section>
<section>
<title>Equivalence of Context Types and Roles </title>
<para>For two context nodes to be equivalent, they MUST have the same context type
and role. For example, if two context nodes represent different XDI names for
the same person, both must be person entity nodes. If two context nodes
represent the same email address in different contexts, both must be attributes.
If two context nodes represent synonyms in a dictionary, both must be
definitions. </para>
</section>
<section>
<title>Reference Relations ($ref)</title>
<para>In contrast to identity relations, which establish the equivalence of two
context nodes where neither is canonical, a reference relation establishes the
equivalence of two context nodes where the XDI address for the object node is
canonical. In this case only the object node may contain a subgraph—the subject
node may only contain a reference to the object node. </para>
<para>A reference relation MUST be expressed using the XDI predicate
<code>$ref</code>. An inverse reference relation MUST be expressed with the
XDI predicate <code>$is$ref</code>. See Inverse Relations.</para>
<para>A <code>$ref</code> assertion of equivalence is irreflexive, asymmetric and
transitive. Because it is canonical, a context node described by a $ref relation
MUST be the subject of exactly one $ref statement and MUST NOT be the subject of
any other XDI statements. </para>
<para>An inverse reference relation is not canonical, so a context node described by
an <code>$is$ref</code> relation MAY be the subject of more than one
<code>$is$ref</code> statement and MAY contain its own subgraph. When a
<code>$ref</code> relation is reached while traversing an XDI address, the
<code>$ref</code> relation MUST be followed to the object node, and
traversal of the XDI address MUST continue from the object node. By default,
when an XDI operation requests a subgraph containing a <code>$ref</code>
relation, both the <code>$ref</code> relation and the object subgraph will be
included in the returned subgraph. </para>
<para>Note: this behavior can be modified by an XDI messaging parameter as defined
in the XDI Messaging specification. </para>
<para>Reference relations are needed for one of the most common patterns in XDI
graphs: mapping a human-friendly mutable (reassignable) identifier (an XDI name)
to a machine-friendly immutable (persistent) identifier (an XDI number). This is
called the <glossterm>name/number reference pattern</glossterm>. The following
example shows a name/number <code>$ref</code> relation for both a person and a
group:
<programlisting>{
"=alice": {
"/$ref": [
"=!:uuid:33ad7beb-1abc-4a26-b892-466df4379a51"
]
},
"+example.club": {
"/$ref": [
"+!:uuid:1c958708-d5aa-4213-a6a9-73dd423502b3"
]
}
} </programlisting></para>
</section>
<section>
<title>Rules for Processing Equivalence Relations </title>
<para>Rules for processing of operations on XDI graphs are defined in the XDI
Messaging specification <xref linkend="xdi-messaging-1.0"/>. This includes rules
for processing of equivalence relations. For informative purposes, here is a
summary: <orderedlist>
<listitem>
<para>A standard XDI <code>/$get/</code> operation must return all
reference relations but must not return any replacement relations.
</para>
</listitem>
<listitem>
<para>If an XDI <code>/$get/</code> message specifies a
<code><$deref></code> parameter, the operation must process
all reference relations as if they were replacement relations. This
means: a) each <code>$ref</code> predicate in the result graph must
be replaced with a <code>$rep</code> predicate, and b) the resulting
statement must be processed as a replacement relation. Therefore the
XDI graph returned by this <code>/$get/</code> operation will not
contain any reference or replacement relations—they will all have
been dereferenced.</para>
</listitem>
<listitem>
<para>If a reference relation or replacement relation is included in the
processing of an XDI <code>$add</code>, <code>$set</code> or
<code>$del</code> operation, it must be processed according to
the standard rules for equivalence relations, and processing of the
operation must continue at the object of the statement. The final
target statement(s) to be added or deleted must be determined only
after all reference or replacement relations have been processed.
</para>
</listitem>
<listitem>
<para>If the target of an XDI operation is itself a reference relation
or replacement relation, that relation must not be processed.
Instead, the operation must apply directly to the <code>$ref</code>
or <code>$rep</code> statement.</para>
</listitem>
</orderedlist></para>
</section>
</section>
<section>
<title>Inverse Relations</title>
<para>Due to its semantic tree architecture, the inverse of any XDI predicate may be
expressed algorithmically by prefixing it with the <code>$is</code> identity
equivalence relation. If an XDI predicate is prefixed by $is, it MUST be interpreted
as expressing the inverse relation of the same XDI predicate without the prefix.
Examples:
<table frame="none">
<title>Inverting relations with $is</title>
<tgroup cols="3">
<colspec colname="c1" colnum="1" colwidth="1.0*" align="center"/>
<colspec colname="c2" colnum="2" colwidth="1.0*" align="center"/>
<colspec colname="c3" colnum="3" colwidth="1.0*" align="center"/>
<thead>
<row>
<entry>Subject</entry>
<entry>Predicate</entry>
<entry>Object</entry>
</row>
</thead>
<tbody>
<row>
<entry><code>=luke.skywalker</code></entry>
<entry><code>#father</code></entry>
<entry><code>=darth.vader</code></entry>
</row>
<row>
<entry><code>=darth.vader</code></entry>
<entry><code>$is#father</code></entry>
<entry><code>=luke.skywalker</code></entry>
</row>
<row>
<entry><code>[#vehicle]!*:uuid:x-1</code></entry>
<entry><code>#owner</code></entry>
<entry><code>=example</code></entry>
</row>
<row>
<entry><code>=example</code></entry>
<entry><code>$is#owner</code></entry>
<entry><code>[#vehicle]!*:uuid:x-1</code></entry>
</row>
<row>
<entry><code>=example.club</code></entry>
<entry><code>$ref</code></entry>
<entry><code>+!:uuid:x-2</code></entry>
</row>
<row>
<entry><code>+!:uuid:x-2</code></entry>
<entry><code>$is$ref</code></entry>
<entry><code>=example.club</code></entry>
</row>
</tbody>
</tgroup>
</table></para>
<para>In semantic terms, the <code>$is</code> prefix expresses that the subject of a
statement whose predicate includes the <code>$is</code> prefix is equivalent to the
object of the same statement made without the <code>$is</code> prefix. </para>
<para>A predicate that uses the <code>$is</code> prefix is called an <glossterm>inverse
predicate</glossterm>. A statement that uses an inverse relation is called an
<glossterm>inverse statement</glossterm>. A predicate that does not use the
<code>$is</code> prefix is called a <glossterm>direct predicate</glossterm>. A
statement that does not use an inverse relation is called a <glossterm>direct
statement</glossterm>. An inverse relation may be used to express the inverse of
any XDI statement except the <code>$is</code> identity equivalence relation itself
(which is its own inverse). This includes XDI contextual statements. However,
because the predicate of an XDI contextual statement is empty, an inverse contextual
statement MUST use the predicate <code>$is()</code>. The empty parentheses
encapsulate the empty predicate. </para>
<para>Inverse contextual statements are particularly useful in XDI graphs because they
provide a mechanism for discovering other contexts for a resource. For example, a
requestor who only has knowledge of <code>=alice</code> could query the following
XDI graph (assuming the requestor has permission) to discover that
<code>=alice</code> also exists in the <code>+example.company</code> and
<code>+example.club</code> contexts.
<programlisting>{
"=alice": {
"/$is()": [
"+example-company",
"+example-club"
],
"<#email>": {
"&": "alice@example.name"
}
},
"+example-company=alice": {
"<#email>": {
"&": "asmith@example-company.com"
}
},
"+example-club=alice": {
"<#email>": {
"&": "alice.smith@example-club.com"
}
}
} </programlisting></para>
</section>
<section>
<title>Type Relations (#)</title>
<para>The heart of ontologies is type relationships, i.e., defining subtypes
(subclasses) and supertypes (superclasses). In XDI, these relationships are
expressed using XDI type statements. Since the concept of “type” is already
represented in XDI as <code>#</code> (the context symbol for unreserved classes), an
XDI type relation MUST be expressed using the XDI predicate <code>#</code>. An
inverse type relation MUST be expressed with the XDI predicate <code>$is#</code>. </para>
<para>XDI type statements fall into two categories: <orderedlist>
<listitem>
<para><emphasis role="bold">Relationships between subclasses and
superclasses.</emphasis> These correspond to
<code>rdf:subClassOf</code> relations. </para>
</listitem>
<listitem>
<para><emphasis role="bold">Relationships between instances and
classes.</emphasis> These correspond to <code>rdf:type</code>
relations.</para>
</listitem>
</orderedlist>Since the context symbol for an XDI context already indicates whether
it is a class or an instance, the same XDI type relations can express either
category of type statement.</para>
<para>Examples of superclass-subclass relations:<table frame="none">
<title>Superclass-subclass relations</title>
<tgroup cols="3" align="center">
<colspec colname="c1" colnum="1" colwidth="3.27*"/>
<colspec colname="c2" colnum="2" colwidth="1*"/>
<colspec colname="c3" colnum="3" colwidth="3.2*"/>
<thead>
<row>
<entry>Subject</entry>
<entry>Predicate</entry>
<entry>Object</entry>
</row>
</thead>
<tbody>
<row>
<entry><code>#food</code></entry>
<entry><code>#</code></entry>
<entry><code>#fruit</code></entry>
</row>
<row>
<entry><code>#fruit</code></entry>
<entry><code>#</code></entry>
<entry><code>#apple</code></entry>
</row>
<row>
<entry><code>#fruit</code></entry>
<entry><code>#</code></entry>
<entry><code>#banana</code></entry>
</row>
<row>
<entry><code>#fruit</code></entry>
<entry><code>#</code></entry>
<entry><code>#pear</code></entry>
</row>
<row>
<entry><code><$string></code></entry>
<entry><code>#</code></entry>
<entry><code><#name></code></entry>
</row>
<row>
<entry><code><$string></code></entry>
<entry><code>#</code></entry>
<entry><code><#email></code></entry>
</row>
</tbody>
</tgroup>
</table> Examples of subclass-superclass relations:<table frame="none">
<title>Subclass-superclass relations</title>
<tgroup cols="3" align="center">
<colspec colname="c3" colnum="1" colwidth="3.41*"/>
<colspec colname="c2" colnum="2" colwidth="1*"/>
<colspec colname="c1" colnum="3" colwidth="3.43*"/>
<thead>
<row>
<entry>Object</entry>
<entry>Predicate</entry>
<entry>Object</entry>
</row>
</thead>
<tbody>
<row>
<entry><code>#fruit</code></entry>
<entry><code>$is#</code></entry>
<entry><code>#food</code></entry>
</row>
<row>
<entry><code>#apple</code></entry>
<entry><code>$is#</code></entry>
<entry><code>#fruit</code></entry>
</row>
<row>
<entry><code>#banana</code></entry>
<entry><code>$is#</code></entry>
<entry><code>#fruit</code></entry>
</row>
<row>
<entry><code>#pear</code></entry>
<entry><code>$is#</code></entry>
<entry><code>#fruit</code></entry>
</row>
<row>
<entry><code><#name></code></entry>
<entry><code>$is#</code></entry>
<entry><code><$string></code></entry>
</row>
<row>
<entry><code><#email></code></entry>
<entry><code>$is#</code></entry>
<entry><code><$string></code></entry>
</row>
</tbody>
</tgroup>
</table></para>
<para>Examples of class-instance relations:<table frame="none">
<title>Class-instance relations</title>
<tgroup cols="3" align="center">
<colspec colname="c1" colnum="1" colwidth="3.27*"/>
<colspec colname="c2" colnum="2" colwidth="1*"/>
<colspec colname="c3" colnum="3" colwidth="3.2*"/>
<thead>
<row>
<entry>Subject</entry>
<entry>Predicate</entry>
<entry>Object</entry>
</row>
</thead>
<tbody>
<row>
<entry><code>#carpenter</code></entry>
<entry><code>#</code></entry>
<entry><code>=!:uuid:...</code></entry>
</row>
<row>
<entry><code>#church</code></entry>
<entry><code>#</code></entry>
<entry><code>+!:uuid:...</code></entry>
</row>
<row>
<entry><code>#car</code></entry>
<entry><code>#</code></entry>
<entry><code>*!:uuid:...</code></entry>
</row>
</tbody>
</tgroup>
</table> Examples of instance-class relations:<table frame="none">
<title>Instance-class relations</title>
<tgroup cols="3" align="center">
<colspec colname="c3" colnum="1" colwidth="3.41*"/>
<colspec colname="c2" colnum="2" colwidth="1*"/>
<colspec colname="c1" colnum="3" colwidth="3.43*"/>
<thead>
<row>
<entry>Object</entry>
<entry>Predicate</entry>
<entry>Object</entry>
</row>
</thead>
<tbody>
<row>
<entry><code>=!:uuid:...</code></entry>
<entry><code>$is#</code></entry>
<entry><code>#carpenter</code></entry>
</row>
<row>
<entry><code>+!:uuid:...</code></entry>
<entry><code>$is#</code></entry>
<entry><code>#church</code></entry>
</row>
<row>
<entry><code>*!:uuid:...</code></entry>
<entry><code>$is#</code></entry>
<entry><code>#car</code></entry>
</row>
</tbody>
</tgroup>
</table></para>
</section>
<section>
<title>Aggregation Relations ($has)</title>
<para>From an object modeling standpoint, XDI contextual relations are analogous to UML
<glossterm>composition</glossterm> (whole/part) relationships, where a composite
object both possesses and owns a set of component objects. The defining feature of
composition is ownership, i.e., when a composite object is destroyed, so are its
component objects. This is true of XDI contexts—if a context node is deleted, so are
all the context nodes in its subgraph. </para>
<para>UML also defines <glossterm>aggregation</glossterm> relationships, where an
aggregate object possesses but does not own a set of aggregated objects. The
defining feature of aggregation is lack of ownership, i.e., when an aggregate object
is destroyed, its aggregated objects are not. They continue to live independently of
the aggregate object. </para>
<para>This is often called a “has-a” relationship. For this reason, aggregation
relations in XDI are expressed using the XDI predicate <code>$has</code>. An inverse
aggregation relation MUST be expressed with the XDI predicate <code>$is$has</code>. </para>
<para>Compared to contextual relations, the defining feature of <code>$has</code>
relations in XDI is the same as in UML: if the subject of a <code>$has</code>
relation is deleted, the object of the relation is not affected (unless the object
happens to be in the subgraph of the subject). </para>
<para>A classic example is a university department: it has a set of professors, but if
the university department is closed, the professors still exist. The following
example shows both the university group entity and each of the professors’ person
entities as independent root-level entities aggregated via a <code>$has</code>
relation:</para>
<programlisting>{
"+example-university#magic#department": {
"/$has": [
"=example-prof-1",
"=example-prof-2",
"=example-prof-3"
]
},
"=example-prof-1": {
"<#name>": {
"&": "Albus Dumbledore"
}
},
"=example-prof-2": {
"<#name>": {
"&": "Minerva McGonagall"
}
},
"=example-prof-3": {
"<#name>": {
"&": "Severus Snape"
}
}
}</programlisting>
<para>Because the aggregated entities in this example are root-level, their attributes
(such as the <code><#name></code> attribute shown above) describe them
independently of any other context. XDI’s semantic tree architecture also enables
the aggregated entities to be described in the context of the aggregating entity.
This is called the <glossterm>contextual description pattern</glossterm>. The
advantage of contextual descriptions is that the attributes and relations of the
aggregated entity can be specific to the aggregating context. </para>
<para>For example, in the university professor scenario above, contextual descriptions
may be used to express the names and email addresses of the university professors in
the context of a specific university department. </para>
<programlisting>{
"+example-university#magic#department=example-prof-1": {
"<#name>": {
"&": "Headmaster Dumbledore"
},
"<#email>": {
"&": "adumbledore@magic.example.edu"
}
},
"+example-university#magic#department=example-prof-2": {
"<#name>": {
"&": "Professor McGonagall"
},
"<#email>": {
"&": "mmcgonagall@magic.example.edu"
}
},
"+example-university#magic#department=example-prof-3": {
"<#name>": {
"&": "Professor Snape"
},
"<#email>": {
"&": "ssnape@magic.example.edu"
}
}
}</programlisting>
<para>Contextual description of the members of a group is optional because it is only
needed when a group member has context-specific attributes or relations. When it is
required to express group membership in XDI, it MUST be expressed using a
<code>$has</code> relation between the group entity and each group member
entity. A group member entity MAY be either a person entity or another group entity,
i.e., groups may contain other groups. </para>
<para>In general, as with UML aggregation relationships, an XDI <code>$has</code>
aggregation relation does not constrain the type of entity that may be aggregated.
There is one exception. If the subject of a <code>$has</code> relation is a
collection, the object of this relation MUST be a member of the collection class.
This is called the <glossterm>virtual collection pattern</glossterm>. It applies
whenever members of a collection are independent entities that do not have
contextual descriptions. A typical example is a person’s music album
collection.</para>
<programlisting>{
"=example-person[#album]": {
"/$has": [
"+moody-blues[#album]*~every-good-boy-deserves-favour",
"+rolling-stones[#album]*~sticky-fingers",
"+derek-and-the-dominos[#album]*~layla"
]
},
"+moody-blues[#album]*~every-good-boy-deserves-favour": {
"<#release><#year>": {
"&": "1971"
}
},
"+rolling-stones[#album]*~sticky-fingers": {
"<#release><#year>": {
"&": "1971"
}
},
"+derek-and-the-dominos[#album]*~layla": {
"<#release><#year>": {
"&": "1971"
}
}
}</programlisting>
<para>Virtual collections are another example of how traditional database indexes may be
modeled in an XDI graph. </para>
<para><code>$has</code> aggregation relations are as useful in XDI as they are in UML.
They can model many forms of resource ownership and control. A specific application
is digital signatures: an XDI signature attribute can use a <code>$has</code>
relation to specify the set of XDI subgraphs included in the signature’s scope. The
use of <code>$has</code> relations with XDI digital signatures is specified in the
XDI Cryptographic Mechanisms specification <xref linkend="xdi-security-1.0"
/>.</para>
</section>
<section>
<title>Boolean Relations</title>
<para>To meet the design goal of describing authorization, policy, and rights
expression, XDI must be able to describe Boolean logic trees. These relations are
formally defined in the XDI Policy specification but are summarized below for
reference:<table frame="none">
<title>Boolean Relations</title>
<tgroup cols="2" align="center">
<colspec colname="c1" colnum="1" colwidth="1.0*"/>
<colspec colname="c2" colnum="2" colwidth="1.0*"/>
<thead>
<row>
<entry>Relation</entry>
<entry>Definition</entry>
</row>
</thead>
<tbody>
<row>
<entry>$true</entry>
<entry>Logical true statement</entry>
</row>
<row>
<entry>$false</entry>
<entry>Logical false statement</entry>
</row>
<row>
<entry>$and</entry>
<entry>Logical conjunction</entry>
</row>
<row>
<entry>$or</entry>
<entry>Logical disjunction</entry>
</row>
<row>
<entry>$not</entry>
<entry>Logical negation</entry>
</row>
<row>
<entry>$if</entry>
<entry>Logical branching</entry>
</row>
</tbody>
</tgroup>
</table></para>
</section>
<section>
<title>XDI Operations</title>
<para>The final category of core relations is the set of XDI predicates representing the
standard XDI protocol operations on XDI graphs. These are formally defined in the
XDI Messaging specification <xref linkend="xdi-messaging-1.0"/>, but are summarized
below for reference:<table frame="none">
<title>Boolean Relations</title>
<tgroup cols="2" align="center">
<colspec colname="c1" colnum="1" colwidth="1.0*"/>
<colspec colname="c2" colnum="2" colwidth="1.0*"/>
<thead>
<row>
<entry>Relation</entry>
<entry>Operation in Target Graph</entry>
</row>
</thead>
<tbody>
<row>
<entry>$get</entry>
<entry>Read statement</entry>
</row>
<row>
<entry>$set</entry>
<entry>Write statements</entry>
</row>
<row>
<entry>$add</entry>
<entry>Add new statements</entry>
</row>
<row>
<entry>$mod</entry>
<entry>Update value</entry>
</row>
<row>
<entry>$del</entry>
<entry>Delete statements</entry>
</row>
<row>
<entry>$connect</entry>
<entry>Instantiate a new XDI connection</entry>
</row>
<row>
<entry>$send</entry>
<entry>Send an XDI message</entry>
</row>
<row>
<entry>$push</entry>
<entry>Publish an XDI message to subscribers</entry>
</row>
<row>
<entry>$do</entry>
<entry>Authorize other operations</entry>
</row>
</tbody>
</tgroup>
</table></para>
</section>
<section>
<title>Nominalization</title>
<para>In linguistics, nominalization is the use of a verb as a noun. In XDI,
nominalization is the use of an XDI relation as an XDI context. The
<glossterm>nominalization pattern</glossterm> is needed in XDI for the same
reason as in human language: to embody relations so they may have their own
descriptions, attributes, and ordering. </para>
<para>A common case is when an XDI protocol operation needs a parameter. For example, in
the following XDI message, the XDI <code>$get</code> request in the first statement
is nominalized in order to add the <code><$deref></code> parameter in the second
statement.</para>
<programlisting>{
"=!:uuid:x-1[$msg]*!:uuid:x-2$do": {
"/$get": [
"=!:uuid:x-3<#email>"
]
},
"=!:uuid:x-1[$msg]*!:uuid:x-2$do$get": {
"<$deref>": {
"&": true
}
}
}</programlisting>
<para>Another common example involves the name/number reference pattern, where a mutable
human-friendly XDI name for an entity has a <code>$ref</code> equivalence relation
to an immutable XDI number for the entity. With this pattern it is easy to start
with the XDI name to look up the XDI number. However a relying party such as an
online merchant may frequently need to do the opposite, i.e., look up a
human-friendly XDI name from a persisted XDI number (e.g., to greet a returning
customer). </para>
<para>This is not as simple as following an inverse reference relation
(<code>$is$ref</code>) from the XDI number to the XDI name because the person
may have more than one XDI name that references his/her XDI number. </para>
<para>As shown below, the solution is to nominalize the <code>$is$ref</code> relation so
it may be treated as a subcontext in the person’s XDI graph. This new subcontext can
now express a canonical <code>ref</code> relation to the person’s preferred XDI
name. (Note that this preference is stored inside an inner graph describing the
merchant’s unique relationship with that particular customer.)</para>
<programlisting>{
"=!:uuid:x-1": {
"/$is$ref": [
"=alice",
"=alison",
"=alice.smith"
]
},
"+!:uuid:x-2": {
"/$is$ref": [
"+example.merchant"
]
},
"(+!:uuid:x-2/=!:uuid:x-1)": {
"=!:uuid:x-1$is$ref": {
"/$ref": [
"=alice.smith"
]
}
}
}</programlisting>
</section>
</section>
<section>
<title>ABNF</title>
<para>An XDI graph in <glossterm>statement format</glossterm>, where there is one XDI
statement for each arc in the graph, MUST be valid according to the ABNF rules in this
section. The <emphasis>Serialization</emphasis> section specifies the rules for
serializing a valid XDI graph in JSON.</para>
<para>Note that the ABNF rules alone do not express all requirements for an XDI graph to be
semantically valid. Additional rules for semantic validity are stated in text both
within this section and in other sections.</para>
<section>
<title>XDI Graph</title>
<programlisting>xdi-graph = *( xdi-statement / CRLF )
xdi-statement = contextual-statement / literal-statement / relational-statement</programlisting>
<para>In statement format, an XDI graph is a set of XDI statements consisting of a
sequence of Unicode characters. It is intended only for encoding in Unicode
encodings such as UTF-8 and UTF-16. Encoding in other encodings may result in
character corruption and unpredictable results.</para>
<para>All statements are one of three types: contexual, literal, or relational.</para>
<section>
<title>Contextual Statements</title>
<programlisting>contextual-statement = direct-contextual / inverse-contextual
direct-contextual = peer-root-direct / inner-root-direct / entity-direct / attr-direct
peer-root-direct = *peer-root "//" peer-root
inner-root-direct = root-address "//" inner-root
entity-direct = entity-address "//" entity
attr-direct = attr-address "//" attr
inverse-contextual = peer-root-inverse / inner-root-inverse / entity-inverse / attr-inverse
peer-root-inverse = peer-root "/$is()/" *peer-root
inner-root-inverse = inner-root "/$is()/" root-address
entity-inverse = entity "/$is()/" entity-address
attr-inverse = attr "/$is()/" attr-address</programlisting>
<para>Contextual statements define the branch nodes of a semantic tree. See
<emphasis>Contextual Arcs and Contextual Statements</emphasis>. A direct
contextual statement MAY have an inverse contextual statement. An inverse
contextual statement MUST have an direct contextual statement. Note that a
direct contextual statement MUST have exactly one XDI context node as an object,
and an inverse contextual statement MUST have exactly one XDI context node as a
subject.</para>
</section>
<section>
<title>Literal Statements</title>
<programlisting>literal-statement = entity-address 1*attr "/&/" value
literal-var-statement = entity-address 1*attr "/{&}/" value-variable
value-variable = "{" attr-class "}"</programlisting>
<para>Literal statements define the leaf nodes of a semantic tree. See
<emphasis>Literal Arcs and Literal Statements</emphasis>. An additional rule
applies to literal statements: the final node sequence before a literal
predicate MUST be one of two options:</para>
<para>
<orderedlist>
<listitem>
<para>An attribute class (<code>attr-class</code>).</para>
</listitem>
<listitem>
<para>An attribute collection (<code>attr-collection</code>) followed by
an attribute instance (<code>attr-instance</code>).</para>
</listitem>
</orderedlist>
</para>
</section>
<section>
<title>Relational Statements</title>
<programlisting>relational-statement = direct-relational / inverse-relational / relation-definition
direct-relational = xdi-address "/" 1*entity "/" xdi-address
inverse-relational = xdi-address "/$is" 1*entity "/" xdi-address</programlisting>
<para>Relational statements define relationships between context nodes in a semantic
tree. See <emphasis>Relational Arcs and Relational Statements</emphasis>. A
direct relational statement MAY have an inverse relational statement. An inverse
relational statement MAY have a direct relational statement. The existence of a
direct relational statement does not require the existence of its inverse, and
vice versa.</para>
</section>
<section>
<title>Relation Definition Statements</title>
<programlisting>relation-definition = direct-domain / inverse-domain / direct-range / inverse-range
direct-domain = direct-entity-domain / direct-attr-domain
direct-entity-domain = root-address 1*definition "/(/)/" root-address 1*definition
direct-attr-domain = root-address *definition 1*attr-definition "/(/)/" root-address 1*definition
inverse-domain = inverse-entity-domain / inverse-attr-domain
inverse-entity-domain = root-address 1*definition "/$is(/)/" root-address 1*definition
inverse-attr-domain = root-address 1*definition "/$is(/)/" root-address *definition 1*attr-definition
direct-range = direct-entity-range / direct-attr-range
direct-entity-range = root-address 1*definition "/(/)#/" root-address 1*definition
direct-attr-range = root-address 1*definition "/(/)#/" root-address *definition 1*attr-definition
inverse-range = inverse-entity-range / inverse-attr-range
inverse-entity-range = root-address 1*definition "/$is(/)#/" root-address 1*definition
inverse-attr-range = root-address *definition 1*attr-definition "/$is(/)#/" root-address 1*definition</programlisting>
<para>In XDI dictionaries, relational statements are used to define the domain and
range of XDI predicates. The empty inner graph <code>(/)</code> is the relation
definition predicate.</para>
</section>
</section>
<section>
<title>XDI Address</title>
<para>The arcs of an XDI address must follow this order: first any peer roots, then any
inner roots, then any entity arcs, then any attribute arcs, then the literal symbol
<code>&</code> (if the address identifies a literal node). If the address
terminates in the literal symbol, it MUST be preceded by either an attribute class
or the combination of an attribute collection and attribute instance as stated in
the Literal Statements section above. The required sequence is summarized in the
following ABNF rule, which however is not suitable for deterministic parsing because
of the preceding restriction, so we do not list it as normative.</para>
<para><code>xdi-address = *peer-root *inner-root *entity *attr [ attr "&"
]</code></para>
<para>XDI addresses are categorized for use in Contextual Statements:</para>
<programlisting>xdi-address = root-address / entity-address / attr-address / literal-address
root-address = *peer-root *inner-root
entity-address = root-address *entity
attr-address = entity-address *attr
literal-address = entity-address 1*attr "&"</programlisting>
</section>
<section>
<title>XDI Contexts</title>
<para>The rules in this section define the valid syntax for the three different primary
roles for XDI context nodes.</para>
<section>
<title>Root Contexts</title>
<programlisting>peer-root = peer-root-instance / peer-root-variable
peer-root-instance = "(" entity ")"
peer-root-variable = "{" peer-root-instance "}"
inner-root = inner-root-instance / inner-root-variable
inner-root-instance = inner-root-peer-root / inner-root-entity
inner-root-peer-root = "(" *peer-root "/" *entity ")"
inner-root-entity = "(" *entity "/" *entity ")"
inner-root-variable = "{" inner-root-instance "}"</programlisting>
<para>Both peer root context nodes and inner root context nodes are syntactically
distinguished by enclosing parentheses. Inner root context nodes contain the
subject and predicate of the XDI relational statement that defines the inner
root graph.</para>
</section>
<section>
<title>Entity Contexts</title>
<programlisting>entity = singleton / collection / definition / variable / meta-variable
singleton = instance / class
collection = "[" class "]"
definition = "|" ( singleton / collection ) "|"
variable = "{" ( singleton / collection / definition ) "}"
meta-variable = "{" variable "}"
instance = person / group / thing / ordinal
person = "=" [ "!" ] [ "~" ] id-string
group = "+" [ "!" ] [ "~" ] id-string
thing = "*" [ "!" ] [ "~" ] id-string
ordinal = "@" [ "!" ] [ "~" ] ordinal-string
class = reserved-class / unreserved-class / "$" / "#" / "=" / "+" / "*" / "@"
reserved-class = "$" xdi-name
unreserved-class = "#" [ "~" ] id-string</programlisting>
<para>Entity context nodes are either classes or instances. Class node identifiers
are always immutable, so they do not use the immutability symbol <code>!</code>.
Instance node identifiers may use both the immutability symbol and the
relativity symbol <code>~</code>.</para>
</section>
<section>
<title>Attribute Contexts</title>
<programlisting>attr = attr-singleton / attr-collection / attr-definition / attr-variable / attr-meta-variable
attr-singleton = attr-class / attr-instance
attr-collection = "[" attr-class "]"
attr-definition = "|" ( attr-singleton / attr-collection ) "|"
attr-variable = "{" ( attr-singleton / attr-collection / attr-definition ) "}"
attr-meta-variable = "{" attr-variable "}"
attr-class = "<" class ">"
attr-instance = "<" instance ">"</programlisting>
<para>The rules for attribute context nodes are very similar to the rules for entity
context nodes, with the addition of chevron brackets <code><</code> and
<code>></code> to indicate the attribute role.</para>
</section>
</section>
<section>
<title>XDI Identifiers</title>
<programlisting>id-string = xdi-name / xdi-scheme / encap-iri
ordinal-string = int / other-scheme</programlisting>
<para>For all XDI identifiers except ordinals, there are three basic identifier types:
names/numbers, schemes, and encapsulated IRIs. Ordinals are restricted to either
integers or another scheme with an associated specification for defining the order
of identifiers under that scheme. See <emphasis>XDI Schemes</emphasis>.</para>
<section>
<title>XDI Names and Numbers</title>
<programlisting>xdi-name = ID_Start *( ID_Continue / "_" / "-" / "." )
pct-encoded = "%" HEXDIG HEXDIG</programlisting>
<para>Note that the ABNF rule <code>xdi-name</code> covers both XDI names and XDI
numbers as defined in <emphasis>XDI Names and Numbers</emphasis>. </para>
<para>An XDI identifier MUST start with a character with the ID_START property
defined by the Unicode Identifier and Pattern Syntax <xref
linkend="unicode-tr31"/>. The characters following the ID_START character
MUST have the ID_CONTINUE property or be underscore <code>_</code>, hyphen
<code>-</code>, or period <code>.</code>.</para>
<para>For compatibility, users SHOULD define and enter XDI names and numbers using
lower case as a normalization to avoid interoperability problems with other
case-insensitive systems. See <emphasis>Normalization and
Comparison</emphasis>.</para>
</section>
<section>
<title>XDI Schemes</title>
<programlisting>xdi-scheme = uuid-scheme / cid-scheme / other-scheme
uuid-scheme = ":uuid:" 8HEXDIG "-" 4HEXDIG "-" 4HEXDIG "-" 2HEXDIG 2HEXDIG "-" 12HEXDIG
cid-scheme = ":cid-" 1*DIGIT ":" xdi-name
other-scheme = ":" ( lower-alpha / DIGIT ) *( lower-alpha / DIGIT / "_" / "-" / "." ) ":" xdi-name</programlisting>
<para>See <emphasis>XDI Schemes</emphasis>.</para>
</section>
<section>
<title>Encapsulated IRIs</title>
<para>The rules in this section have been simplified from <xref linkend="rfc3987"/>
as sufficient for XDI processors to recognize IRI syntax without intensive
verification.</para>
<programlisting>encap-iri = "(" absolute-iri ")"
absolute-iri = iri-scheme ":" 1*iri-char
iri-scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
iri-char = safe-char / %xA0-EFFFD / pct-encoded
safe-char = unreserved / reserved / gen-delims / safe-sub-delims
unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
reserved = gen-delims / safe-sub-delims
gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@"
safe-sub-delims = "!" / "$" / "&" / "(" / "*" / "+" / "," / ";" / "="</programlisting>
<para>Note that, in comparison to the <code>sub-delims</code> rule in RFC 3987, the
<code>safe-sub-delims</code> rule has removed:</para>
<orderedlist>
<listitem>
<para>The right parentheses character <code>)</code> in order to prevent it
from being interpreted as terminating the encapsulated IRI.</para>
</listitem>
<listitem>
<para>The single quote character <code>'</code> in order to prevent it from
being interpreted as terminating a JSON string.</para>
</listitem>
</orderedlist>
<para>Additional rules for this section:</para>
<orderedlist>
<listitem>
<para>XDI processors are NOT REQUIRED to check URIs for valid URI
syntax.</para>
</listitem>
<listitem>
<para>XDI parsers reading an URI (i.e. having found an open parenthesis
followed by a string matching uri-scheme followed by a colon) MAY simply
consider following characters part of the URI up to the close
parenthesis <code>)</code>.</para>
</listitem>
</orderedlist>
</section>
</section>
<section>
<title>Rules Inherited from JSON</title>
<para>The rules in this section covering JSON primitives are adapted from and equivalent
to those in <xref linkend="rfc7159"/>.</para>
<programlisting>value = "false" / "null" / "true" / object / array / number / string
object = begin-object [ member *( value-separator member ) ] end-object
member = string name-separator value
array = begin-array [ value *( value-separator value ) ] end-array
begin-array = ws %x5B ws ; [ left square bracket
begin-object = ws %x7B ws ; { left curly bracket
end-array = ws %x5D ws ; ] right square bracket
end-object = ws %x7D ws ; } right curly bracket
name-separator = ws %x3A ws ; : colon
value-separator = ws %x2C ws ; , comma
number = [ "-" ] int [ frac ] [ exp ]
exp = [ "e" / "E" ] [ "-" / "+" ] 1*DIGIT
frac = "." 1*DIGIT
int = "0" / ( %x31-39 *DIGIT ) ; no leading zeros
string = quotation-mark *char quotation-mark
char = unescaped / backslash ( quotation-mark / backslash /
"/" / "b" / "f" / "n" / "r" / "t" / "u" 4HEXDIG )
backslash = %x5C ; \ reverse solidus U+005C
quotation-mark = %x22 ; " quotation mark U+0022
unescaped = %x20-21 / %x23-5B / %x5D-10FFFF
ws = *( %x20 / %x09 / %x0A / %x0D ) </programlisting>
<para>Additional rules for this section:</para>
<para>
<orderedlist>
<listitem>
<para>The ABNF in RFC 7159 MUST be authoritative. The JSON ABNF given here
is just a readable equivalent given for the reader's convenience.</para>
</listitem>
<listitem>
<para>While RFC 7159 allows whitespace between JSON tokens to be space, tab,
CR, or LF, an XDI literal statement MUST be a single line, so CR or LF
are not allowed as whitespace in JSON values in XDI literal
statements.</para>
</listitem>
<listitem>
<para>XDI generators SHOULD produce JSON values without optional whitespace
between tokens.</para>
</listitem>
<listitem>
<para>For historical reasons, the <code>\uxxxx</code> escape sequence
expresses an UTF-16 code unit, implying a non-BMP character must be
escaped as two code units, and allowing illegal escape sequences such as
unpaired surrogates. This is not ideal, but following RFC 7159, these
rules are carried forward for backward compatibility. XDI processors MAY
reject input with invalid UTF-16 code sequences but are NOT REQUIRED to
check.</para>
</listitem>
</orderedlist>
</para>
</section>
<section>
<title>Rules Inherited from ABNF (RFC 2234)</title>
<para>These standard ASCII character classes are inherited from <xref linkend="rfc2234"
/>.</para>
<programlisting>ALPHA = %x41-5A / %x61-7A ; A-Z, a-z
DIGIT = %x30-39 ; 0-9
HEXDIG = %x30-39 / %x41-46 / %x61-66 ; 0-9, a-f, A-F
CRLF = %x0D / %x0A / ( %x0D %x0A )</programlisting>
</section>
</section>
<section>
<title>Serialization</title>
<para>In keeping with the design goal of serialization independence, an XDI graph may be
serialized in any specified format. JSON was selected as the first format due to its
compact structure and minimal overhead. The XDI TC may specify additional serialization
formats in the future, including XML (and potentially binary formats).</para>
<para>The JSON serialization format specified in this section was developed to strike a
balance between a <emphasis>completely flat serialization model</emphasis>—where every
XDI address in a graph has its own unique key in a single top-level JSON object—and a
<emphasis>completely nested serialization model</emphasis>—where every single node
in an XDI graph is represented by its own nested JSON object regardless of depth.</para>
<para>The XDI Technical Committee chose a mid-point of four levels of nested JSON objects
for the following reasons:</para>
<itemizedlist>
<listitem>
<para>It directly reflects the four-level XDI root-entity-attribute-literal (REAL)
graph model, which in turn reflects the RDF 1.1 quad model.</para>
</listitem>
<listitem>
<para>It also directly emulates the four components of the RDF 1.1 quad model: graph
name, subject, predicate, object.</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para>This format is easy to navigate and search with tools that support JSON Path
<xref linkend="jsonpath"/>.</para>
</listitem>
<listitem>
<para>If you know (or discover) the address of a specific XDI graph, you can easily
discover the associated XDI graph relations and XDI entities (assuming you have
permission). </para>
</listitem>
<listitem>
<para>If you know (or discover) the address of specific XDI entity within a graph,
you can easily discover the associated XDI entity relations and XDI attributes
(assuming you have permission). </para>
</listitem>
<listitem>
<para>If you know (or discover) the address of specific XDI attribute within a
graph, you can easily discover the associated XDI attribute relations and, if
present, the literal value of the attribute (assuming you have permission).
</para>
</listitem>
</itemizedlist>
<section>
<title> XDI JSON Format Serialization Rules </title>
<para>A valid XDI JSON document MUST be a valid JSON document according to <xref
linkend="rfc7159"/>". Prior to JSON serialization, an XDI graph MUST be valid
according to the rules in the ABNF section. </para>
<para>There are two sets of JSON serialization rules depending on whether an XDI agent
requests implied contextual statements (<code>implied=1</code>) or does not request
these statements (<code>implied=0</code>, which is the default). See Contextual Arcs
and Contextual Statements in <emphasis>The XDI Graph Model</emphasis> section. The
<code>implied=1</code> rules build on the <code>implied=0</code> rules.</para>
<para><emphasis role="bold">Definitions:</emphasis></para>
<orderedlist>
<listitem>
<para><glossterm>Solitary context node</glossterm> is a context node that is
only the object of a single contextual statement in the graph, and not the
subject or object of any other statements in the graph. Note that an inner
root node is <emphasis>never</emphasis> a solitary context node because it
is always be the object of a relational statement. </para>
</listitem>
<listitem>
<para><glossterm>Object-only node</glossterm> is a context node that is the
object of one or more relational statements in the graph, but not the
subject of any statements in the graph.</para>
</listitem>
</orderedlist>
<section>
<title> Rules When Implied Contextual Statements are Excluded (Implied=0)</title>
<section>
<title> Root Node Serialization Rules </title>
<orderedlist>
<listitem>
<para>The XDI common graph root MUST be serialized as the top-level JSON
object ("common graph object"). </para>
</listitem>
<listitem>
<para>To serialize a peer or inner graph root node in the common graph,
the XDI address of the graph root node MUST be a key string in the
common graph object ("graph root key"). </para>
</listitem>
<listitem>
<para>The JSON value of a graph root key MUST be a second-level nested
JSON object ("graph object"). </para>
</listitem>
<listitem>
<para>If a graph root node is a solitary context node, the graph object
MUST be empty. </para>
</listitem>
<listitem>
<para>To serialize an XDI graph root relation, the XDI address of the
relation MUST be a key string in the graph object ("root relation
key") prefixed with a forward slash <code>/</code>. </para>
</listitem>
<listitem>
<para>The JSON value of a root relation key MUST be an array of the XDI
addresses of the XDI object(s) of the relation. </para>
</listitem>
</orderedlist>
</section>
<section>
<title> Entity Node Serialization Rules </title>
<orderedlist>
<listitem>
<para>To serialize an XDI entity node inside a graph object (i.e., a
common graph object, peer graph object, or inner graph object), the
XDI address of the entity node MUST be a key string in the graph
object ("entity key"). </para>
</listitem>
<listitem>
<para>The JSON value of an entity key MUST be a nested JSON object
("entity object"). </para>
</listitem>
<listitem>
<para>If an entity node is a solitary context node, the entity object
MUST be empty. </para>
</listitem>
<listitem>
<para>To serialize an XDI entity relation, the XDI address of the
relation MUST be a key string in the entity object ("entity relation
key") prefixed with a forward slash <code>/</code>. </para>
</listitem>
<listitem>
<para>The JSON value of an entity relation key MUST be an array of the
XDI addresses of the XDI object(s) of the relation. </para>
</listitem>
</orderedlist>
</section>
<section>
<title> Attribute Node Serialization Rules </title>
<orderedlist>
<listitem>
<para>To serialize an XDI attribute node inside a graph object or entity
object, the XDI address of the attribute node MUST be a key string
in the graph object or entity object ("attribute key"). </para>
</listitem>
<listitem>
<para>The JSON value of an attribute key MUST be a nested JSON object
("attribute object"). </para>
</listitem>
<listitem>
<para>If an an attribute node is a solitary context node, the attribute
object MUST be empty.</para>
</listitem>
<listitem>
<para>To serialize an XDI attribute relation, the XDI address of the
relation MUST be a key string in the attribute object ("attribute
relation key") prefixed with a forward slash <code>/</code>.</para>
</listitem>
<listitem>
<para>The JSON value of an attribute relation key MUST be an array of
the XDI addresses of the XDI object(s) of the relation.</para>
</listitem>
</orderedlist>
</section>
<section>
<title> Literal Node Serialization Rules </title>
<orderedlist>
<listitem>
<para>To serialize an XDI literal node containing the value of an XDI
attribute, the key string in the attribute object MUST be
<code>&</code> (the "literal key").</para>
</listitem>
<listitem>
<para>The JSON value of the literal key MUST be the JSON value of the
XDI literal.</para>
</listitem>
</orderedlist>
</section>
<section>
<title> Common Variable Node Serialization Rule </title>
<orderedlist>
<listitem>
<para>If an XDI address includes a common variable, that variable MUST
be appended to the graph root key, entity key, or attribute key that
precedes it.</para>
</listitem>
</orderedlist>
</section>
</section>
<section>
<title> Rules When Implied Contextual Statements are Included (Implied=1)</title>
<para>These rules MUST be applied in addition to the rules in the previous
section.</para>
<orderedlist>
<listitem>
<para>The first-level subcontexts of every graph root node MUST be
serialized using the graph root relation <code>//</code>. </para>
</listitem>
<listitem>
<para>The first-level subcontexts of every entity node MUST be serialized
using the entity relation <code>//</code>. </para>
</listitem>
<listitem>
<para>The first-level subcontexts of every attribute node MUST be serialized
using the attribute relation <code>//</code>. </para>
</listitem>
<listitem>
<para>Every object-only context node MUST be serialized following the same
rules as for a solitary context nodes in the previous section.</para>
</listitem>
</orderedlist>
<para>Note that while the <code>implied=0</code> serialization is more verbose, it
has two properties that may be useful to thin clients who wish do navigation
directly on the returned JSON document.</para>
<orderedlist>
<listitem>
<para>There will be exactly one serialized XDI subject/predicate/object
triple (in the common graph) or context/subject/predicate/object quad
(in a peer or inner graph) for every arc in the XDI graph. This is the
serialization most directly comparable to an <xref
linkend="rdf-datasets"/>.</para>
<orderedlist>
<listitem>
<para>Every contextual statement will have the predicate
<code>//</code>.</para>
</listitem>
<listitem>
<para>Every relational statement will have a predicate that begins
with <code>/</code>.</para>
</listitem>
<listitem>
<para>Every literal statement will have the JSON object key string
<code>&</code>. </para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>There will be exactly one JSON object for every XDI context node in
the graph, including the outermost JSON object which represents the
common root context.</para>
</listitem>
</orderedlist>
</section>
</section>
<section>
<title> Readability Rules </title>
<para>For consistent readability, the following rules are RECOMMENDED.</para>
<orderedlist>
<listitem>
<para>At all context levels of an XDI graph, starting with the common root
level, XDI statements that are applicable in that context SHOULD appear in
the following order:</para>
<orderedlist>
<listitem>
<para>Implied contextual statements (when <code>implied=1</code>).
</para>
</listitem>
<listitem>
<para>Relational statements.</para>
</listitem>
<listitem>
<para>Literal statements. </para>
</listitem>
<listitem>
<para>Attribute statements. </para>
</listitem>
<listitem>
<para>Entity statements. </para>
</listitem>
<listitem>
<para>Graph root statements. </para>
</listitem>
</orderedlist>
</listitem>
<listitem>
<para>For a set of XDI statements of the same type at the same level, the JSON
objects SHOULD appear in alphabetical order according to the JSON object key
string. </para>
</listitem>
<listitem>
<para>In a JSON array of XDI addresses, the XDI address values SHOULD appear in
alphabetical order.</para>
</listitem>
</orderedlist>
</section>
<section>
<title> JSON Display Format Rules </title>
<para>JSON XDI format is easy enough to read that in most cases there is no need for a
separate display format. However there may be cases where either: a) the JSON
delimiters may be confusing to a non-technical audience, or b) vertical line space
is at a premium. For these situations, we define a simple display version of the
JSON XDI format.</para>
<orderedlist>
<listitem>
<para>First, serialize the graph in JSON XDI format as specified above using the
conventional JSON display formatting rules where each JSON object and array
appears on a new line and is indented one level. </para>
</listitem>
<listitem>
<para>Remove all JSON delimiters except those delimiting XDI literal values.
</para>
</listitem>
<listitem>
<para>Remove all blank lines. </para>
</listitem>
<listitem>
<para>Remove one level of indenting. </para>
</listitem>
<listitem>
<para>If a line needs to wrap, the wrapped line(s) MUST be indented to the same
number of tab stops as the starting line. </para>
</listitem>
<listitem>
<para>Any instance of the common root node (which is serialized in the JSON
format as the empty string <code>""</code>) MUST be replaced by a double
forward slash <code>//</code>.</para>
</listitem>
</orderedlist>
<para>Note about this format:</para>
<orderedlist>
<listitem>
<para>The left margin represents the common root node; all subroots, entities,
attributes, and relations of the common root node will be aligned with the
left margin. </para>
</listitem>
<listitem>
<para>All entities, attributes, and relations of a subroot node will be indented
one tab stop. </para>
</listitem>
<listitem>
<para>All attributes and relations of an entity will be indented one tab stop
more than the entity. </para>
</listitem>
<listitem>
<para>All relations of an attribute will be indented one tab stop more than the
attribute. </para>
</listitem>
<listitem>
<para>The ampersand <code>&</code> representing the literal value of an
attribute will be indented one tab stop more than the attribute. </para>
</listitem>
<listitem>
<para>The JSON value of the attribute will follow the ampersand on the same
line, indented one tab stop more than the ampersand.</para>
</listitem>
</orderedlist>
</section>
<section>
<title> Examples </title>
<para>Note: in these examples, UUIDs are shown in a truncated format for
readability.</para>
<section>
<title> Example Where Implied Contextual Statements are Excluded (Implied=0)</title>
<programlisting>{
"/$is$ref": [
"(=!:uuid:x-alice)"
],
"<$uri>": {
"&": "https://xdi.example.com/=!:uuid:x-alice";
},
"=!:uuid:x-alice": {
"/#friend": [
"=!:uuid:x-bob",
"=!:uuid:x-carol",
"(=!:uuid:x-alice/#friend)"
],
"/#spouse": [
"=!:uuid:x-david"
],
"[<#email>]<!0>": {
"&": "alice@example.com"
},
"[<#email>]<!1>": {
"&": "asmith@example.net"
},
"<#email>": {
"/$ref": [
"=!:uuid:x-alice[<#email>]<!0>"
]
},
"<#home><#email>": {
"/$ref": [
"=!:uuid:x-alice[<#email>]<!1>"
]
},
"<#work><#email>": {
"/$ref": [
"=!:uuid:x-alice[<#email>]<!1>"
]
}
},
"=!:uuid:x-alice#passport": {
"<#country>": {
"&": "USA"
},
"<#name>": {
"&": "Alice Smith"
},
"<#number>": {
"&": "1234567"
}
},
"(=!:uuid:x-alice)": {
"/$ref": [
""
]
},
"(=!:uuid:x-alice/#friend)": {
"+!:uuid:x-org#card$do": {
"/$get": [
"=!:uuid:x-alice<#home><#email>"
]
}
},
"(=!:uuid:x-alice/#friend)(+!:uuid:x-org#card$do$if/$true)": {
"{$from}": {
"/$is#friend": [
"=!:uuid:x-alice"
]
}
},
"(=!:uuid:x-bob)": {
"<$uri>": {
"&": "https://xdi.example.com/=!:uuid:x-bob/";
}
},
"(=!:uuid:x-carol)": {
"<$uri>": {
"&": "https://xdi.example.com/=!:uuid:x-carol/";
}
}
}</programlisting>
</section>
<section>
<title> Example Where Implied Contextual Statements are Included (Implied=1)</title>
<para>
<programlisting>{
"//": [
"<$uri>",
"=!:uuid:x-alice",
"=!:uuid:x-bob",
"=!:uuid:x-carol",
"=!:uuid:x-david",
"(=!:uuid:x-alice)",
"(=!:uuid:x-alice/#friend)",
"(=!:uuid:x-bob)",
"(=!:uuid:x-carol)"
],
"/$is$ref": [
"(=!:uuid:x-alice)"
],
"<$uri>": {
"&": "https://xdi.example.com/=!:uuid:x-alice";
},
"=!:uuid:x-alice": {
"//": [
"[<#email>]",
"<#email>",
"<#home>",
"<#work>",
"#passport"
],
"/#friend": [
"=!:uuid:x-bob",
"=!:uuid:x-carol",
"(=!:uuid:x-alice/#friend)"
],
"/#spouse": [
"=!:uuid:x-david"
],
"[<#email>]": {
"//": [
"<!0>",
"<!1>"
]
},
"[<#email>]<!0>": {
"&": "alice@example.com"
},
"[<#email>]<!1>": {
"&": "asmith@example.net"
},
"<#email>": {
"/$ref": [
"=!:uuid:x-alice[<#email>]<!0>"
]
},
"<#home>": {
"//": [
"<#email>]"
]
},
"<#home><#email>": {
"/$ref": [
"=!:uuid:x-alice[<#email>]<!1>"
]
},
"<#work>": {
"//": [
"<#email>]"
]
},
"<#work><#email>": {
"/$ref": [
"=!:uuid:x-alice[<#email>]<!1>"
]
}
},
"=!:uuid:x-alice#passport": {
"//": [
"<#country>",
"<#name>",
"<#number>"
],
"<#country>": {
"&": "USA"
},
"<#name>": {
"&": "Alice Smith"
},
"<#number>": {
"&": "1234567"
}
},
"=!:uuid:x-bob": {},
"=!:uuid:x-carol": {},
"=!:uuid:x-david": {},
"(=!:uuid:x-alice)": {
"/$ref": [
""
]
},
"(=!:uuid:x-alice/#friend)": {
"//": [
"+!:uuid:x-org#card$do",
"+!:uuid:x-org#card$do$if",
"(+!:uuid:x-org#card$do$if/$true)"
],
"+!:uuid:x-org#card$do": {
"/$get": [
"=!:uuid:x-alice<#home><#email>"
]
},
"+!:uuid:x-org#card$do$if": {
"/$true": [
"(=!:uuid:x-alice/#friend)(+!:uuid:x-org#card$do$if/$true)"
]
}
},
"(=!:uuid:x-alice/#friend)(+!:uuid:x-org#card$do$if/$true)": {
"//": [
"{$from}"
],
"{$from}": {
"/$is#friend": [
"=!:uuid:x-alice"
]
}
},
"(=!:uuid:x-bob)": {
"//": [
"<$uri>"
],
"<$uri>": {
"&": "https://xdi.example.com/=!:uuid:x-bob/";
}
},
"(=!:uuid:x-carol)": {
"//": [
"<$uri>"
],
"<$uri>": {
"&": "https://xdi.example.com/=!:uuid:x-bob/";
}
}
}</programlisting>
</para>
</section>
</section>
<section>
<title> Special Case Examples </title>
<para>This section provides examples of how to serialize the special cases involving
solitary context nodes, object-only context nodes, and inner roots. Each is shown
both with and without implied contextual statements.</para>
<section>
<title> Solitary Context Nodes </title>
<section>
<title>Implied=0</title>
<para> Statement format:</para>
<programlisting>//=a
//=b</programlisting>
<para>JSON format:</para>
<programlisting>{
"=a": {},
"=b": {}
}</programlisting>
</section>
<section>
<title> Implied=1 </title>
<para> Statement format:</para>
<programlisting>//=a
//=b</programlisting>
<para>JSON format:</para>
<programlisting>{
"//": [
"=a",
"=b"
],
"=a": {},
"=b": {}
}</programlisting>
</section>
</section>
<section>
<title> Object-Only Context Nodes </title>
<section>
<title>Implied=0</title>
<para> Statement format:</para>
<programlisting>=a/#friend/=b</programlisting>
<para>JSON format:</para>
<programlisting>{
"=a": {
"/#friend": [
"=b"
]
}
}</programlisting>
</section>
<section>
<title> Implied=1 </title>
<para> Statement format:</para>
<programlisting>//=a
//=b
=a/#friend/=b</programlisting>
<para>JSON format:</para>
<programlisting>{
"//": [
"=a",
"=b"
],
"=a": {
"/#friend": [
"=b"
]
},
"=b": {}
}</programlisting>
</section>
</section>
<section>
<title> Both Solitary and Object-Only Context Nodes </title>
<section>
<title>Implied=0</title>
<para>Statement format:</para>
<programlisting>=a/#friend/=b
//=c</programlisting>
<para>JSON format:</para>
<programlisting>{
"=a": {
"/#friend": [
"=b"
]
},
"=c": {}
} </programlisting>
</section>
<section>
<title> Implied=1 </title>
<para>Statement format:</para>
<programlisting>//=a
//=b
//=c
=a/#friend/=b</programlisting>
<para>JSON format:</para>
<programlisting>{
"//": [
"=a",
"=b",
"=c"
],
"=a": {
"/#friend": [
"=b"
]
},
"=b": {},
"=c": {}
}</programlisting>
</section>
</section>
<section>
<title> Non-Empty Inner Root </title>
<section>
<title>Implied=0</title>
<para>Statement format:</para>
<programlisting>(=a/#b)=x/#y/=z</programlisting>
<para>JSON format:</para>
<programlisting>{
"(=a/#b)": {
"=x": {
"/#y": [
"=z"
]
}
}
}</programlisting>
</section>
<section>
<title>Implied=1</title>
<para>Statement format:</para>
<programlisting>//=a
//=z
//(=a/#b)
=a/#b/(=a/#b)
(=a/#b)//=x
(=a/#b)=x/#y/=z</programlisting>
<para>JSON format:</para>
<programlisting>{
"//": [
"=a",
"=z",
"(=a/#b)"
],
"=a": {
"/#b": [
"(=a/#b)"
]
},
"=z": {},
"(=a/#b)": {
"//": [
"=x"
],
"=x": {
"/#y": [
"=z"
]
}
}
} </programlisting>
</section>
</section>
<section>
<title>Empty Inner Root </title>
<section>
<title>Implied=0 </title>
<para>Statement format:</para>
<programlisting>=a/#b/(=a/#b)</programlisting>
<para>JSON format:</para>
<programlisting>{
"=a": {
"/#b": [
"(=a/#b)"
]
}
}</programlisting>
</section>
<section>
<title>Implied=1 </title>
<para>Statement format:</para>
<programlisting>//=a
//(=a/#b)
=a/#b/(=a/#b)</programlisting>
<para>JSON format:</para>
<programlisting>{
"//": [
"=a",
"(=a/#b)"
],
"=a": {
"/#b": [
"(=a/#b)"
]
},
"(=a/#b)": {}
} </programlisting>
</section>
</section>
</section>
</section>
<section>
<title>XDI Addressing</title>
<para>The first design goal of XDI architecture is 100% addressability of all graph nodes.
This is accomplished via XDI’s semantic tree structure and formally defined in the ABNF
rules. The patterns and rules for addressing and traversing nodes within this semantic
tree structure are summarized in this section.</para>
<section>
<title>Semantic Tree Architecture</title>
<para>As summarized in the figure below from the <emphasis>Introduction</emphasis>, a
semantic tree is a hybrid between a semantic graph and a conventional directory
tree.</para>
<svg width="500" height="300" viewBox="0 0 500 150" version="1.1"
xmlns="http://www.w3.org/2000/svg";>
<ellipse cx="250" cy="70" rx="248" ry="140" stroke="black" stroke-width="2" fill="white"/>
<g transform="translate(130,0)">
<circle cx="0" cy="70" r="105" stroke="black" fill="white"/>
<text x="0" y="0" text-anchor="middle">Semantic Web:</text>
<text x="0" y="40" text-anchor="middle">Description Logic</text>
<text x="0" y="60" text-anchor="middle">Knowledge Representation</text>
<text x="0" y="80" text-anchor="middle">Machine Learning</text>
<text x="0" y="120" text-anchor="middle">RDF, OWL, JSON-LD</text>
</g>
<g transform="translate(360,0)">
<circle cx="0" cy="70" r="105" stroke="black" fill="white"/>
<text x="0" y="0" text-anchor="middle">Directory Tree:</text>
<text x="0" y="40" text-anchor="middle">Identity Management</text>
<text x="0" y="60" text-anchor="middle">Discovery, Access Control</text>
<text x="0" y="80" text-anchor="middle">Authentication, Authorization</text>
<text x="0" y="120" text-anchor="middle">X.500, LDAP, DNS</text>
<text x="0" y="140" text-anchor="middle">XACML, OAuth</text>
</g>
<text x="250" y="-40" text-anchor="middle">Semantic Tree:</text>
<text x="250" y="180" text-anchor="middle">XDI</text>
</svg>
<para>Like an RDF semantic graph, all arcs in an XDI graph are represented with
subject/predicate/object triples. Like a conventional X.500 directory tree,
hierarchical relationships in an XDI graph may be represented using contextual arcs
that form a rooted tree structure. This combination yields the identifier and
addressing features described in this section.</para>
<section>
<title>REAL Sequences</title>
<para>The first rule of XDI addressing within a semantic tree, enforced in the ABNF,
is that the sequence of XDI identifiers composing an XDI address MUST follow the
XDI REAL (Root-Entity-Attribute-Literal) sequence order. The following table
lists the sequence patterns that are valid per the ABNF.
<table frame="none">
<title>Valid REAL Sequences</title>
<tgroup cols="6" align="center">
<colspec colname="c1" colnum="1" colwidth="1.33*"/>
<colspec colname="c2" colnum="2" colwidth="1*"/>
<colspec colname="c3" colnum="3" colwidth="1.13*"/>
<colspec colname="c4" colnum="4" colwidth="1.76*"/>
<colspec colname="c5" colnum="5" colwidth="1.38*"/>
<colspec colname="newCol6" colnum="6" colwidth="8.11*"/>
<thead>
<row>
<entry>Pattern #</entry>
<entry>Root</entry>
<entry>Entity</entry>
<entry>Attribute</entry>
<entry>Literal</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>1</entry>
<entry>x</entry>
<entry>x</entry>
<entry>x</entry>
<entry>x</entry>
<entry><code>(+example-corp/#employee)=alice<#email>&</code></entry>
</row>
<row>
<entry>2</entry>
<entry>x</entry>
<entry>x</entry>
<entry>x</entry>
<entry/>
<entry><code>(+example-corp/#employee)=alice<#email></code></entry>
</row>
<row>
<entry>3</entry>
<entry>x</entry>
<entry>x</entry>
<entry/>
<entry/>
<entry><code>(+example-corp/#employee)=alice</code></entry>
</row>
<row>
<entry>4</entry>
<entry>x</entry>
<entry/>
<entry/>
<entry/>
<entry><code>(+example-corp/#employee)</code></entry>
</row>
<row>
<entry>5</entry>
<entry/>
<entry>x</entry>
<entry>x</entry>
<entry>x</entry>
<entry><code>=alice<#email>&</code></entry>
</row>
<row>
<entry>6</entry>
<entry/>
<entry>x</entry>
<entry>x</entry>
<entry/>
<entry><code>=alice<#email></code></entry>
</row>
<row>
<entry>7</entry>
<entry/>
<entry>x</entry>
<entry/>
<entry/>
<entry><code>=alice</code></entry>
</row>
<row>
<entry>8</entry>
<entry/>
<entry/>
<entry>x</entry>
<entry>x</entry>
<entry><code>$uri&</code></entry>
</row>
<row>
<entry>9</entry>
<entry/>
<entry/>
<entry>x</entry>
<entry/>
<entry><code><$uri></code></entry>
</row>
<row>
<entry>10</entry>
<entry>x</entry>
<entry/>
<entry>x</entry>
<entry>x</entry>
<entry><code>(+example-corp)<$uri>&</code></entry>
</row>
<row>
<entry>11</entry>
<entry>x</entry>
<entry/>
<entry>x</entry>
<entry/>
<entry><code>(+example-corp)<$uri></code></entry>
</row>
</tbody>
</tgroup>
</table>Note that in patterns 8, 9, 10, and 11, the attribute describes the root
node, i.e., the graph itself, and not any entity in the graph. In patterns 8 and
9, the attribute describes the common root node of the current graph. In
patterns 10 and 11, the attribute describes a peer root or inner root
node.</para>
<para>Note also that a peer root node MUST appear before an inner root node in a
sequence that includes both root node types. </para>
<section>
<title>Specialization and Generalization</title>
<para>Within a semantic tree, there is a standard pattern called the
specialization/ generalization pattern for specializing the semantic meaning
of an entity or attribute. This pattern is based entirely on the order of
the XDI identifiers representing each arc in an XDI address. The rule is:
each identifier in a sequence of entity identifiers specializes the final
entity in the sequence, and each attribute in a sequence of attribute
identifiers specializes the final attribute in the sequence. </para>
<para>This rule applies no matter how deep the sequence. For example, each of
the following XDI addresses further specializes the final entity—in this
case a bolt. <simplelist>
<member><code>#bolt </code></member>
<member><code>#locking#bolt </code></member>
<member><code>#engine#locking#bolt </code></member>
<member><code>#airplane#engine#locking#bolt </code></member>
<member><code>#jet#airplane#engine#locking#bolt </code></member>
<member><code>+example-corp#jet#airplane#engine#locking#bolt</code>
</member>
</simplelist>Note: although the specialization/generalization pattern
happens to align with how a noun is specialized by a series of adjectives or
adverbs in English, the pattern is not derived from English (or any other
human language). It is a natural property of semantic trees. </para>
<para>In the first five cases in the example above, the specialization is one of
type; each preceding entity class further specializes the type of bolt. Such
type specializations may be one of two kinds: <orderedlist>
<listitem>
<para><emphasis role="bold">Defined specializations</emphasis> are
formally defined in an XDI dictionary so there are
machine-understandable rules describing how the specialization
either categorizes or modifies the attributes and/or relations
of the specialized entity. </para>
</listitem>
<listitem>
<para><emphasis role="bold">Ad hoc specializations</emphasis> do not
change the semantic definition of an entity but serve only to
categorize it.</para>
</listitem>
</orderedlist>In the final case in the example above, where the class
sequence is put in the context of the <code>+example-corp</code> group
instance, the specialization is only one of possession and does not affect
the semantic definition of the entity. </para>
<para>The specialization/generalization pattern also applies to attributes. The
following examples shows how a phone number attribute can be specialized: <simplelist>
<member><code><#phone> </code></member>
<member><code><#home><#phone> </code></member>
<member><code><#work><#phone> </code></member>
<member><code><#fax><#phone> </code></member>
<member><code><#home><#fax><#phone> </code></member>
<member><code><#work><#fax><#phone></code></member>
</simplelist>In this example, none of the specializations changes the
semantics of the phone number being described; they only serve to categorize
it. </para>
<para>Note that the specialization/generalization pattern cannot be applied to
peer root nodes—because they all represent peer XDI graphs—or to literal
nodes—because they cannot be nested.</para>
</section>
</section>
<section>
<title> Peer Roots and XDI Discovery</title>
<para>Conventional directory tree architectures such as X.500, LDAP, and DNS assume
a single rooted directory information tree (DIT). XDI semantic tree architecture
assumes there may be any number of parallel rooted trees (peer graphs), each
with its own peer root node. As discussed in the Peer Roots section, while all
peer graphs have a single logical root (the XDI common root node), none of them
are assumed to be authoritative for a particular branch of the graph. Authority
may only be determined by consensus among a set of peers.</para>
<para>The process of determining this consensus is called <glossterm>XDI
discovery</glossterm> and is defined by the XDI Discovery specification
<xref linkend="xdi-discovery-1.0"/>. XDI discovery begins with the
assumption that any peer root node may contain its own subgraph of other peer
root nodes, including attributes such as the authoritative IRIs for their XDI
endpoints. Each of these subgraphs is itself a branch of the semantic tree. An
XDI discovery agent may “walk the tree” of the peer root nodes it trusts to
discover the location of other peer graphs. In this process it may also
determines their consensus about the authority for a particular branch of the
XDI semantic tree. </para>
<para>The sequence of peer root nodes that need to be traversed to determine the
location and authority of another peer root node is called the peer root
address. Each peer root node in the address includes the XDI identifier for the
entity authoritative for that peer root relative to the previous peer root. This
discovery process can be applied to all XDI entities, including persons, groups,
and things. Examples of peer root addresses: <simplelist>
<member><code>(=example-person)</code></member>
<member><code>(+example-corp)(=example-person)</code></member>
<member><code>(+example-consortia)(+example-corp)(=example-person)</code></member>
<member><code>(=example-person)(*example-thing)</code></member>
<member><code>(=example-corp)(*example-thing)</code></member>
</simplelist>Each peer graph for <code>(=example-person)</code> in the above
examples represents the same natural person (because it has the same absolute
XDI identifier). However each is a different peer graph because of its position
in the peer root address. In the first example, the peer graph is at the common
root level. This means the authority is the natural person with the following
XDI entity address:<programlisting> =example-person</programlisting> In the
second example, the peer root (=example-person) is relative to the peer
root(+example-corp). This means it is authoritative for the following XDI
address: <programlisting>+example-corp=example-person</programlisting>This is a
contextual description of <code>=example-person</code> in the context of
<code>+example-corp</code>, for which <code>+example-corp</code> is
authoritative. </para>
<para>In the third example, the peer root <code>(+example-corp)</code> is itself
relative to the peer root <code>(+example-consortia)</code>. This means it is
authoritative for the following XDI address:
<programlisting>+example-consortia+example-corp=example-person</programlisting>This
is a contextual description of <code>=example-person</code> in the context of
<code>+example-corp</code>, which in turn is a contextual description in the
context of <code>+example-consortia</code>. The first entity in this sequence,
<code>+example-consortia</code>, is ultimately authoritative for this entire
address. </para>
<para>This pattern may be nested as deeply as needed in order to delegate authority
for XDI peer graphs the same way authority may be delegated in DNS or other
hierarchical naming and directory tree systems. </para>
<para>Note that because any number of peer graphs may describe the same peer root
address, in XDI there is no single authoritative peer root node at which to
begin discovery of that address. Instead, an XDI discovery agent may choose a
specific peer root node to trust as the starting point, or it may query multiple
peer root nodes and compare their answers to determine a consensus. </para>
<para>For more details on XDI discovery, see the XDI Discovery specification <xref
linkend="xdi-discovery-1.0"/>. </para>
</section>
<section>
<title>Inner Roots and XDI Reification</title>
<para>As described in Inner Roots in the Roots section, semantic tree architecture
uses the inner graph pattern to reify a relationship so it can be further
described. This pattern is fundamental to many aspects of XDI architecture
including XDI messaging, XDI connections, and XDI policies. </para>
<para>From an XDI addressing standpoint, the inner graph pattern enables context
nodes to be described and addressed in the context of either a generic or a
specific relationship. For a generic relationship, the predicate of the inner
graph is an XDI class, and all the root-level subjects of the inner graph are
members of that class, as shown in the following example.
<programlisting>{
"(=alice/#friend)": {
"=bob": {
"/#introducer": [
"=beth"
],
"<#introduction><$date>": {
"&": "2010-11-12"
}
},
"=edith": {
"/#introducer": [
"=beth"
],
"<#introduction><$date>": {
"&": "2010-11-13"
}
},
"=frank": {
"/#introducer": [
"=edith"
],
"<#introduction><$date>": {
"&": "2010-11-14"
}
}
}
}</programlisting>For
a specific relationship, the predicate of the inner graph is an XDI instance,
and the root-level subjects of the inner graph are either attributes of that
specific relationship, or entities describing the relationship, as shown in the
following example.
<programlisting>{
"(=alice/=bob)": {
"#marriage": {
"/#minister": [
"=parson-brown"
],
"<$date>": {
"&": "2010-08-22"
}
}
}
}</programlisting>From
the standpoint of XDI addressing, it does not matter if an inner graph is
generic or specific. It both cases, the inner graph serves as the root of
another complete XDI graph, and addressing within this graph works the same way
as inside any XDI common graph, with one exception: an inner graph MUST NOT
contain a peer root node. Only the common root node or another peer root node
may contain a peer root node. However an inner root node MAY contain another
inner root node. </para>
<para>Both generic and specific relationships described by inner graphs are the
starting point for XDI link contracts. A link contract is an entity that
describes the rights and permissions over one or more XDI subgraphs that an
authorizing XDI authority extends to a requesting authority. Each link contract
includes a policy branch that uses nested inner graphs to express the policies
that must be satisfied in order to grant authorization. XDI link contracts and
policy expressions are defined in the XDI Policy specification <xref
linkend="xdi-policy-1.0"/>.</para>
</section>
</section>
<section>
<title>Namespace Architecture</title>
<para>The ABNF defines six native namespaces for XDI identifiers. Namespaces may be used
with properties except in the cases in the table below, as defined in the following
sections.</para>
<para>Dollar words are inherently immutable and absolute, and do not contain
encapsulated IRIs.</para>
<para>Ordinals, on the other hand, are inherently relative.<table frame="none">
<title>Namespace and Property Compatibility</title>
<tgroup cols="8" align="center">
<colspec colname="c1" colnum="1" colwidth="1.0*"/>
<colspec colname="c2" colnum="2" colwidth="1.0*"/>
<colspec colname="c3" colnum="3" colwidth="1.0*"/>
<colspec colname="c4" colnum="4" colwidth="1.0*"/>
<colspec colname="c5" colnum="5" colwidth="1.0*"/>
<colspec colname="c6" colnum="6" colwidth="1.0*"/>
<colspec colname="c7" colnum="7" colwidth="1.0*"/>
<colspec colname="newCol8" colnum="8" colwidth="1*"/>
<thead>
<row>
<entry>Namespace</entry>
<entry>Mutable</entry>
<entry>Immutable</entry>
<entry>Absolute</entry>
<entry>Relative</entry>
<entry>Rooted</entry>
<entry>Nested</entry>
<entry>IRI</entry>
</row>
</thead>
<tbody>
<row>
<entry><code>$</code></entry>
<entry><emphasis role="bold">No</emphasis></entry>
<entry>Yes*</entry>
<entry>Yes</entry>
<entry><emphasis role="bold">No</emphasis></entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry><emphasis role="bold">No</emphasis></entry>
</row>
<row>
<entry><code>#</code></entry>
<entry><emphasis role="bold">No</emphasis></entry>
<entry>Yes*</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry><code>=</code></entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry><code>+</code></entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry><code>*</code></entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes</entry>
</row>
<row>
<entry><code>@</code></entry>
<entry>Yes</entry>
<entry>Yes</entry>
<entry>Yes**</entry>
<entry>Yes</entry>
<entry>Yes**</entry>
<entry>Yes</entry>
<entry><emphasis role="bold">No</emphasis></entry>
</row>
</tbody>
</tgroup>
</table></para>
<para>* Classes identifiers are immutable by definition, so they do not use the
immutability symbol. See <emphasis>Classes</emphasis>.</para>
<para>** Absolute ordinal identifiers are not ordered, and only absolute ordinal
identifiers may be rooted. See <emphasis>Ordinals</emphasis>.</para>
<para>Four of the namespaces also allow the use of IRIs as XDI identifiers. This allows
any resource with an IRI to be described by an XDI graph. In addition, any XDI
address may be transformed into a valid IRI, so all XDI graph nodes may be treated
as Web resources. See the <emphasis>IRIs</emphasis> section..</para>
<section>
<title>Mutable and Immutable Identifiers (XDI Names and XDI Numbers)</title>
<para>To meet the Persistent Identification design goal, XDI namespace architecture
requires the ability for XDI authorities to assign identifiers that are
immutable, i.e., assigned once to identify a resource and never reassigned to
identify a different resource. Immutable XDI identifiers are also called XDI
numbers. The requirements for immutable identifiers are defined by the IETF URN
(Uniform Resource Name) specification <xref linkend="rfc4122"/>. </para>
<para>At the same time, to meet human usability requirements, XDI namespace
architecture requires the ability for XDI authorities to assign identifiers that
are mutable, i.e., that may be assigned to identify one resource at one point in
time and a different resource at a different point in time. Mutable XDI
identifiers are also called XDI names. Examples of mutable identifiers are
dynamic IP addresses, domain names that may be bought and sold by different
owners, and email addresses that may be recycled to different users. </para>
<para>Because XDI names are typically more human-friendly than XDI numbers, they are
the default form of XDI identifier. XDI addressing only requires explicit syntax
to express an XDI number. All XDI identifiers except those in the class
namespaces (<code>$</code> and <code>#</code>) MUST use the <code>!</code>
immutability symbol if and only if the XDI authority for that identifier asserts
that the identifier is immutable. </para>
<para>All identifiers in the XDI class namespaces are immutable by definition and
MUST NOT use the immutability symbol. While an XDI class identifier MUST NOT be
reassigned, its definition MAY evolve. An evolved definition SHOULD be
identified with an XDI version number. See Versioning. </para>
<para>The XDI <code>&</code> literal symbol is immutable by definition and MUST
NOT use the immutability symbol. </para>
<para>An XDI address consisting of a sequence of XDI identifiers is immutable if and
only if all of the XDI identifiers in the sequence are immutable. </para>
<para>The name/number reference pattern defined in the Reference Relations section
demonstrates how XDI graphs may use equivalence relations to map human-friendly
mutable identifiers to machine-friendly immutable identifiers. Such mappings may
also be cryptographically signed. Thus, while neither an XDI name nor an XDI
number by itself can solve the namespace design problem known as Zooko’s
Triangle <xref linkend="zooko"/>
https://en.wikipedia.org/wiki/Zooko%27s_triangle], the combination of an XDI
name/number mapping can effectively “square Zooko’s triangle”.</para>
</section>
<section>
<title>Absolute and Relative Identifiers</title>
<para>Absolute and relative identifiers play a very different role in semantic tree
architecture than in conventional directory tree or federated namespace
architectures. In the latter, absolute identifiers only exist at the top level
of the tree, i.e., they identify first level of nodes under the root. All other
identifiers for nodes below the first level are relative to the nodes above
them. </para>
<para>In XDI, an absolute identifier is one that identifies the same logical
resource regardless of its parent context. A relative identifier is one whose
scope of identification of a resource is relative to its parent context. </para>
<para>For example, in each of the following three XDI addresses, the identifier
<code>=!:uuid:x-1</code> identifies the same natural person.
<programlisting>=!:uuid:x-1
+!:uuid:x-2=!:uuid:x-1
+!:uuid:x-3+!:uuid:x-2=!:uuid:x-1</programlisting>In
the second address, the person is represented in the context of a group that
also has an absolute address. In the third address, both the person and the
first group are represented in the context of a second group that also has an
absolute address. </para>
<para>Because absolute identifiers may exist at any level of the XDI graph and
provide so much semantic value, they are the default form of XDI identifier. XDI
addressing only requires explicit syntax to express when an XDI identifier is
relative. All XDI identifiers except those in the <code>$</code> reserved class
namespace MUST use the <code>~</code> relativity symbol if and only if the XDI
authority for that namespace asserts that the identifier is relative. </para>
<para>All identifiers in the <code>$</code> reserved class namespace are absolute by
definition and MUST NOT use the relativity symbol. The following two XDI
addresses are an example of a relative identifier for a person in the context of
absolute identifiers for two different groups.
<programlisting>+!:uuid:x-4=~alice
+!:uuid:x-5=~alice</programlisting>Unlike
the previous example, no inference can be made that the person identified by
<code>=~alice</code> relative to the first group has any relationship to the
person identified by <code>=~alice</code> relative the second group. The
equivalence of the two relative identifiers has no semantic meaning in an XDI
graph. An XDI address consisting of a sequence of XDI identifiers is absolute if
and only if it begins with an absolute identifier. Because of this rule, when a
relative identifier is placed in the context of an absolute identifier, the
combination becomes absolute. For example, in the three XDI addresses below, the
combination of
<code>+!:uuid:x-4=~alice</code> represents the same unique
person in all three.
<programlisting>+!:uuid:x-4=~alice
+!:uuid:x-5+!:uuid:x-4=~alice
+!:uuid:x-6+!:uuid:x-5+!:uuid:x-4=~alice</programlisting>This
rule holds true even for multiple relative identifiers. For example, in the
three XDI addresses below, the combination of
<code>+!:uuid:x-4=~alice*~phone</code> represents the same unique device in
all three.
<programlisting>+!:uuid:x-4=~alice*~phone
+!:uuid:x-5+!:uuid:x-4=~alice*~phone
+!:uuid:x-6+!:uuid:x-5+!:uuid:x-4=~alice*~phone</programlisting>An
XDI address consisting of a sequence of XDI identifiers that begins with a
relative identifier is always relative, even if other identifiers in the
sequence are absolute. </para>
<para>To summarize the rules, an XDI absolute identifier: <orderedlist>
<listitem>
<para>MUST be globally unique in the XDI logical graph.</para>
</listitem>
<listitem>
<para>MUST NOT include the relativity symbol.</para>
</listitem>
<listitem>
<para>MAY appear at any level of an XDI graph.</para>
</listitem>
<listitem>
<para>MUST be inferred as identifying the same logical resource
regardless of the context in which it appears.</para>
</listitem>
</orderedlist> An XDI relative identifier: <orderedlist>
<listitem>
<para>MUST be unique within the scope of its parent context node.</para>
</listitem>
<listitem>
<para>MUST include the relativity symbol.</para>
</listitem>
<listitem>
<para>MUST NOT appear at the root level of an XDI graph.</para>
</listitem>
<listitem>
<para>MUST NOT be inferred as identifying the same resource relative to
any other XDI context node.</para>
</listitem>
</orderedlist></para>
<para>For absolute identifiers, the XDI name prefix "x-" is reserved for examples
and testing and SHOULD NOT be assigned for any other purpose.</para>
</section>
<section>
<title>Rooted and Nested Identifiers</title>
<para>For the same reason a semantic tree has different definitions of absolute and
relative identifiers, it needs different terms for describing the relative
position of an identifier in an XDI address. </para>
<para>In conventional directory tree or federated namespace architectures, an
absolute identifier must be the first identifier in an address sequence because
its parent is the root node. All other identifiers in the address sequence are
relative. </para>
<para>In a semantic tree, an absolute identifier may exist at any level of the tree.
So XDI uses the term rooted identifier for an identifier whose parent is a root
node, and rooted address for an XDI address that begins with a rooted
identifier. It uses the term nested identifier for an identifier that whose
parent is not a root node, and nested address for an XDI address that begins
with a nested identifier. </para>
<para>Per the rules in the previous section, it follows that: <orderedlist>
<listitem>
<para>An XDI rooted identifier MUST be an absolute identifier, and a
rooted address MUST be an absolute address. </para>
</listitem>
<listitem>
<para>An XDI nested identifier MAY be either an absolute or a relative
identifier, and a nested address MAY be either an absolute or a
relative address.</para>
</listitem>
</orderedlist>An XDI rooted address is the equivalent of a fully-qualified
address in conventional directory tree or federated namespace architectures.
Those architectures assume only a single root node so there is only a single
form of a rooted address. In XDI semantic tree architecture there are four forms
of rooted addresses as shown in he table below.<table frame="none">
<title>Rooted Address Forms</title>
<tgroup cols="2" align="center">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="3.94*"/>
<thead>
<row>
<entry>Rooted address type</entry>
<entry>Example</entry>
</row>
</thead>
<tbody>
<row>
<entry>Common rooted</entry>
<entry><code>=alice<#email></code></entry>
</row>
<row>
<entry>Peer rooted</entry>
<entry><code>(+example-corp)=alice<#email></code></entry>
</row>
<row>
<entry>Inner rooted</entry>
<entry><code>(+example-corp/#employee)=alice<#email></code></entry>
</row>
<row>
<entry>Peer and inner rooted</entry>
<entry><code>(+example-dir)(+example-corp/#employee)=alice<#email></code></entry>
</row>
</tbody>
</tgroup>
</table>In all four examples, the rooted address is
<code>=alice<#email></code>. In the first example, the root is the common
root. In the second, the root is a peer root; in the third, an inner root; and
in the fourth, both a peer root and an inner root. </para>
<para>Note that when an XDI address begins with a peer or inner root node, that peer
or inner root node is itself still rooted in the common root node. The common
root node is the logical parent node of all absolute XDI addresses.</para>
</section>
<section>
<title>Public and Private Identifiers</title>
<para>Most directory tree and federated namespace architectures are designed for
either public or private access, but not both. XDI semantic tree namespaces are
equally suited for both public and private access. </para>
<para>Unlike the distinctions between mutable and immutable identifiers and between
absolute and relative identifiers, the distinction between public and private
identifiers is not syntactic, but rather one of access policy. </para>
<para>A <glossterm>public identifier</glossterm> is an XDI identifier whose XDI
discovery information is available at an XDI endpoint accessible via a public
link contract, i.e., a link contract that grants any requesting authority
permission to access the subgraph without authentication. Public link contracts
are defined in the XDI Policy specification <xref linkend="xdi-policy-1.0"/>. </para>
<para>A <glossterm>private identifier</glossterm> is an XDI identifier that requires
a non-public link contract in order to access its XDI discovery information. </para>
<para>Note that the distinction between public and private identifiers in XDI does
not depend on the visibility of the identifier itself. A public identifier may
be kept hidden or a private identifier may be publicly known. The distinction is
based on access control. </para>
<para>A special XDI context, <code>$anon</code>, is reserved for private identifiers
whose subgraphs are intended for sharing XDI data while preserving anonymity,
such as might be required for aggregated health records or quantified self data.
The $anon context is defined in the XDI Privacy Mechanisms specification <xref
linkend="xdi-privacy-1.0"/>. </para>
<para>The ability to support both public and private identifiers—and for private
identifiers to use <code>$rep</code> replacement relations (as described in
Replacement Relations in the Equivalence Relations section) to protect
pseudonymity is a key component of how XDI semantic tree architecture supports
Privacy By Design <xref linkend="pbd"/>.</para>
</section>
</section>
<section>
<title>Internationalization</title>
<para>To enable XDI to describe any resource that humans are able to identify in natural
language, XDI identifiers are defined by the Unicode Identifier and Pattern Syntax
<xref linkend="unicode-tr31"/> with the addition of underscore, hyphen, and
period as allowable non-initial charactes. </para>
<para>To enable XDI to describe any resource on the World Wide Web, XDI identifiers
support the encapsulation of any IRI (Internationalized Resource Identifier) as
covered in the IRI section.</para>
</section>
<section>
<title>Normalization and Comparison</title>
<para>Consistent identification of resources both within and across contexts is vital to
interoperability of XDI. Therefore XDI requires users to perform any normalization
of identifiers before using them as XDI identifiers. The XDI endpoint itself MUST
NOT attempt to perform any normalization or folding. We cover some specific cases
below.</para>
<para>The following normalization rules apply to all XDI identifiers except encapsulated
IRIs, which are covered in the following section.</para>
<para>These normalization rules do not by themselves prevent homographic attacks
(spoofing of an XDI identifier by using look-alike characters from a different
script). XDI authorities—and in particular those who act as XDI registries—SHOULD
impose identifier registration policies that prevent homographic attacks. </para>
<section>
<title>Upper and Lower Case</title>
<para>XDI processors MUST NOT do case folding or case-insensitive comparison of XDI
identifiers. Client systems which internally use case-insensitive identifiers
(e.g. URNs; Macintosh filenames; SQL) are expected to case-fold names to a
consistent normalized format (which SHOULD be all lower case, for compatibility
between XDI applications) before introducing it to an XDI graph.</para>
<para>However, for percent-encoded bytes in <code>%XX</code> format, the
two hex digits SHOULD be upper case <code>ABCDEF</code>, not lower case
<code>abcdef</code>.</para>
</section>
<section>
<title>Unicode Normalization Forms</title>
<para>XDI identifiers SHOULD be in Unicode Normalization Form NFKC. <xref
linkend="unicode-tr15"/> Most existing Unicode text meets this
criterion.</para>
</section>
</section>
<section>
<title>IRIs</title>
<para>To be fully compliant with W3C World Wide Web architecture, XDI addressing
incorporates IRIs in two ways: <orderedlist>
<listitem>
<para>Any World Wide Web resource identified by an IRI MAY be described in
an XDI graph by encapsulating the IRI as an XDI identifier. </para>
</listitem>
<listitem>
<para>Any XDI graph node identified by an XDI address MAY be expressed as a
World Wide Web resource by appending the XDI address to an IRI that
identifies the host XDI graph. </para>
</listitem>
</orderedlist>This section defines the rules in both directions. </para>
<section>
<title>Describing IRIs in XDI Addresses</title>
<para>Describing an IRI-identified resource in XDI requires two steps: Normalize the
IRI (to prevent misinterpretation of where the IRI terminates when encapsulated
within an XDI identifier). Encapsulate the IRI within an XDI identifier by
enclosing it in parentheses as required by the XDI ABNF. Examples:<table
frame="none">
<title>IRI Encapsulation</title>
<tgroup cols="2" align="center">
<colspec colname="c1" colnum="1" colwidth="1.0*"/>
<colspec colname="c2" colnum="2" colwidth="1.0*"/>
<thead>
<row>
<entry>IRI</entry>
<entry>XDI address encapsulating IRI</entry>
</row>
</thead>
<tbody>
<row>
<entry><code>http://example.com/</code></entry>
<entry><code>+(http://example.com/)</code></entry>
</row>
<row>
<entry><code>mailto:alice@example.com</code></entry>
<entry><code>=(mailto:alice@example.com)</code></entry>
</row>
<row>
<entry><code>https://example.com/item#id</code></entry>
<entry><code>*!(https://example.com/item#id)</code></entry>
</row>
</tbody>
</tgroup>
</table></para>
<para>To normalize an IRI prior to encapsulation, the following steps MUST be
performed in order and exactly once (since they are not idempotent). <orderedlist>
<listitem>
<para>Put the IRI into its absolute normalized form, including any
required percent-encoding, as required by the specification for the
applicable IRI scheme and by RFC 3987 <xref linkend="rfc3987"/>.
</para>
</listitem>
<listitem>
<para>Percent-encode all percent <code>%</code> characters as
<code>%25</code>. </para>
</listitem>
<listitem>
<para>Percent-encode all right parentheses <code>)</code>
characters as <code>%29</code>.</para>
</listitem>
</orderedlist> If it is later necessary to extract the original IRI, the
following steps MUST be performed on the encapsulated IRI in order and exactly
once (since they are not idempotent). <orderedlist>
<listitem>
<para>Decode all <code>%29</code> percent-encoding as right
parentheses <code>)</code> characters. </para>
</listitem>
<listitem>
<para>Decode all <code>%25</code> percent-encoding as percent
<code>%</code> characters. </para>
</listitem>
</orderedlist>Note that when the IRI is encapsulated as an XDI identifier,
semantic meaning is added—at a minimum, a prefixed XDI context symbol (and
potentially an immutability symbol and/or a relativity symbol). So there is
always a difference between the semantic meaning of the XDI identifier and the
original IRI. </para>
<para>In addition, although the resource identified by the XDI identifier MUST be
the same resource identified by the IRI on the World Wide Web, the XDI graph
node representing the resource in the logical XDI graph MUST NOT be the same
resource identified by the IRI on the World Wide Web. This separation between
the Web resource and the XDI description of the Web resource avoids the
HTTPRange-14 issue <xref linkend="httprange14"/>. </para>
</section>
<section>
<title>Transforming XDI Addresses into IRIs</title>
<para>Transforming an XDI address identifying an XDI graph node into a valid IRI
identifying a World Wide Web resource address requires two steps: <orderedlist>
<listitem>
<para>Normalize the XDI address (to turn it into a valid relative IRI
and prevent misinterpretation by an IRI parser). </para>
</listitem>
<listitem>
<para>Append the XDI address as a relative IRI to a base IRI identifying
the host XDI endpoint. </para>
</listitem>
</orderedlist>To normalize the XDI address, the following steps MUST be
performed in order and exactly once (since they are not idempotent). <orderedlist>
<listitem>
<para>Percent-encode all percent <code>%</code> characters as
<code>%25</code>. </para>
</listitem>
<listitem>
<para>Percent-encode each of the characters in the table below.</para>
</listitem>
</orderedlist><table frame="none">
<title>Percent-encoding required</title>
<tgroup cols="3" align="center">
<colspec colname="c1" colnum="1" colwidth="1*"/>
<colspec colname="c2" colnum="2" colwidth="1*"/>
<colspec colname="c3" colnum="3" colwidth="1*"/>
<thead>
<row>
<entry>Character name</entry>
<entry>Character</entry>
<entry>Encoded</entry>
</row>
</thead>
<tbody>
<row>
<entry>Dollar</entry>
<entry><code>$</code></entry>
<entry><code>%24</code></entry>
</row>
<row>
<entry>Hash</entry>
<entry><code>#</code></entry>
<entry><code>%23</code></entry>
</row>
<row>
<entry>Equals</entry>
<entry><code>=</code></entry>
<entry><code>%3D</code></entry>
</row>
<row>
<entry>Plus</entry>
<entry><code>+</code></entry>
<entry><code>%2B</code></entry>
</row>
<row>
<entry>Star, asterisk</entry>
<entry><code>*</code></entry>
<entry><code>%40</code></entry>
</row>
<row>
<entry>At sign</entry>
<entry><code>@</code></entry>
<entry><code>%26</code></entry>
</row>
<row>
<entry>Ampersand</entry>
<entry><code>&</code></entry>
<entry><code>%7C</code></entry>
</row>
<row>
<entry>Pipe, vertical bar</entry>
<entry><code>|</code></entry>
<entry><code>%3C</code></entry>
</row>
<row>
<entry>Chevrons, angle brackets</entry>
<entry><code>< ></code></entry>
<entry><code>%3C %3E</code></entry>
</row>
<row>
<entry>[Square] brackets</entry>
<entry><code>[ ]</code></entry>
<entry><code>%5B %5D</code></entry>
</row>
<row>
<entry>Braces, curly brackets</entry>
<entry><code>{ }</code></entry>
<entry><code>%7B %7D</code></entry>
</row>
</tbody>
</tgroup>
</table>If it is later necessary to restore the original XDI address, the
following steps MUST be performed on the normalized XDI address in order and
exactly once (since they are not idempotent). <orderedlist>
<listitem>
<para>Decode all the percent-encoded characters in the table above.
</para>
</listitem>
<listitem>
<para>Decode all <code>%25</code> percent-encoding as percent
<code>%</code> characters. </para>
</listitem>
</orderedlist>Once the XDI address is transformed into a relative IRI, it may be
appended to a base URI that identifies the host XDI endpoint as defined in
section 6.5 of RFC 3987 <xref linkend="rfc3987"/>. It is RECOMMENDED that the
base URI end with a forward slash. To the extent that the XDI authority is also
the authority for the DNS name, it is RECOMMENDED that DNS host name of the IRI
for an XDI endpoint begin with <code>xdi</code>. </para>
<para>If an XDI address does not contain percent-encoding, the resulting IRI will
only reflect percent-encoding of the XDI syntax characters. For example, start
with the following XDI address:
<programlisting>=alice<#email></programlisting> If the base IRI for the XDI
endpoint hosting this XDI address is:
<programlisting>http://xdi.example.com/ </programlisting>Then the resulting
fully qualified IRI would be:
<programlisting>http://xdi.example.com/%3Dalice%3C%23email%3E </programlisting>If
the XDI address contains percent-encoding, the resulting IRI will have
percent-encoding of both the original percent-encoding as well of the XDI syntax
characters. For example, take this XDI address:
<programlisting>=alice*some%20pet%20name </programlisting>When normalized and
appended to the same base URI above, the fully qualified IRI would be:
<programlisting>http://xdi.example.com/%3Dalice%2Asome%2520pet%2520name</programlisting></para>
</section>
</section>
<section>
<title>XDI Schemes</title>
<para>In addition to context, immutability, and relativity symbols, in some cases XDI
identifiers require additional syntactic structure in order to express identifiers
with specific properties. To meet this requirement, XDI addressing syntax uses a
mechanism analogous to URIs and IRIs, xalled XDI schemes. </para>
<para>With URIs and IRIs, an absolute identifier must begin with a scheme name followed
by a colon (e.g., “<code>http:</code>”, “<code>ftp:</code>”,
“<code>mailto:</code>”). Scheme names must also use a limited character set. </para>
<para>With XDI identifiers, a scheme is an optional syntactic feature. If an XDI
identifier includes an XDI scheme, the following rules apply: <orderedlist>
<listitem>
<para>An XDI scheme name MUST begin and end with a colon character and
include a sequence of one or more characters as allowed by the
<code>xdi-scheme</code> rule in the XDI ABNF. </para>
</listitem>
<listitem>
<para>The scheme name MUST follow the XDI context symbol and, if present,
the immutability symbol and/or relativity symbol. </para>
</listitem>
<listitem>
<para>The identifier following the scheme name MUST be valid according to
the scheme specification. </para>
</listitem>
</orderedlist>As with URIs and IRIs, XDI schemes are extensible. However unlike XDI
dictionary spaces, which may be specialized by any XDI authority in its own
namespace, the XDI scheme namespace is shared across all XDI authorities. To prevent
collisions, it is RECOMMENDED that: <orderedlist>
<listitem>
<para>Members of an XDI community requiring a new XDI scheme collaborate to
develop a scheme that does not conflict with existing XDI schemes.
</para>
</listitem>
<listitem>
<para>A new scheme be documented in a public specification that includes the
scheme name, the purpose of the scheme, ABNF rules for validating
identifiers conformant to the scheme, and any security, privacy, or
other special considerations for using the scheme. </para>
</listitem>
<listitem>
<para>New scheme specifications be registered with the OASIS XDI Technical
Committee. </para>
</listitem>
</orderedlist>Note that use of an XDI scheme does not alter the requirement for the
XDI identifier to be unique in the scope of its parent context—and for all XDI
absolute identifiers to be globally unique. Indeed, the motivation for the two XDI
schemes defined in the following sections is to establish interoperable standards
for how XDI identifiers can meet this global uniqueness requirement. </para>
<section>
<title>UUID (Universally Unique Identifier)</title>
<para>UUIDs as defined by RFC 4122 <xref linkend="rfc4122"/> are widely used in
distributed computing as globally unique identifiers that do not require a
central registration authority. When an XDI authority needs to generate an
absolute XDI identifier that does not have any other specific properties (such
as a cryptographic identifier—see the next section), the use of the XDI UUID
scheme is RECOMMENDED. </para>
<para>As defined in the XDI ABNF, the XDI UUID scheme name is <code>:uuid:</code>.
An XDI UUID MUST be a valid UUID conforming to RFC 4122. It SHOULD be a Version
4 UUID as specified in sections 4.1.3 and 4.4 of RFC 4122. Implementers SHOULD
follow the recommendations in RFC 4122 and RFC 1750 for generating random
numbers with sufficient entropy. </para>
<para>Although the probability of collision of two UUIDs is extremely small, XDI
authorities SHOULD always check to ensure the uniqueness of an XDI identifier
within its parent context. This is particular important for XDI authorities who
offer XDI registry and discovery services to other XDI authorities.</para>
</section>
<section>
<title>CID (Cryptographic Identifier)</title>
<para>The XDI CID scheme family is reserved for identifiers with cryptographic
properties. As defined in the XDI ABNF, the XDI CID scheme prefix is
<code>:cid-:</code>. The hyphen MUST be followed by one or more digits
identifying a specific XDI CID scheme. Specific XDI CID schemes will be defined
in either the XDI Scheme specification or the XDI Cryptographic Mechanisms
specification.</para>
</section>
</section>
</section>
<section>
<title>Versioning</title>
<para>Using semantic tree architecture, XDI graphs can model versioning uniformly and
interoperably at all levels of the tree. The overall rules for XDI versioning are
defined in the XDI Versioning specification. The minimal rules for expressing the
version of an XDI graph conformant with this specification are defined here. </para>
<para>The XDI reserved class name for versions is <code>$v</code>. Since a version tree is
by definition an ordered collection of version instances, a version class will always
appears as a collection: <orderedlist>
<listitem>
<para><code>([$v])</code> for a graph root version collection. </para>
</listitem>
<listitem>
<para><code>[$v]</code> for an entity version collection. </para>
</listitem>
<listitem>
<para><code>[<$v>]</code> for an attribute version collection.</para>
</listitem>
</orderedlist> The members of the collection must be ordinal identifiers expressing a
ordered set of version instances. </para>
<para>To express that it conforms to a specific version of this specification, an XDI graph
MAY include an XDI version statement. An XDI version statement is an XDI type statement
that uses an XDI version collection to describe the common root node of the XDI graph. </para>
<para>The current specification is the first version of the XDI Core specification, so its
version instance identifier is <code>(@~0)</code>. Therefore if an XDI graph needs to
assert conformance with this version of this specification, it MUST include the
following XDI version statement:
<programlisting>{
"/$is#": [
"($xdi)([$v])(@~0)"
]
}</programlisting> It
is NOT REQUIRED for an XDI graph to contain an XDI version statement. </para>
</section>
<section>
<title>Appendix A: Collected ABNF</title>
<programlisting>xdi-graph = *( xdi-statement / CRLF )
xdi-statement = contextual-statement / literal-statement / relational-statement
contextual-statement = direct-contextual / inverse-contextual
direct-contextual = peer-root-direct / inner-root-direct / entity-direct / attr-direct
peer-root-direct = *peer-root "//" peer-root
inner-root-direct = root-address "//" inner-root
entity-direct = entity-address "//" entity
attr-direct = attr-address "//" attr
inverse-contextual = peer-root-inverse / inner-root-inverse / entity-inverse / attr-inverse
peer-root-inverse = peer-root "/$is()/" *peer-root
inner-root-inverse = inner-root "/$is()/" root-address
entity-inverse = entity "/$is()/" entity-address
attr-inverse = attr "/$is()/" attr-address
literal-statement = entity-address 1*attr "/&/" value
literal-var-statement = entity-address 1*attr "/{&}/" value-variable
value-variable = "{" attr-class "}"
relational-statement = direct-relational / inverse-relational / relation-definition
direct-relational = xdi-address "/" 1*entity "/" xdi-address
inverse-relational = xdi-address "/$is" 1*entity "/" xdi-address
relation-definition = direct-domain / inverse-domain / direct-range / inverse-range
direct-domain = direct-entity-domain / direct-attr-domain
direct-entity-domain = root-address 1*definition "/(/)/" root-address 1*definition
direct-attr-domain = root-address *definition 1*attr-definition "/(/)/" root-address 1*definition
inverse-domain = inverse-entity-domain / inverse-attr-domain
inverse-entity-domain = root-address 1*definition "/$is(/)/" root-address 1*definition
inverse-attr-domain = root-address 1*definition "/$is(/)/" root-address *definition 1*attr-definition
direct-range = direct-entity-range / direct-attr-range
direct-entity-range = root-address 1*definition "/(/)#/" root-address 1*definition
direct-attr-range = root-address 1*definition "/(/)#/" root-address *definition 1*attr-definition
inverse-range = inverse-entity-range / inverse-attr-range
inverse-entity-range = root-address 1*definition "/$is(/)#/" root-address 1*definition
inverse-attr-range = root-address *definition 1*attr-definition "/$is(/)#/" root-address 1*definition
xdi-address = root-address / entity-address / attr-address / literal-address
root-address = *peer-root *inner-root
entity-address = root-address *entity
attr-address = entity-address *attr
literal-address = entity-address 1*attr "&"
peer-root = peer-root-instance / peer-root-variable
peer-root-instance = "(" entity ")"
peer-root-variable = "{" peer-root-instance "}"
inner-root = inner-root-instance / inner-root-variable
inner-root-instance = inner-root-peer-root / inner-root-entity
inner-root-peer-root = "(" *peer-root "/" *entity ")"
inner-root-entity = "(" *entity "/" *entity ")"
inner-root-variable = "{" inner-root-instance "}"
entity = singleton / collection / definition / variable / meta-variable
singleton = instance / class
collection = "[" class "]"
definition = "|" ( singleton / collection ) "|"
variable = "{" ( singleton / collection / definition ) "}"
meta-variable = "{" variable "}"
instance = person / group / thing / ordinal
person = "=" [ "!" ] [ "~" ] id-string
group = "+" [ "!" ] [ "~" ] id-string
thing = "*" [ "!" ] [ "~" ] id-string
ordinal = "@" [ "!" ] [ "~" ] ordinal-string
class = reserved-class / unreserved-class / "$" / "#" / "=" / "+" / "*" / "@"
reserved-class = "$" xdi-name
unreserved-class = "#" [ "~" ] id-string
attr = attr-singleton / attr-collection / attr-definition / attr-variable / attr-meta-variable
attr-singleton = attr-class / attr-instance
attr-collection = "[" attr-class "]"
attr-definition = "|" ( attr-singleton / attr-collection ) "|"
attr-variable = "{" ( attr-singleton / attr-collection / attr-definition ) "}"
attr-meta-variable = "{" attr-variable "}"
attr-class = "<" class ">"
attr-instance = "<" instance ">"
id-string = xdi-name / xdi-scheme / encap-iri
ordinal-string = int / other-scheme
xdi-name = ID_Start *( ID_Continue / "_" / "-" / "." )
pct-encoded = "%" HEXDIG HEXDIG
xdi-scheme = uuid-scheme / cid-scheme / other-scheme
uuid-scheme = ":uuid:" 8HEXDIG "-" 4HEXDIG "-" 4HEXDIG "-" 2HEXDIG 2HEXDIG "-" 12HEXDIG
cid-scheme = ":cid-" 1*DIGIT ":" xdi-name
other-scheme = ":" ( lower-alpha / DIGIT ) *( lower-alpha / DIGIT / "_" / "-" / "." ) ":" xdi-name
encap-iri = "(" absolute-iri ")"
absolute-iri = iri-scheme ":" 1*iri-char
iri-scheme = ALPHA *( ALPHA / DIGIT / "+" / "-" / "." )
iri-char = safe-char / %xA0-EFFFD / pct-encoded
safe-char = unreserved / reserved / gen-delims / safe-sub-delims
unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~"
reserved = gen-delims / safe-sub-delims
gen-delims = ":" / "/" / "?" / "#" / "[" / "]" / "@"
safe-sub-delims = "!" / "$" / "&" / "(" / "*" / "+" / "," / ";" / "="
value = "false" / "null" / "true" / object / array / number / string
object = begin-object [ member *( value-separator member ) ] end-object
member = string name-separator value
array = begin-array [ value *( value-separator value ) ] end-array
begin-array = ws %x5B ws ; [ left square bracket
begin-object = ws %x7B ws ; { left curly bracket
end-array = ws %x5D ws ; ] right square bracket
end-object = ws %x7D ws ; } right curly bracket
name-separator = ws %x3A ws ; : colon
value-separator = ws %x2C ws ; , comma
number = [ "-" ] int [ frac ] [ exp ]
exp = [ "e" / "E" ] [ "-" / "+" ] 1*DIGIT
frac = "." 1*DIGIT
int = "0" / ( %x31-39 *DIGIT ) ; no leading zeros
string = quotation-mark *char quotation-mark
char = unescaped / backslash ( quotation-mark / backslash /
"/" / "b" / "f" / "n" / "r" / "t" / "u" 4HEXDIG )
backslash = %x5C ; \ reverse solidus U+005C
quotation-mark = %x22 ; " quotation mark U+0022
unescaped = %x20-21 / %x23-5B / %x5D-10FFFF
ws = *( %x20 / %x09 / %x0A / %x0D )
ALPHA = %x41-5A / %x61-7A ; A-Z, a-z
DIGIT = %x30-39 ; 0-9
HEXDIG = %x30-39 / %x41-46 / %x61-66 ; 0-9, a-f, A-F
CRLF = %x0D / %x0A / ( %x0D %x0A )</programlisting>
</section>
<section>
<title>Appendix B: Acknowledgments</title>
<para>In addition to the Editors, the XDI Technical Committee gratefully acknoledges the
contributions of its active members:</para>
<para>
<itemizedlist>
<listitem>
<para>Christopher Allen</para>
</listitem>
<listitem>
<para>Daniel Blum</para>
</listitem>
<listitem>
<para>Les Chasen</para>
</listitem>
<listitem>
<para>Peter Davis</para>
</listitem>
<listitem>
<para>Dr. Phillip Windley</para>
</listitem>
<listitem>
<para>Dr. Lionel Wolberger</para>
</listitem>
<listitem>
<para>Ning Zhang</para>
</listitem>
</itemizedlist>
</para>
<para>The Committee would also like to thank previous members:</para>
<para>
<itemizedlist>
<listitem>
<para>Geoffrey Strongin (Past Co-Chair)</para>
</listitem>
<listitem>
<para>Bill Barnhill (Past Co-Chair)</para>
</listitem>
<listitem>
<para>Andy Dale</para>
</listitem>
<listitem>
<para>Victor Grey</para>
</listitem>
<listitem>
<para>Jim Fournier</para>
</listitem>
<listitem>
<para>Mike Schwartz</para>
</listitem>
<listitem>
<para>John Bradley</para>
</listitem>
<listitem>
<para>Aldo Castaneda</para>
</listitem>
<listitem>
<para>Kaliya (IdentityWoman)</para>
</listitem>
<listitem>
<para>William Dyson</para>
</listitem>
</itemizedlist>
</para>
<para>Finaly, the Committee would like to thank OASIS staff members for their ongoing support: Chet Ensign, Paul Knight, Jamie Clark, Dee Schur, Robin Cover, and Scott McGrath.</para>
</section>
<section>
<title>Appendix C: Revision History</title>
<para>
<table frame="none">
<title>Table</title>
<tgroup cols="6" align="center">
<colspec colname="c1" colnum="1" colwidth="1.16*"/>
<colspec colname="c2" colnum="2" colwidth="1*"/>
<colspec colname="c3" colnum="3" colwidth="3.43*"/>
<colspec colname="c4" colnum="4" colwidth="1.76*"/>
<colspec colname="c5" colnum="5" colwidth="1.38*"/>
<colspec colname="newCol6" colnum="6" colwidth="8.11*"/>
<thead>
<row>
<entry>Revision</entry>
<entry>Date</entry>
<entry>Changes Made</entry>
</row>
</thead>
<tbody>
<row>
<entry>CSD 01</entry>
<entry>29 October 2015</entry>
<entry>First Version</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
</section>
</article>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]