XDI Core Version 1.0

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 [RFC 7159]:

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 Type Relations section).

All non-literal nodes in the XDI graph model are called context nodes. 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 [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.

In XDI the term “context” is used uniformly across all levels of the REAL model to describe all forms of semantic context, including when:

See Contextual Arcs and Contextual Statements, below.

All context nodes MUST have:

The XDI REAL model defines six global context types in two groups:

The context symbols for each type are shown in the table below:


A definition of each context type is provided in the Entity section below.

Note that XDI syntax also uses four other single-character symbols:

The XDI REAL model defines six context roles in two groups:

The context brackets for each role are shown in the table below:

Each context role is defined in its own section below.

In the XDI REAL model, a literal node MUST be the object of exactly one literal arc expressed by exactly one literal statement. The subject of a literal arc MUST be an XDI attribute node. An XDI attribute node MUST have no more than one literal arc.

There are two key differences between XDI literal arcs and RDF predicates whose object is a literal node:

Because of the first difference above, an XDI literal arc is the semantic equivalent of the rdf:value property in RDF [rdf-schema]. Thus in XDI, all literal arcs MUST have the same XDI identifier: the ampersand character &. This is called the literal symbol. All XDI literal statements MUST use the literal symbol as the predicate. Examples:


In XDI JSON serialization format:

{
    "=example<#email>": {
        "&": "foo@example.com"
    },
    "+example<#main><#phone>": {
        "&": "+44-2222-888888"
    },
    "*!1234[<#event>]<@78><$t>": {
        "&": "2010-09-20T10:11:12Z"
    }
}

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:


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. [rdf-concepts]

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 contextual arc expressed by exactly one contextual statement. The subject of a contextual statement MUST be another context node, called the parent node or supercontext. 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 child node or subcontext. The object of a contextual statement MUST have an XDI identifier that is unique in the parent context.

The result of these requirements is that XDI context nodes form a rooted directed acyclic graph, called a semantic tree, 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.

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 [webarch]. See the XDI Addressing section for details.

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; <#interior> and <#color> are XDI attributes.

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:

{
    "=example": {
        "//": [
            "#car"
        ]
    },
    "=example#car": {
        "//": [
            "<#interior>"
        ],
        "<#interior>": {
            "//": [
                "<#color>"
            ]
        },
        "<#interior><#color>": {
            "&": "black"
        }
    }
}

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 implied parameter (see the Serialization section for details). Below is the same example graph without the contextual statements:

{
    "=example#car": {
        "<#interior><#color>": {
            "&": "black"
        }
    }
}

Any relationship between two XDI graph nodes that is not described by a literal or contextual arc is described by a relational arc expressed by a relational statement. The predicate of a relational statement MUST be a sequence of one or more XDI entities.

XDI relational arcs are the equivalent of RDF properties that describe the relationship between two RDF resources. Examples:


In the XDI JSON serialization, a predicate expressing a relational arc is prefixed with a forward slash character:

{
    "=person-1": {
        "/#friend": [
            "=person-2",
            "=person-3"
        ],
        "/#best#friend": [
            "=person-3"
        ],
        "/#employer": [
            "+example.company"
        ]
    },
    "[#device]*!:uuid:...": {
        "/#owner": [
            "=person-1"
        ]
    }
}

Relational statements may also be used to assert type or subclass relationships. See Type Relations.

A reserved class 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.

The XDI identifier of a reserved class MUST begin with the $ context symbol. The $ context symbol by itself represents the class of all reserved classes. Reserved class names are also known as dollar words or keywords. Examples:

$iri
$do
$and
$or
$not
$public

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.

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 # context symbol. The # context symbol by itself represents the class of all unreserved classes. Unreserved class names are also known as tags, hashtags, or dictionary words. Examples:

#email
#passport
#home
#work
#friend
#enemy

An unreserved class name MUST be immutable and MUST NOT use the XDI immutability symbol.

In a dictionary context, unreserved class names are called dictionary words. 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.

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.

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.

The XDI identifier of a natural person is called a personal authority. A personal authority MUST begin with the = 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).

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:

=example
=example-name
=example.name

Example of a personal XDI number (in this case, using the XDI UUID scheme):

=!:uuid:33ad7beb-1abc-4a26-b892-466df4379a51

Examples of personal encapsulated IRIs:

=(https://example.name/)
=(mailto:foo@example.com)

A personal XDI identifier represents a new form of digital identity for individuals. This can be referred to as sovereign identity 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. [sovereign-identity].

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 + context symbol. The + context symbol by itself represents the class of all groups. Group identifiers are also known as plus names (mutable) or plus numbers (immutable). Examples:

+example
+example-company
+example.org
+!:uuid:f336a645-f5a9-41b7-ab80-ace41a8f69c2
+(https://example.com/)
+(mailto:division@example.com)

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.

Any unordered XDI instance that does not represent a person or a group represents an XDI thing. 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.

Note: an XDI thing is not the same as an owl:Thing, which is the root class of all classes in OWL [owl].

The XDI identifier of an thing MUST begin with the * context symbol. The * context symbol by itself represents the class of all things. XDI thing identifiers are also known as star names (mutable) or star numbers (immutable).

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.

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:

Following is an example of XDI things serving as entity instances (in thsi case identified using immutable UUIDs):

{
    "+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"
        }
    }
}

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.

{
    "=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"
        }
    }
}

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.

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:

See Absolute and Relative Identifiers and Rooted and Nested Identifiers.

The @ context symbol by itself represents the class of all ordered instances.

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.

By default, ordinal identifiers are non-negative integers, called order numbers. 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):

{
    "=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"
        ]
    }
}

Order numbers also apply to attribute instances as shown in this example:

{
    "=example": {
        "<#pref>[<#email>]<@~0>": {
            "&": "alice#example.com"
        },
        "<#pref>[<#email>]<@~1>": {
            "&": "alice.roth@example.net"
        },
        "<#pref>[<#email>]<@~2>": {
            "&": "stillalice@example.org"
        }
    }
}

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.

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 Cryptography 1.0 specification. [XDI-Cryptography-V1.0]

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.

Absolute XDI identifiers are defined in Absolute and Relative Identifiers section.

Following is an example of the same natural person represented by the same absolute XDI name =alice in three different contexts (the common root context and two group contexts).

{
    "=alice": {
        "<#email>": {
            "&": "alice@example.name"
        }
    },
    "+example-company=alice": {
        "<#email>": {
            "&": "asmith@example-company.com"
        }
    },
    "+example-club=alice": {
        "<#email>": {
            "&": "alice.smith@example-club.com"
        }
    }
}        

Since XDI names are mutable (reassignable), immutable references require XDI numbers. Here is the same example using XDI numbers in the form of UUIDs.

{
    "=!: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"
        }
    }
}     

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 $is.

Unlike all other XDI predicates, there is no inverse form—$is is its own inverse. See Inverse Relations.

A $is 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.

A $is statement does not have any special XDI processing rules. Therefore if an XDI endpoint returns a $is statement, it is the requestor’s responsibility to determine if it needs to request the subgraph identified by the object of that statement.

Following are two examples of $is 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).

{
    "=alice": {
        "/$is": [
            "+example.club=~alice.smith"
        ]
    }
}       

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).

{
    "=!:uuid:33ad7beb-1abc-4a26-b892-466df4379a51": {
        "/$is": [
            "+!:uuid:1c958708-d5aa-4213-a6a9-73dd423502b3=!:uuid:8ded2f7e-afb4-4494-9918-0fecf38f80d5"
        ]
    }
}

{
    "=!: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
        }
    }
}

{
    "=!:uuid:33ad7beb-1abc-4a26-b892-466df4379a51": {
        "<#age>": {
            "&": 33
        }
    }
}

The contextual arcs in an XDI graph form a rooted tree. To ensure deterministic traversal, this rooted tree must be acyclic—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 cycle.

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.

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.

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.

A reference relation MUST be expressed using the XDI predicate $ref. An inverse reference relation MUST be expressed with the XDI predicate $is$ref. See Inverse Relations.

A $ref 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.

An inverse reference relation is not canonical, so a context node described by an $is$ref relation MAY be the subject of more than one $is$ref statement and MAY contain its own subgraph. When a $ref relation is reached while traversing an XDI address, the $ref 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 $ref relation, both the $ref relation and the object subgraph will be included in the returned subgraph.

Note: this behavior can be modified by an XDI messaging parameter as defined in the XDI Messaging specification.

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 name/number reference pattern. The following example shows a name/number $ref relation for both a person and a group:

{
    "=alice": {
        "/$ref": [
            "=!:uuid:33ad7beb-1abc-4a26-b892-466df4379a51"
        ]
    },
    "+example.club": {
        "/$ref": [
            "+!:uuid:1c958708-d5aa-4213-a6a9-73dd423502b3"
        ]
    }
}        

Rules for processing of operations on XDI graphs are defined in the XDI Messaging specification [XDI-Messaging-V1.0]. This includes rules for processing of equivalence relations. For informative purposes, here is a summary:

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

Contextual statements define the branch nodes of a semantic tree. See Contextual Arcs and Contextual Statements. 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.

literal-statement       = entity-address 1*attr "/&/" value
literal-var-statement   = entity-address 1*attr "/{&}/" value-variable
value-variable          = "{" attr-class "}"

Literal statements define the leaf nodes of a semantic tree. See Literal Arcs and Literal Statements. An additional rule applies to literal statements: the final node sequence before a literal predicate MUST be one of two options:

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

Relational statements define relationships between context nodes in a semantic tree. See Relational Arcs and Relational Statements. 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.

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

In XDI dictionaries, relational statements are used to define the domain and range of XDI predicates. The empty inner graph (/) is the relation definition predicate.

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 "}"

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.

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

Entity context nodes are either classes or instances. Class node identifiers are always immutable, so they do not use the immutability symbol !. Instance node identifiers may use both the immutability symbol and the relativity symbol ~.

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 ">"

The rules for attribute context nodes are very similar to the rules for entity context nodes, with the addition of chevron brackets < and > to indicate the attribute role.

xdi-name                = ID_Start *( ID_Continue / "_" / "-" / "." )
pct-encoded             = "%" HEXDIG HEXDIG

Note that the ABNF rule xdi-name covers both XDI names and XDI numbers as defined in XDI Names and Numbers.

An XDI identifier MUST start with a character with the ID_START property defined by the Unicode Identifier and Pattern Syntax [UAX31]. The characters following the ID_START character MUST have the ID_CONTINUE property or be underscore _, hyphen -, or period ..

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 Normalization and Comparison.

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

See XDI Schemes.

The rules in this section have been simplified from [RFC 3987] as sufficient for XDI processors to recognize IRI syntax without intensive verification.

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         = "!" / "$" / "&" / "(" / "*" / "+" / "," / ";" / "="

Note that, in comparison to the sub-delims rule in RFC 3987, the safe-sub-delims rule has removed:

Additional rules for this section:

These rules MUST be applied in addition to the rules in the previous section.

Note that while the implied=0 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.

{
    "/$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/"
        }
    }
}

{
    "//": [
        "<$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/"
        }
    }
}

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.


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.

Note also that a peer root node MUST appear before an inner root node in a sequence that includes both root node types.

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.

The process of determining this consensus is called XDI discovery and is defined by the XDI Discovery specification [XDI-Discovery-V1.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.

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:

Each peer graph for (=example-person) 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:

 =example-person

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:

+example-corp=example-person

This is a contextual description of =example-person in the context of +example-corp, for which +example-corp is authoritative.

In the third example, the peer root (+example-corp) is itself relative to the peer root (+example-consortia). This means it is authoritative for the following XDI address:

+example-consortia+example-corp=example-person

This is a contextual description of =example-person in the context of +example-corp, which in turn is a contextual description in the context of +example-consortia. The first entity in this sequence, +example-consortia, is ultimately authoritative for this entire address.

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.

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.

For more details on XDI discovery, see the XDI Discovery specification [XDI-Discovery-V1.0].

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.

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.

{
    "(=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"
            }
        }
    }
}

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.

{
    "(=alice/=bob)": {
        "#marriage": {
            "/#minister": [
                "=parson-brown"
            ],
            "<$date>": {
                "&": "2010-08-22"
            }
        }
    }
}

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.

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 Link Contracts specification [XDI-Link-Contracts-V1.0].

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 [RFC 4122].

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.

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 ($ and #) MUST use the ! immutability symbol if and only if the XDI authority for that identifier asserts that the identifier is immutable.

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.

The XDI & literal symbol is immutable by definition and MUST NOT use the immutability symbol.

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.

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 [zooko] https://en.wikipedia.org/wiki/Zooko%27s_triangle], the combination of an XDI name/number mapping can effectively “square Zooko’s triangle”.

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.

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.

For example, in each of the following three XDI addresses, the identifier =!:uuid:x-1 identifies the same natural person.

=!:uuid:x-1 
+!:uuid:x-2=!:uuid:x-1 
+!:uuid:x-3+!:uuid:x-2=!:uuid:x-1

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.

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 $ reserved class namespace MUST use the ~ relativity symbol if and only if the XDI authority for that namespace asserts that the identifier is relative.

All identifiers in the $ 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.

+!:uuid:x-4=~alice 
+!:uuid:x-5=~alice

Unlike the previous example, no inference can be made that the person identified by =~alice relative to the first group has any relationship to the person identified by =~alice 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 
+!:uuid:x-4=~alice represents the same unique person in all three.

+!:uuid:x-4=~alice 
+!:uuid:x-5+!:uuid:x-4=~alice 
+!:uuid:x-6+!:uuid:x-5+!:uuid:x-4=~alice

This rule holds true even for multiple relative identifiers. For example, in the three XDI addresses below, the combination of 
+!:uuid:x-4=~alice*~phone represents the same unique device in all three.

+!:uuid:x-4=~alice*~phone 
+!:uuid:x-5+!:uuid:x-4=~alice*~phone 
+!:uuid:x-6+!:uuid:x-5+!:uuid:x-4=~alice*~phone

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.

To summarize the rules, an XDI absolute identifier:

An XDI relative identifier:

For absolute identifiers, the XDI name prefix "x-" is reserved for examples and testing and SHOULD NOT be assigned for any other purpose.

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.

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.

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.

Per the rules in the previous section, it follows that:

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.

In all four examples, the rooted address is =alice<#email>. 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.

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.

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.

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.

A public identifier 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 Link Contracts specification [XDI-Link-Contracts-V1.0].

A private identifier is an XDI identifier that requires a non-public link contract in order to access its XDI discovery information.

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.

A special XDI context, $anon, 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 specification [XDI-Privacy-V1.0].

The ability to support both public and private identifiers—and for private identifiers to use $rep 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 [pbd].

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.

However, for percent-encoded bytes in %XX format, the two hex digits SHOULD be upper case ABCDEF, not lower case abcdef.

XDI identifiers SHOULD be in Unicode Normalization Form NFKC. [UAX15] Most existing Unicode text meets this criterion.

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:

To normalize an IRI prior to encapsulation, the following steps MUST be performed in order and exactly once (since they are not idempotent).

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).

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.

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 [httprange14].

Transforming an XDI address identifying an XDI graph node into a valid IRI identifying a World Wide Web resource address requires two steps:

To normalize the XDI address, the following steps MUST be performed in order and exactly once (since they are not idempotent).

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).

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 [RFC 3987]. 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 xdi.

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:

=alice<#email>

If the base IRI for the XDI endpoint hosting this XDI address is:

http://xdi.example.com/ 

Then the resulting fully qualified IRI would be:

http://xdi.example.com/%3Dalice%3C%23email%3E 

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:

=alice*some%20pet%20name 

When normalized and appended to the same base URI above, the fully qualified IRI would be:

http://xdi.example.com/%3Dalice%2Asome%2520pet%2520name

UUIDs as defined by RFC 4122 [RFC 4122] 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.

As defined in the XDI ABNF, the XDI UUID scheme name is :uuid:. 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.

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.

The XDI CID scheme family is reserved for identifiers with cryptographic properties. As defined in the XDI ABNF, the XDI CID scheme prefix is :cid-:. 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 Cryptography specification.