XDI - Messaging client for XDI servers
Version 0.01
use XDI; my $xdi = new XDI; .. my $iname = '=tester'; my $xdi = XDI->new($iname); .. my $hash = { 'from' => '=tester', 'from_graph' => '@xdiserver' }; my $xdi = XDI->new($hash);
pick_xdi_tuple
XDI is an open standard semantic graph model, data sharing format, and protocol.
Details on XDI can be found at https://wiki.oasis-open.org/xdi/FrontPage
XDI graphs are addressed via inames/inumbers which conform to the generic URI syntax as defined in IETF RFC 3986. inames resolve to inumbers. inames can be re-assigned while inumbers are permanent identifiers
=markus # individual context =!91F2.8153.F600.AE24 @xdi # institutional context @!3D12.8C35.6FB3.E89C
An experimental service to provide XDI iname/inumber resolution is http://xri2xdi.net/index.html
CRUD permissions to an XDI database are defined by link contracts. Link contracts define a permission ($get,$add,$mod,$del) for a graph node and who has that permission
The XDI perl module provides a client for communicating with XDI servers.
$xdi Root object defining identity of querier $c Connection object defining graph target and permissions $msg Message object for XDI messages $hash Reference to a hash of key/attribute values
All XDI communications are between two graph entities, these are defined by inames/inumbers Identity verification and authority are still being developed under the XDI specification so this module allows the user to self-assert
use XDI; $xdi = XDI->new('=tester');
This constructor assumes that the user making the query from is the same as the graph from which the query is being made from_graph. If you were implementing an XDI service that mediated queries on behalf of a user, it would be appropriate to set the from_graph to the identity of the service
$xdi = XDI->new({from => '=tester', from_graph => '@kynetx' });
To specify the graph to which you would like to query, you create a XDI::Connection
$c = $xdi->connect();
This is the primary method for creating a Connection object so that it can access the fields of the XDI object.
You can pass any XDI::Connection initialization parameters to connect()
connect()
$hash = { target => E<lt>iname|inumberE<gt>, # eg: =my_personal_cloud secret => $secret }; $c = $xdi->connect($hash);
Given an iname, the default behavior for XDI is to attempt to resolve the iname to it's corresponding inumber using the iname resolution service at xri2xdi.net. This service also returns the URI to the graph that is authoritative for said iname, during testing and development that often proves inconvenient so you can override this behavior
$c->resolve(0);
Of course, if you do that, you will have to specify the URI of the graph to which you are sending a query
$c->server("http://example/=my_personal_cloud");
You may have noticed that we haven't actually connected to anything yet. I reserve the right to make checking the target graph for a valid link contract part of the connection process
XDI security policy is currently under discussion by the XDI Technical Committee so the placeholder for a more robust policy is to use a shared secret. Please note that the policy allows for arbitrarily complex expressions and Javascript is proposed for the expression syntax. https://wiki.oasis-open.org/xdi/XdiPolicyExpression As the policy matures, I expect to need to update the client
Next step is to create an XDI::Message object
$msg = $c->message();
As usual, you can pass valid message constructor parameters to XDI::Connection::message
$hash = { link_contract => '=!1111' };
The link_contract is the address of the node to which you have permissions. Note that you not only have to have permission to that node, but you have to have permission to execute your operation ($get,$mod,$add,$del,$all)
link_contract
The process of a external party negotiating a link contract is still under development so an XDI server has the option of not enforcing link contracts. In such case, leave the link_contract parameter undefined and that statement will not be included as part of the message. More information on link contracts can be found at XDI::Message
Compose the message that you intend to send to the target graph
$msg->get('=!1111+tel');
An XDI message can only contain one type of operation, so it is an error to try to mix operations in a message, but it is possible to send multiple statements of the same operation
$msg->get('=!1111+tel'); $msg->get('=!1111+email'); $msg->get('=!1111+birthdate');
Each one of these operations composes an XDI statement. There is no order of execution for statements in a message. This has little consequence for $get operations, but needs to be taken into consideration for $add and $mod operations
Once the message is composed, use the XDI::Connection object to post the message to the target graph post performs an http post request to the server with the XDI message in the body.
post
$graph = $c->post($msg);
The result is a JSON encoded representation of the nodes requested in the $get operation. Other operations will return an empty hash {} upon success. Default behavior is to automatically convert the JSON to a perl hash object
XDI and it's members support the common PERL OO-style syntax via AUTOLOAD
$xdi = XDI->new($iname); $xdi = XDI->new({ 'from' => '=tester, 'from_graph' => '@server' }); $xdi = XDI->new($ref);
Constructs a new XDI object. Optional arguments consist of either a single iname|inumber string or a list of field => value pairs. The single argument will default values of from and from_graph to the same value.
$xdi->from() $xdi->from($val)
Get/set from value. from is the identity of the entity making the XDI request
from
$xdi->from_graph() $xdi->from_graph($val)
Get/set from_graph value. from_graph is the identity of the graph that is making the XDI request. In the case of a PERL client, the distinction between from and from_graph may be negligible, but could be significant when issues of authorized access via signed messages are implemented
from_graph
$c = $xdi->connect() $c = $xdi->connect($hash)
This method returns a XDI::Connection object. Any parameters passed to the method will be used to invoke the XDI::Connection constructor.
$tuple = pick_xdi_tuple($graph,[I<$subject>,I<$predicate>,I<$object>])
$graph is a perl hash object as returned by $c-post($msg)>
$graph
$c-
$subject,$predicate,$object are optional matching arguments (strings) used to match the returned tuple Any one or two of the parameters may be undef. Only the first matching tuple is returned
undef
pick_xdi_tuple returns an array reference [$subject,$predicate,$object]
$tuples = tuples($graph,[I<$subject> | I<regex>,I<$predicate> | I<regex>,I<$object> | I<regex>])
tuples returns an array of array references. Any of the match elements can be substituted with a regular expression.
Usually the third element of the tuple is an array. If there is only 1 element to the array, the element is substituted for the array of 1 element
get_literal($graph,I<$key>) get_literal($graph,I<@key>)
get_literal is a convenience function to pull literals (subject/!/literal) from the graph. A single key or an array of keys is a valid parameter
If an array of keys @key is used, all of the values are placed into a single array that is returned
get_equivalent($graph,$key)
get_equivalent is a convenience function to pull equivalance expressions (subject/$is/equivalent) from the graph.
get_property($graph,$key)
get_property is a convenience function to pull properties of subject (subject/()/property) from the graph.
get_context($graph,$key)
get_context is a convenience function to pull the contexts of definitions (+(+def)/$is()/[...]]) from the graph.
Mark Horstmeier <solargroovey@gmail.com>
Copyright (C) 2007-2012 Kynetx, Inc.
The perl XDI client is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
To install XDI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm XDI
CPAN shell
perl -MCPAN -e shell install XDI
For more information on module installation, please visit the detailed CPAN module installation guide.