Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

IdAS XDI Mapping

Revision as of 12:22, 22 August 2008 by Markus.sabadello.gmail.com (Talk | contribs) (Example)

{{#eclipseproject:technology.higgins}} This page documents the mapping between the Higgins Data Model (which is implemented by IdAS) and XDI. XDI ("XRI Data Interchange") is a data model and protocol for sharing, linking, and synchronizing data over the Internet ("structured web") and other networks using Extensible Resource Identifiers (XRIs). It is being developed by the OASIS XDI Technical Committee.

The IdAS XDI Engine exposes an IdAS Context at an XDI endpoint. It processes and applies incoming XDI messages.

The XDI Context Provider implements an IdAS Context by sending XDI messages. These message can be sent either to an XDI endpoint exposed by the IdAS XDI Engine or to a native XDI endpoint.

Mapping

Concepts

Since the Higgins Data Model is based on RDF/OWL, and since XDI is also (conceptually) based on RDF, the basic mapping is straight-forward. However, some attention has to be paid to details.

A Higgins Context can be mapped to an XDI graph using the following rules:

  • An Entity maps to an XDI subject. The XDI subject's XRI is the Entity ID cast to an XRI.
  • An Attribute maps to an XDI predicate. The XDI predicate's XRI is the Attribute ID cast to an XRI.
  • In general, each value of an Attribute maps to an XDI subject inside an XDI inner graph. The XDI subject's XRI is a HIN calculated from the value.
    • If the Value is a Simple Value, then the XDI subject in the XDI inner graph has a single XDI predicate with an XDI literal. The XDI predicate's XRI is the Attribute ID of the Attribute to which the value belongs.
    • If the Value is a Complex Value, then the rules for mapping the Attributes of that Complex Value apply recursively, i.e. each Attribute of the Complex Value maps to an XDI predicate.
  • Special case 1: If an Attribute contains only a single Simple Value, then that Attribute does not need an inner graph. Instead the Value maps directly to an XDI literal on the XDI predicate that represents the Attribute.
  • Special case 2: If an Attribute is a Entity Relation, then that Attribute does not need an inner graph. Instead the Values map directly to XDI references on the XDI predicate that represents the Attribute.
  • An Entity Correlation maps to an XDI statement with the special $is XDI predicate
  • The type of an Entity maps to an XDI statement with the special $is$a XDI predicate

Example

Example Context:

  • The Context has three Entities =paul, =sergey and =drummond.
  • =paul has an Attribute +name, which has a single Simple Value :"Paul T.".
  • =paul has an Entity Relation +friend to =sergey and =drummond.
  • =paul has an Attribute +phone, which has two Values:
    • The first Value is a Simple Value: "+1 (617) 513 7924".
    • The second Value is a Simple Value: "+1 (781) 559 0153".
  • =paul has an Attribute +address, which has three Values:
    • The first Value is a Simple Value: "56 Kearney Rd, Needham, MA 02494".
    • The second Value is a Complex Value. It has four Attributes +street, +city, +state and +zip.
      • The first Attribute has a single Simple Value: "56 Kearney Rd".
      • The second Attribute has a single Simple Value: "Needham".
      • The third Attribute has a single Simple Value: "MA".
      • The fourth Attribute has a single Simple Value: "02494".
    • The third Value is a Complex Value. It has two Attributes +line and +country.
      • The first Attribute has two Simple Values.
        • The first Value is a Simple Value: "56 Kearney Rd".
        • The second Value is a Complex Value: "Needham, MA 2494".
      • The second Attribute has a single Simple Value: "USA".
=paul     <-- An Entity -->
   +name     <-- A "Special Case 1" Attribute -->
      "Paul T."     <-- A single Simple Value -->
   +friend     <-- A "Special Case 2" Attribute -->
      =sergey     <-- An Entity Relation Value -->
      =drummond     <-- An Entity Relation Value -->
   +phone     <-- An Attribute with two Values -->
      /
         $value$hash$sha$256!e5754ab606a4f0d6a3570d2c37c1f75643b9eefccf8e66e27ec77499bea8ae1d     <-- First Value of +phone: A Simple Value -->
            +phone
               "+1 (617) 513 7924"
         $value$hash$sha$256!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca     <-- Second Value of +phone: A Simple Value -->
            +phone
               "+1 (781) 559 0153"
   +address     <-- An Attribute with three Values -->
      /
         $value$hash$sha256!07e8c548c164ea1df063e85d13a5faa04ee2e3129b571ace4360c557ba506a9c     <-- First Value of +address: A Simple Value -->
            +address
               "56 Kearney Rd, Needham, Massachusetts 02494, USA"
         $value$hash$sha256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715     <-- Second Value of +address: A Complex Value with four Attributes -->
            +street     <-- A "Special Case 1" Attribute -->
               "56 Kearnery Rd"     <-- A single Simple Value -->
            +city     <-- A "Special Case 1" Attribute -->
               "Needham"     <-- A single Simple Value -->
            +state     <-- A "Special Case 1" Attribute -->
               "MA"     <-- A single Simple Value -->
            +zip     <-- A "Special Case 1" Attribute -->
               "02494"     <-- A single Simple Value -->
         $value$hash$sha256!da4bb94a2779f74e4995fbb8a83965df2dfb9c91c63ba3a561206c33feb9d324     <-- Third Value of +address: A Complex Value with two Attributes -->
            +line     <-- An Attribute with two values -->
               /
                  $value$hash$sha256!4e8ae563672c68cb1533ae16993a693033f1a9032e43893c3464956b8ec2109c     <-- First Value of +line: A Simple Value -->
                     +line
                        "56 Kearney Rd"
                  $value$hash$sha256!d27ef0bac9a6830121ebc30cd911fa9672a28fa8e8bd5d63ae3ade11af519d32     <-- Second Value of +line: A Simple Value -->
                     +line
                        "Needham, Massachusetts 02494"
            +country     <-- A "Special Case 1" Attribute -->
                  "USA"     <-- A single Simple Value -->
=sergey     <-- An Entity -->
	+name     <-- A "Special Case 1" Attribute -->
		"Sergey"     <-- A single Simple Value -->
=drummond     <-- An Entity -->
	+name     <-- A "Special Case 1" Attribute -->
		"Drummond"     <-- A single Simple Value -->

Hash I-Numbers for Simple Values

On several occasions in this mapping, it is necessary to refer to individual Simple Values of a multi-valued Attribute. Since Simple Values in Higgins IdAS do not have persistent identifiers, a mechanism called "Hash I-Number" (HIN) is used. A HIN is an i-number that is deterministically calculated from a value, therefore acting as an index of that Value in an XDI inner graph.

This pseudocode can be used to calculate a HIN for a Simple Value:

FUNCTION makeSimpleValueHin(simpleValue)

  String hin = "$value$hash$sha256" + "!" + hex(sha256(simpleValue.string));
  RETURN hin;
END

Examples:

  • "Sergey" becomes $value$hash$sha256!f3357799ddcf994ae4d759e37d58c29938419f5af9681ae65a6f0f1677b213b7
  • "Markus" becomes $value$hash$sha256!f00b1896cf1c0569b9bdcfdde4ed948a266bae9707b3567240211efc8ffc06a0
  • "+1 (617) 513 7924" becomes $value$hash$sha$256!e5754ab606a4f0d6a3570d2c37c1f75643b9eefccf8e66e27ec77499bea8ae1d
  • "+1 (781) 559 0153" becomes $value$hash$sha$256!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca

Hash I-Numbers for Complex Values

Hash I-Numbers are also used to refer to individual Complex Values. Like with Simple Values, HINs for Complex Values are calculated from the Value and can then be used as an index of that Value in an XDI inner graph.

This pseudocode can be used to calculate a HIN for a Complex Value:

FUNCTION makeComplexValueHin(complexValue):

  String hin = "$value$hash$sha256" + "!" + hex(sha256(makeComplexString(complexValue)));
  RETURN hin;
END

FUNCTION makeComplexValueString(complexValue):

  String buffer = "";
  Set attributeIdStrings;  # a set of strings representing the attribute ids of this complex value

  FOR EACH attribute IN complexValue.attributes

    attibuteIdStrings.push(attribute.attributeId)
  END

  FOR EACH attributeId IN sort(attributeIdStrings)

    buffer += attributeId + ' ';
    Set simpleValuesStrings;  # a set of strings representing the simple values of this complex value
    Set complexValuesStrings;  # a set of strings representing the complex values of this complex value

    FOR EACH value IN attribute.values

      IF value.isSimple THEN
        simpleValuesStrings.push('"' + value.string + '"' + ' ')
      ELSE IF value.isComplex THEN
        complexValuesStrings.push(makeComplexValueString(value) + ' ')
      END IF
    END FOR

    buffer += concat(sort(simpleValuesStrings));
    buffer += concat(sort(complexValuesStrings));
  END FOR

  RETURN buffer;
END

Examples:

  • For the second value of +address,
    • the result of the makeComplexValueString() function is +city{space}"Needham"{space}+state{space}"MA"{space}+street{space}"56 Kearney Rd"{space}+zip{space}"02494"{space}
    • the result of the makeComplexValueHin() function is $value$hash$sha256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715
  • For the third value of +address,
    • the result of the makeComplexString() function is +country{space}"USA"{space}+line{space}"56 Kearney Rd"{space}"Needham, Massachusetts 02494"{space}
    • the result of the makeComplexHin() function is $value$hash$sha256!da4bb94a2779f74e4995fbb8a83965df2dfb9c91c63ba3a561206c33feb9d324

Note that this mechanism is only used for Complex Values without an Entity ID.

Operations

Using IdAS, a Higgins context can be opened, and operations can be performed on it. The equivalent in XDI is XDI messages (which contain XDI operations).

All XDI examples are in the X3 Simple serialization format. See X3Format for more information about X3 serialization formats.

Entities

List all Entities in the Context

IdAS calls:

Iterator<Entity> entities = context.getEntities(null);

Message sent by the XDI Context Provider to <url>:

=sender
	$get

Reply from the XDI endpoint:

=paul
   +name
      "Paul T."
   +friend
      =sergey
      =drummond
   +phone
      /
         $value$hash$sha$256!e5754ab606a4f0d6a3570d2c37c1f75643b9eefccf8e66e27ec77499bea8ae1d
            +phone
               "+1 (617) 513 7924"
         $value$hash$sha$256!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca
            +phone
               "+1 (781) 559 0153"
   +address
      /
         $value$hash$sha256!07e8c548c164ea1df063e85d13a5faa04ee2e3129b571ace4360c557ba506a9c
            +address
               "56 Kearney Rd, Needham, Massachusetts 02494, USA"
         $value$hash$sha256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715
            +street
               "56 Kearnery Rd"
            +city
               "Needham"
            +state
               "MA"
            +zip
               "02494"
         $value$hash$sha256!da4bb94a2779f74e4995fbb8a83965df2dfb9c91c63ba3a561206c33feb9d324
            +line
               /
                  $value$hash$sha256!4e8ae563672c68cb1533ae16993a693033f1a9032e43893c3464956b8ec2109c
                     +line
                        "56 Kearney Rd"
                  $value$hash$sha256!d27ef0bac9a6830121ebc30cd911fa9672a28fa8e8bd5d63ae3ade11af519d32
                     +line
                        "Needham, Massachusetts 02494"
            +country
                  "USA"
=sergey
	+name
		"Sergey"
=drummond
	+name
		"Drummond"

Get one Entity from the Context

IdAS calls:

IEntity entity = context.getEntity("=markus");

Message sent by the XDI Context Provider to <url>:

=sender
	$get
		/
			=paul

Reply from the XDI endpoint:

=paul
   +name
      "Paul T."
   +friend
      =sergey
      =drummond
   +phone
      /
         $value$hash$sha$256!e5754ab606a4f0d6a3570d2c37c1f75643b9eefccf8e66e27ec77499bea8ae1d
            +phone
               "+1 (617) 513 7924"
         $value$hash$sha$256!b25629ef86f5f6347f90b31225f95872982bc336ebd34c38e6533e0889bf13ca
            +phone
               "+1 (781) 559 0153"
   +address
      /
         $value$hash$sha256!07e8c548c164ea1df063e85d13a5faa04ee2e3129b571ace4360c557ba506a9c
            +address
               "56 Kearney Rd, Needham, Massachusetts 02494, USA"
         $value$hash$sha256!854d3dfca2b7388c160d301ddcad24084280c7d7bf3e2faac607b1c21917a715
            +street
               "56 Kearnery Rd"
            +city
               "Needham"
            +state
               "MA"
            +zip
               "02494"
         $value$hash$sha256!da4bb94a2779f74e4995fbb8a83965df2dfb9c91c63ba3a561206c33feb9d324
            +line
               /
                  $value$hash$sha256!4e8ae563672c68cb1533ae16993a693033f1a9032e43893c3464956b8ec2109c
                     +line
                        "56 Kearney Rd"
                  $value$hash$sha256!d27ef0bac9a6830121ebc30cd911fa9672a28fa8e8bd5d63ae3ade11af519d32
                     +line
                        "Needham, Massachusetts 02494"
            +country
                  "USA"

Remove an Entity from the Context

IdAS calls:

IEntity entity = context.getEntity("=markus");
entity.remove();

Message sent by the XDI Context Provider to <url>:

=sender
	$del
		/
			=markus

Reply from the XDI endpoint: (none)

Attributes

Get one Attribute from an Entity

IdAS calls:

IEntity entity = context.getEntity("=markus");
IAttribute attribute = entity.getAttribute("http://www.example.com/name");

Message sent by the XDI Context Provider to <url>:

=sender
	$get
		/
			=markus
				+(http://www.example.com/name)

Reply from the XDI endpoint:

=markus
	+(http://www.example.com/name)
		/
			$!da649486d19f8cc02350447179637cba604eff46
				+(http://www.example.com/name)
					"Markus"

Remove an Attribute from an Entity

IdAS calls:

IEntity entity = context.getEntity("=markus");
IAttribute attribute = entity.getAttribute(new URI("http://www.example.com/name"));
attribute.remove();

Message sent by the XDI Context Provider to <url>:

=sender
	$del
		/
			=markus
				+(http://www.example.com/name)

Reply from the XDI endpoint: (none)

Simple Values

Remove a Simple Value from an Attribute

IdAS calls:

IEntity entity = context.getEntity("=markus");
IAttribute attribute = entity.getAttribute(new URI("http://www.example.com/email"));
IAttributeValue value = attribute.getValues().next().next();	// value is "msabadello@parityinc.net"
value.remove();

Message sent by the XDI Context Provider to <url>:

=sender
	$del
		/
			=markus
				+(http://www.example.com/email)
					/
						$!710e4214a22c1840fc7a829b1c3fd32375e9efca	<-- HIN of msabadello@parityinc.net -->

Reply from the XDI endpoint: (none)

Change a Simple Value of an Attribute

IdAS calls:

IEntity entity = context.getEntity("=markus");
IAttribute attribute = entity.getAttribute(new URI("http://www.example.com/email"));
Iterator<IAttributeValue> values = (Iterator<IAttributeValue>) attribute.getValues();
IAttributeValue value = values.next();	// current value is "markus.sabadello@gmail.com"
((ITypedValue) value).setData("markus@changedemail.com");

Message sent by the XDI Context Provider to <url>:

=sender
	$del
		/
			=markus
				+(http://www.example.com/email)
					/
						$!546de0b559ddcdb45983fd901f8d665ecc795e6e	<-- HIN of markus.sabadello@gmail.com -->
	$add
		/
			=markus
				+(http://www.example.com/email)
					/
						$!6ea54708b267b24988beca6adc34c4e79ed0a0b5	<-- HIN of markus@changedemail.com -->
							+(http://www.example.com/email)
								"markus@changedemail.com"

Reply from the XDI endpoint: (none)

Add a Simple Value to an Attribute

IdAS calls:

IEntity entity = context.getEntity("=markus");
IAttribute attribute = entity.getAttribute(new URI("http://www.example.com/email"));
attribute.addSimpleValue(new URI(""), "markus@newemail.com");

Message sent by the XDI Context Provider to <url>:

=sender
	$add
		/
			=markus
				+(http://www.example.com/email)
					/
						$!690e082dc615d636abdaae2b066bdbf7e2b70057	<-- HIN of markus@newemail.com -->
							+(http://www.example.com/email)
								"markus@newemail.com"

Reply from the XDI endpoint: (none)

Complex Values

Remove a Complex Value from an Attribute

IdAS calls:

IEntity entity = context.getEntity("=markus");
IAttribute attribute = entity.getAttribute(new URI("http://www.example.com/friend"));
IAttributeValue value = attribute.getValues().next();	// value is "=sergey"
value.remove();

Message sent by the XDI Context Provider to <url>:

=sender
	$del
		/
			=markus
				+(http://www.example.com/friend)
					=sergey

Reply from the XDI endpoint: (none)

Add a Complex Value to an Attribute

IdAS calls:

IEntity entity = context.getEntity("=markus");
IAttribute attribute = entity.getAttribute(new URI("http://www.example.com/friend"));
attribute.addComplexValue(new URI(""));
/* ... */

Message sent by the XDI Context Provider to <url>:

=sender
	$add
		/
			=markus
				+(http://www.example.com/friend)
					=sergey

Reply from the XDI endpoint: (none)

Miscellaneous

Get the schema of the Context

IdAS calls:

String schema = IContext.getSchema();

Schema support in IdAS maps to XDI dictionary statements.

TODO

Get Context Relations and Context Correlations

IdAS calls:

IContext.getRelationships() 

TODO

Authentication

The Higgins authentication materials needed to open an XDI context are:

  • A Sender XRI (i-name or i-number)
  • A Private Key which is used to sign all messages

Example:

=sender
	$get
		/
			=markus
				+(http://www.example.com/name)
	$sig$rsa
		"bCbYq6EN26N1hdJTtrjvHw05X+MtNzyFKuyPMoEX/nHxzotTAlGDfHqGuUGMgWIrAtFBkre+bbrUA07gjb6do8kr5OsmOKYvfEi/rxnbEhlEPfISEP5/SWJ8auc+W8E6TOPK2bBTxTrt4+5JGIE4TjiP1IZe9l85rqOmeAY5TLZkFzxGanD01Jf4EbB8qDdNjVsQSZgW0zcqyAdi7/quqTLesxLM9m340doFdHhJxW0cdVLS5CjBU67TR1uDSMEfMpqQhEp8qfQaD/0dUif5Wr5/q+L8nz9BsBQ9tzfFhUSATYMaL1whNNWHEpoO/OGKQPADv/PJbsbN7T3dwyjlBA=="

Access control

Access control in IdAS maps to XDI link contracts.

TODO

Notifications

Notification support in IdAS maps to XDI links contracts.

TODO

Filters

Filter support in IdAS maps to XDI queries.

On the OASIS XDI TC there was a proposal for an XDI query language. The idea is simple: You send a $get and replace everything you don't know with $$. So if you want to have all attributes with a name attribute that has a value of "Sergey", you would do:

Message sent by the XDI Context Provider to <url>:

=sender
    $get
        /
            $$  <-- we don't know the subject -->
                +(http://www.example.com/name)
                    /
                        $$
                            +(http://www.example.com/name)
                                "Sergey"

Reply from the XDI endpoint:

=sergey    <-- that's what matched the $$ -->
    +(http://www.example.com/name)
        /
            $!11cac773045ffc189fa2e3ed232843d363d019c6
                +(http://www.example.com/name)
                    "Sergey"

This can be tested with the XDI Querier.

Links

  • Higgins Home
  • The XDI RDF Model is the current OASIS TC proposal for an RDF-based data model and addressing format for XDI. This document includes the proposed XDI RDF schema and a number of examples of XDI documents. (Note that it does not yet include the proposed XDI messaging format, which uses XDI documents as message envelopes for other XDI documents.)
  • OASIS XDI TC Wiki
  • Wikipedia page on XDI

Copyright © Eclipse Foundation, Inc. All Rights Reserved.