RDF API Convergence - Perl

Mailing List (join)
References


Note: These pages has been produced in collaboration with Devon Smith and now mirrored here by Alberto Reggiori as backup copy.

Proposed Base API:
For the base API, only entities actually mentioned in RDFMS-5 are used

PackageISAMembers, Methods, Notes
RDF::Literal
 
  • label()
    Set/Get the label for the Literal
RDF::Resource 
  • uri()
    Set/Get the URI of the Resource
  • namespaces()
    Returns a reference to an array of all the namespaces of all the Properties for this Resource
  • addPredicate(p,o)
    Add a predicate to this Resource. p is a Property and o is a Resource or Literal.
  • getPredicates(p?)
    Returns a Bundle of Statements with this Resource as the subject, and the given Property, if supplied. If the Property is not supplied, all Statements with this Resource as subject will be in the Bundle.
RDF::PropertyRDF::Resource
  • namespace()
    Set/Get the namespace for the Property
Note: addPredicate and getPredicates must be overridden to return undef.
Note: See Below
RDF::Statement 
  • subject()
    Set/Get the subject of the Statement.
  • property()
    Set/Get the property of the Statement.
  • object()
    Set/Get the object of the Statement.
  • addPredicate(p,o)
    add a predicate to the Statement. Calling this method implies reification of the Statement.
  • getPredicates(p?)
    Returns a Bundle of Statements with this Statement's reification as the subject, and the given Property, if supplied. If the Property is not supplied, all Statements with this Statement's reification as subject will be in the Bundle.
RDF::BagRDF::Resource
  • add(Resource)
    Adds Resource to the container.
  • remove(x)
    Removes element x from the container and returns it.
  • disclose(x)
    Returns element x without removing it.
  • contents()
    Return an array ref to the contents of the container.
RDF::SequenceRDF::Resource
  • add(Resource, x)
    Adds Resource to the container at index x, or at the end if x is undefined
  • remove(x)
    Removes element x from the container and returns it.
  • disclose(x)
    Returns element x without removing it.
  • first()
    Returns the first element, without removing it
  • last()
    Returns the last element, without removing it.
  • contents()
    Return an array ref to the contents of the container.
  • push, pop, shift, unshift
    like Perl's builtins.
RDF::AlternativeRDF::Resource
  • add(Resource)
    Adds Resource to the container.
  • remove(x)
    Removes element x from the container and returns it.
  • disclose(x)
    Returns element x without removing it.
  • contents()
    Return an array ref to the contents of the container.
  • preferred()
    Returns the preferred Resource
Note: "An Alt container is required to have at least one member. This member will be identified by the property _1 and is the default or preferred value."3.2 [RDFMS]
Comments:
For Literal, Resource, Property and Statement, an instance is a member of the respective set. For Bag, Sequence and Alternative, an instance is a member of Resource, of the respective container type. Bag, Sequence and Alternative are expected to maintain ordered collections of Resources and/or Literals.

Bundle API Extension: See the Bundle Spec
PackageISAMembers, Methods, Notes
RDF::Bundle 
  • add(x) : x is Literal, Resource or Statement
  • addTriple(s,p,o) : s is Resource, p is Property, o is Resource or Literal
  • addResource(RDF::Resource)
  • addLiteral(RDF::Literal)
  • addStatement(RDF::Statement)
  • addPerResource(p,o)
    For each Resource in the Bundle, add a Statement with the Resource as subject, and the given Property and Object.
  • namespaces()
    Returns a reference to an array of all the namespaces of all the Properties in the Bundle.
  • remove(x)
    Removes element x from the Bundle, if it's present. x is not an index, but a Literal, Resource or Statement.
  • resources()
    Returns a reference to an array of the Resources in the Bundle
  • literals()
    Returns a reference to an array of the Literals in the Bundle
  • statements()
    Returns a reference to an array of the Statements in the Bundle
  • contents()
    Returns a reference to an array of all the elements of the Bundle
  • find(s,p,o)
    Returns a Bundle containing the specifed subject, property and object. Any or all of them may be undef.

Other Possible API Extensions:
PackageISAMembers, Methods, Notes
RDF::LiteralCollection   
RDF::ResourceCollection   
RDF::PropertyCollection   
RDF::StatementCollection   
RDF::Storage::*  For various storage implementations.
RDF::Parser::*  For parsers.
RDF::Agent::*
(RDF::Peer::*)
(RDF::Query::*)		  For Peer 2 Peer operations. Could be equivilant to, or basis for, SemWeb::UserAgent.
RDF::Namespace  For the rdf and rdfs namespaces and their properties, classes etc.
RDF::Namespace::*  For other namespaces and their properties, classes etc.
RDF::Namespace::Map  For namespace prefix <-> namespace URI mapping.
  1. getURIs()
    Returns an array of URIs (as strings) contained in this NamspaceHandle.
  2. getURI($prefix)
    Returns the URI corresponding to the prefix $prefix. Returns undef iff $prefix is not found in the NamespaceHandle.
  3. getPrefixes()
    Returns an array of prefixes (as strings) contained in this NamspaceHandle.
  4. getPrefix($uri)
    Returns the prefix corresponding to the prefix $prefix. Returns undef iff $uri is not found in the NamespaceHandle.
  5. tryToAdd($prefix,$uri)
    Try to add the pair ($prefix,$uri) to the NamespaceHandle. There are different cases:
    1. if the pair($prefix,$uri) is already contained in the NamespaceHandle, it returns true.
    2. elsif $prefix is already contained in the NamespaceHandle, it returns undef.
    3. elsif $uri is already contained in the NamespaceHandle, the old prefix is overwritten and true is returned.
    4. elsif the pair ($prefix,$uri) is added to the NamespaceHandle and true is returned.
    NOTE: $prefix must be a valid prefix in the sense of the XML Namespace specification. THIS IS CURRENTLY NOT ASSUMED TO BE TESTED BY AN IMPLEMENTATION OF NamespaceHandle. (But we should do this in the future ;-)
  6. delete($uri)
    Deletes the pair with URI $uri from the NamespaceHandle. Returns undef on failure.
RDF::Digest::*  For hashing functionality.

Comments:

Anonymous Resources:
The uri() method of an anonymous resource will return undef. Anonymous resources will be distinguished internally by the value of ref($resource) "$resource".

Reified Statement URIs:
The URI for a reified statement resource must be unique. This isn't a problem, however, as every statement is unique. These URIs will match the pattern /^urn:x-rdf:statement:[\dA-Fa-f]{40}$/. The use of the namespace ID "x-rdf" signifies that this scheme is experimental. This use is consistent with RFC 2611 [1]. The section after the last colon will be a hex representation of the "statement digest". The statement digest will be constructed as follows:

  1. The SHA-1 digest of the subject URI will be concatenated onto the SHA-1 digest of the property URI.
  2. If the object is a Literal, a string consisting of the object's SHA-1 digest followed by the string "lit" will be concatenated onto the end of the string resulting from step 1.

    If the object is a Resource, a string consisting of the object's SHA-1 digest followed by the string "res" will be concatenated onto the end of the string resulting from step 1.

  3. The statement digest will be the SHA-1 digest of the string resulting from the above steps.
    i.e. statement digest = SHA( property_digest . subject_digest . object_digest . (res|lit))
The hex representation will be done high nybble first. (That means use 'H' in un/pack.)

Reified Bundle URIs:
???

Type Safety:
How type safe should the API be?
Since we're working in Perl, we'd like to be as forgiving as possible. Ideally, methods that are expecting a Resource will accept an RDF::Resource, a URI or a scalar. For Subjects, it's pretty simple, because it's always a uri at heart. For Properties and Objects, though, the situation becomes a little stickier. Every Property has a namespace with which it is associated. RDF::Property keeps track of the Property name and it's namespaces, but a plain scalar doesn't. And there currently is no agreement on how names and their namespaces are delineated. So if a scalar is passed into a method in place of an RDF::Property, the API has no way of knowing where the namespace ends and the name begins. With Objects, a scalar should imply a Literal, but problems could arise if people pass scalar uris that end up being interpreted as Literals.

  Properties:
A Property will have a namespace and a URI. The namespace need not be a URI and neither need be retrievable. The Property constructor will take two arguments. The first will be the namespace. The second, if it is a URI object or URI string, will be considered the complete URI of the Property. If the second argument is not a URI, then the URI will be formed by concatenating the name (second argument) onto the namespace. If the resulting string is still not a URI, then it will be an error and the constructor will return undef. The namespace() method will simply get/set the Property's namespace. The uri() method with no parameters will return the Property's URI. With a parameter, it will set the URI of the Property following the same algorithm as the constructor.

References:
[1] URN Namespace Definition Mechanisms

Devon Smith (smithde)(at)(oclc dot org)
Online Computer Library Center (http://www.oclc.org)
Created: 2001-05-31