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

About

This page defines common XDI dictionary patterns that lay the foundation for the XDI 1.0 Dictionary specification (see the XDI 1.0 specification list). The patterns defined here are based on the XDI Dictionary Requirements proposal.

Change Log

Introduction

XML has schemas, RDF has ontologies, XDI has dictionaries. Dictionaries are XDI graphs that define the schema/ontology rules that other XDI graphs may follow in order to conform with that dictionary.

Just as a natural language document may be grammatically correct without using words that are published in a dictionary, an XDI graph may be valid without conforming to any particular dictionary. An XDI graph may also contain subgraphs that conform with multiple different dictionaries. An XDI graph may also include its own dictionary definitions, just as an natural language document may contain the definition of words used in that document.

Dictionary Syntax

A dictionary definition MUST conform to XDI dictionary syntax as defined in the XDI Core ABNF. The basic rule is that all dictionary contexts must be enclosed in vertical lines (UTF-8 U+007C) | |. Examples:

RESERVED ENTITY DEFINTION         |$word|
RESERVED ATTRIBUTE DEFINITION     |<$word>|
GENERIC ENTITY DEFINITION         |#word|
GENERIC ATTRIBUTE DEFINITION      |<#word>|
LOCAL ENTITY DEFINITION           |#~word|
LOCAL ATTRIBUTE DEFINITION        |<#~word>|

Where:

Specializing Dictionary Definitions

To specialize a definition, it is defined within the context of another definition. Example patterns:

SPECIALIZED GENERIC ENTITY DEFINITION    |#word1||#word2|
SPECIALIZED LOCAL ENTITY DEFINITION      |#~word1||#~word2|
MIXED GLOBAL/LOCAL SPECIALIZATION        |#word||#~word|
MIXED LOCAL/GLOBAL SPECIALIZATION        |#~word||#word|

A simple example is specializing the generic definition of a phone number by putting it in the context of a specific country:

|#gb||$country||<#tel>|
|#fr||$country||<#tel>|

In English this would read, "UK country telephone number" and "French country telephone number". Note that the |#gb| and |#fr| specialize the keyword |$country|, so their semantic meaning as country codes is particular to this exact context.

Entity Definitions

To define that an entity contains another entity, use a contextual statement to assert the definition of the child entity in the context of the definition of the parent entity. For example, to define that a car contains an engine and wheels:

|#car|//|#engine|
|#car|//|#wheel|

This pattern can be repeated as deeply as needed. For example:

|#car||#engine|//|#carburetor|

Attribute Definitions

To define an attribute of an entity, use a contextual statement to assert the definition of the attribute in the context of the definition of the entity. For example, to define that a passport has a passport number:

|#passport|//|<#num>|

To define an attribute of another attribute, repeat the same pattern. For example, to define that a passport number attribute has a checksum attribute:

|#passport||<#num>|//|<#checksum>|

Subtypes and Supertypes

To define that an entity is a subtype of another entity, use the $is# relation (# is the context symbol for class or type, and $is# is its inverse). In XDI this is the semantic equivalent of the object inheritance relationship is-a. For example:

|#car|/$is#/|#vehicle|
|#passport|/$is#/|#credential|

To define that an entity is a supertype of another entity, use the # relation. For example:

|#vehicle|/#/|#car|
|#vehicle|/#/|#boat|
|#vehicle|/#/|#train|
|#vehicle|/#/|#plane|

The same patterns apply to attributes. For example, to define that a passport number is a type of JSON number and a passport name is a JSON string:

|#passport||<#num>|/$is#/|<$number>|
|#passport||<#name>|/$is#/|<$string>|

The XDI keywords proposed to represent the native JSON data types in dictionary type statements are:

  1. <$boolean>

  2. <$string>

  3. <$number>

  4. <$object>

  5. <$array>

Since JSON is the native XDI serialization format, those keywords do not require any additional context. To represent the native XML data types and the IETF MIME data types, the proposed root context keywords are:

It is anticipated that the XDI Dictionary 1.0 spec will include algorithms for deriving the full XDI keyword set for native XML and MIME data types from the official type names published by the W3C and IETF.

Multiplicity of Entities or Attributes

To define the multiplicity of an entity or attribute definition, use the multiplicity attribute <$n>.

The literal value of the multiplicity attribute is a string that expresses the multiplicity constraint on the relationship of the described entity or attribute to its parent entity or attribute. The formal ABNF rules for multiplicity expressions will be defined in the XDI Dictionary 1.0 specification, but the basic pattern is modeled after multiplicity in UML. For example:

For example, to define that a car has exactly one engine but three or four wheels:

|#car||#engine|<$n>/&/"1"
|#car||#wheel|<$n>/&/"3-4"

To define that a passport has exactly one number attribute and one name attribute:

|#passport||<#number>|<$n>/&/"1"
|#passport||<#name>|<$n>/&/"1"

Note that for a multiplicity of exactly one, or zero or one, instances will be singletons. For any other multiplicity, instances will be members of a collection.

XBNF

XBNF (XDI BNF) is a very simple variant of ABNF which enables an XDI attribute definition to include ABNF validation rules for the literal value. Because XBNF makes every ABNF rule XDI-addressable, XBNF also allows ABNF rules to be reused across XDI dictionary definitions. See the XBNF page for the specification and examples.

Regex

It is also planned for XDI Dictionary 1.0 specification to define a <$regex> attribute for specifying a regular expression that can be used to validate the literal value of an attribute. The specification will include the regex language(s) supported and the regex encoding rules.

Relations, Domains, and Ranges

To define the valid relations for an entity or attribute within an XDI graph, use the relation predicate (/). For example:

|#car|/(/)/|#driver|
|#car|/(/)/|#owner|
|#car|/(/)/|#insurer|
|#person|/(/)/|#eat|
|#cat|/(/)/|#eat|

XDI relations can define both a valid domain (subject) and a valid range (object) for the relation just like RDF properties. For example, the above statements define that #car is a valid domain for the relations #driver, #owner, and #insurer, and that #person and #cat are valid domains for the relation #eat.

To make the inverse statements from the standpoint of the relation, use the inverse predicate $is(/).

|#driver|/$is(/)/|#car|
|#owner|/$is(/)/|#car|
|#insurer|/$is(/)/|#car|
|#eat|/$is(/)/|#person|
|#eat|/$is(/)/|#cat|

To specify the valid range (XDI object) of a relation, use the (/)# predicate:

|#driver|/(/)#/|#person|
|#owner|/(/)#/|#person|
|#owner|/(/)#/|#company|
|#insurer|/(/)#/|#company|
|#eat|/(/)#/|#food|

To make the inverse statements from the standpoint of the object, use the inverse predicate $is(/)#.

|#person|/$is(/)#/|#driver|
|#person|/$is(/)#/|#owner|
|#company|/$is(/)#/|#insurer|
|#food|/$is(/)#/|#eat|

Multiplicity of Relations

To define the multiplicity of a relation, use the same multiplicity attribute <$n> used with entity or attribute definitions. The only difference it that this attribute must describe the inner graph formed by the subject definition and the relation definition, since it is an attribute of this relationship. For example:

(|#car|/|#driver|)<$n>/&/"1"
(|#person|/|#mother|)<$n>/&/"1"
(|#person|/|#father|)<$n>/&/"1"
(|#person|/|#friend|)<$n>/&/"0-n"
(|#person|/|#best||#friend|)<$n>/&/"0-1"

To define a semantic relationship between one XDI dictionary definition and another — the semantic equivalent of "See also" — use the relation $rel. For example:

|#passport|/$rel/|#visa|
|#passport|/$rel/|#identity||#card|
|#passport|/$rel/|#driver||#license|

Other Non-Functional Dictionary Definition Attributes

In addition to the functional dictionary statements described above, XDI dictionary definitions may include the following attributes for human readability and navigation.

Labels

To define a human-readable label for a dictionary definition, use the attribute <$label>. For example:

|#passport|<$label>/&/"passport"

Note that labels may be internationalized following the same pattern as other XDI specializations. Examples:

|#passport|<#en><$lang><$label>/&/"passport"
|#passport|<#fr><$lang><$label>/&/"passeport"
|#passport|<#es><$lang><$label>/&/"pasaporte"

Note that <$lang> is specialized by generic tags corresponding to IETF language tags.

Descriptions

To define a human-readable description for a dictionary definition, use the attribute <$desc>. For example:

|#passport|<$desc>/&/"An official document which proves the identity and nationality of the person for whom it was issued."

Descriptions may be internationalized the same way as labels.

Keywords

To define keywords that can be used to do a natural language search for a dictionary definition, use the attribute collection [<$keyword>]. For example (with abbreviated UUIDs for illustration):

|#passport|[<$keyword>]!:uuid:x-1/&/"credential"
|#passport|[<$keyword>]!:uuid:x-2/&/"governmental document"
|#passport|[<$keyword>]!:uuid:x-3/&/"official document"
|#passport|[<$keyword>]!:uuid:x-4/&/"visa"
|#passport|[<$keyword>]!:uuid:x-5/&/"identity"
|#passport|[<$keyword>]!:uuid:x-6/&/"nationality"

Common, Community, and Personal Dictionaries

Just as with natural language, XDI dictionary definitions can be created by anyone and specialized by anyone. Definitions fall into the three categories based on the publishing authority:

MUTABLE COMMUNITY DICTIONARY NAME          |+community.name|
IMMUTABLE COMMUNITY DICTIONARY NUMBER      |+!:uuid:x-5|
MUTABLE PERSONAL DICTIONARY NAME           |=personal.name|
IMMUTABLE PERSONAL DICTIONARY NUMBER       |=!:uuid:x-3|

It is RECOMMENDED that community and personal dictionaries use immutable XDI identifiers.

Basic Examples

1) COMMON DEFINITION
"The common definition of 'intention'"
DEFINITION:                                |#intention|
EXAMPLE INSTANCE:                          =!:uuid:x-2#intention

2) COMMUNITY DEFINITION
"A definition of 'intention' in a specific community”
DEFINITION:                                |+!:uuid:x-5||#intention|
EXAMPLE INSTANCE:                          =!:uuid:x-4|+!:uuid:x-5|#intention

3) PERSONAL DEFINITION
"My own personal definition of 'intention'"
DEFINITION:                                |=!:uuid:x-3||#~intention|
EXAMPLE INSTANCE:                          =!:uuid:x-6|=!:uuid:x-3|#intention

Specialization Examples

1) COMMON DEFINITION
"The global definition of 'wizard name'"
DEFINITION:                                |<#wizard>||<#name>|
EXAMPLE INSTANCE:                          =!:uuid:x-7<#wizard><#name>

2) FULL PERSONAL SPECIALIZATION OF COMMON DEFINITION
"My own definition of 'wizard name' based on the global definitions of 'wizard' and 'name'"
DEFINITION:                                |=!:uuid:x-8||<#wizard>||<#name>|
EXAMPLE INSTANCE:                          =!:uuid:x-9|=!:uuid:x-8|<#wizard><#name>

3) PARTIAL PERSONAL SPECIALIZATION OF COMMON DEFINITION
"My own definition of 'wizard', which has a 'name' according to the global definition"
DEFINITION:                                |=!:uuid:x-8||<#~wizard>||<#name>|
EXAMPLE INSTANCE:                          =!:uuid:x-9|=!:uuid:x-8|<#~wizard><#name>

4) FULL LOCAL DEFINITION
"My own definition of 'wizard' and my own definition of 'name'"
DEFINITION:                                |=!:uuid:x-8||<#~wizard>||<#~name>|
EXAMPLE INSTANCE:                          =!:uuid:x-9|=!:uuid:x-8|<#~wizard><#~name>


CategoryDictionary

XdiDictionaryPatterns (last edited 2016-07-30 08:46:11 by drummond)