RDF API Convergence

Package	ISA	Members, 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::Property	RDF::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::Bag	RDF::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::Sequence	RDF::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::Alternative	RDF::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

Package	ISA	Members, 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:

Package	ISA	Members, 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. getURIs() Returns an array of URIs (as strings) contained in this NamspaceHandle. getURI($prefix) Returns the URI corresponding to the prefix $prefix. Returns undef iff $prefix is not found in the NamespaceHandle. getPrefixes() Returns an array of prefixes (as strings) contained in this NamspaceHandle. getPrefix($uri) Returns the prefix corresponding to the prefix $prefix. Returns undef iff $uri is not found in the NamespaceHandle. 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 ;-) delete($uri) Deletes the pair with URI $uri from the NamespaceHandle. Returns undef on failure.
RDF::Digest::*		For hashing functionality.

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:

The SHA-1 digest of the subject URI will be concatenated onto the SHA-1 digest of the property URI.
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.
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.

RDF API Convergence - Perl