Copyright Hewlett-Packard, Ontopia 2003. Distribution policies are governed by the W3C intellectual property terms.
This document describes a simple network interface to remote RDF models. There are two sets of functionality: a basic access mechanism that provides query capability to a collection of RDF statements, and an update mechanism where, subject to security constraints (not discussed here), changes to the RDF model can be made. Simple network APIs encourage implementation because of the minimal burden on the implementer. This document also covers are two implementations, one based on SOAP, one based directly on HTTP.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. The latest status of this document series is maintained at the W3C.
By publishing this document, W3C acknowledges that Hewlett-Packard has made a formal submission to W3C for discussion. Publication of this document by W3C indicates no endorsement of its content by W3C, nor that W3C has, is, or will be allocating any resources to the issues addressed by it. This document is not the product of a chartered W3C group, but is published as potential input to the W3C Process. Publication of acknowledged Member Submissions at the W3C site is one of the benefits of W3C Membership; please consult the complete list of acknowledged W3C Member Submissions.
A list of current W3C Recommendations and other technical documents can be found at http://www.w3.org/TR/. W3C publications may be updated, replaced, or obsoleted by other documents at any time.
In order for the semantic web to work it is advantageous that there is standardisation in the protocol that is used for interchanging semantic web data. Semantic web data is primarily concerned with the creation, querying and processing of RDF. While RDF can be interchanged via XML syntax there is no defined protocols for accessing, creating and querying RDF models in a distributed environment. This paper proposes a generic RDF Net API that can be implemented by any service that wishes to expose RDF to client applications. These client applications then have a known and reliable protocol with which they can create, process and query RDF in the web environment.
This paper presents a simple protocol for accessing, querying and modifying a remote RDF model. The paper is split into three sections. The first section defines a set of abstract operations that explain the protocol and expected behaviour in an implementation independent way. The next two sections, 'Soap binding' and 'HTTP Binding' define how concrete implementations work using different transport mechanisms.
This section describes each service operation and its relation to an underlying RDF model. This document does not describe the way in which this service should be implemented but it does define the expected behaviour. The intended usage is that client applications (which could be other servers) can connect to an RDF NetAPI service and use the following set of operations to interact with it.
The set of operations we define are generic RDF Model operations. The operations are completely generic and in no way support domain-specific or schema-specific operations. A layer on top of the RDF NetAPI could provide schema specific operations.
This specification does not prescribe or prohibit any RDF Net API compliant server from performing inferencing or any other additional computational processes as part of any operation defined. The only restriction to this is that any additional processing must not contradict any specific semantics defined by the operation.
The query operation allows for servers to implement different RDF query languages. It is assumed that properties returned by the 'options' operation would indicate which query languages are supported by a given service.
The operation takes four paramters, the model reference, the actual query, the query language under which the query should be evaluated and the format of the query results.
We do not define the specific semantics for this operation except to say that the return value is a set of statements. This is because this operation is intended to allow specific implementations to provide unique and varying querying facilities.
The QueryLanguage parameter indicates which query language interpreter should be used. The ResultsFormat parameter indicates the form of the results where there are alternatives possible.
Op-Prototype:
query(ModelReference, Query, QueryLang, ResultsFormat) => StatementSet
ModelReference: Reference to the target model for this operation
Query: The query to be executed
QueryLanguage: Indication of the query language
ResultsFormat: Indication of the format of the results
to be returned as a set of statements
StatementSet: Set of statements returned
ModelReference: there may be many models hosted by a service so an operation needs to indicate which model is the target. This may be implicit in the request or explicitly stated. For the two protocol bindings below, it is explicitly stated.
QueryLanguage: in order to process the query, the language it is written in needs to be identified
ResultsFormat: some query languages provide alternative forms of their results (e.g. matching subgraph or an RDF encoded set of variable bindings).
This is a special case of the query operation which is explicitly recorded in the abstract service definition to encourage a basic, common access operation.
Op-Prototype: getStatements(ModelReference, Subject, Predicate, Object) => StatementSet ModelReference: Reference to the target model for this operation Subject: URI or * (wildcard) Predicate: URI or * Object: URI,literal or * StatementSet: Set of statements returned
This operation matches the template (subject, predicate, object) against the
model, where the slots are either a fixed value (URI or literal as appropriate)
or a wildcard (meaning match anything in this position).
This operation allows for the insertion of multiple statements into the RDF Model. All statements in the StatementSet must be inserted into the identified RDF model. After the insert, the model must consist of all the statements in the statement set and MAY include any computed or inferred statements that the implementation wishes to add.
If a statement already exists within the model then it is not duplicated nor is an exception thrown; models are sets of statements.
Op-Prototype: insertStatements(ModelReference, StatementSet) ModelReference: Reference to the target model for this operation StatementSet: Set of RDF statements for the operation
Remove statements will remove all the statements given in the statement set from the model specified. The implementation MAY remove any computed or inferred statements at this point. If a statement that the client requests to be removed is a computed statement then the statement may or may not be removed, depending on implementation.
Op-Prototype: removeStatements(ModelReference, StatementSet) ModelReference: Reference to the target model for this operation StatementSet: Set of RDF statements for the operation
The semantics of this operation is that all statements within the model are removed and all statements passed in are created in the model. The identified model must contain all the statements in the statement set and MAY contain statements that are inferred or computed by the implementation.
Op-prototype: putStatements(ModelReference, StatementSet) ModelReference: Reference to the target model for this operation StatementSet: Set of RDF statements for the operation
The Update operation removes one set of statements and adds another set to the specified model. This is equivalent to removeStatements followed by addStatements but has the property that this must happen within a single atomic action. As with add and remove, there may be computed statements that are added or removed from the model.
Op-prototype: updateStatements(ModelReference, RemoveSet, InsertSet) ModelReference: Reference to the target model for this operation RemoveSet: Set of RDF statements to be removed InsertSet: Set of RDF statements to be inserted
The "options" operation allows reflection over the target model. The server returns metadata for the model; this might include information such as which operations are supported by this model and which query languages can be used in accessing the model.
This operation should not change the model. Typically, results from this operation will be cached, so servers should not frequently change the metadata for a model significantly without indicating this possibility in the returned metadata.
Op-prototype: options(ModelReference) => StatementSet ModelReference: Reference to the target model for this operation StatementSet: Results of the operation
The form of the results of this option should accord to a well-known vocabulary. While this note does not defined such a vocabulary, we hope that a common, stable vocabulary will arise.
The model reference '*' has the special meaning of a request for details about all models hosted at the server.
Issues of security, errors and other exception conditions are not considered in this abstract description of the protocol. The security framework will be dependent on the style and abilities of the underlying protocol and of the deployment environment. For exception conditions, such as an attempt to remove an inferred statement, we leave it to the implementation to make the tradeoffs driven by their inference system and desired target environment.
This section has defined the set of operations that make up the RDF Net API. These simple set of operation provide a generic mechanism for clients to interact with semantic web servers. The following section describe specific implementation bindings for SOAP and HTTP.
With the SOAP binding we first define the RDF data model in terms of XMLSchema and then use this in the method definitions.
<?xml version="1.0"?>
<definitions name="rdfnetservice"
targetNamespace='http://www.semanticwebserver.com/rdfnetservice'
xmlns:tns='http://www.semanticwebserver.com/rdfnetservice'
xmlns:soap='http://schemas.xmlsoap.org/wsdl/soap/'
xmlns:xsd='http://www.w3.org/2001/XMLSchema'
xmlns='http://schemas.xmlsoap.org/wsdl/'>
<types>
<schema targetNamespace='http://www.semanticwebserver.com/rdfnetservice'
xmlns='http://www.w3.org/2001/XMLSchema'
xmlns:SOAP-ENC='http://schemas.xmlsoap.org/soap/encoding/'
xmlns:wsdl='http://schemas.xmlsoap.org/wsdl/'
elementFormDefault='qualified'>
<complexType name="rdfstatement">
<sequence>
<element name="subject" xsd:type="xsd:string" />
<element name="predicate" xsd:type="xsd:string" />
<element name="object" xsd:type="xsd:string" />
<element name="isObjectLiteral" xsd:type="xsd:boolean"/>
</sequence>
</complexType>
<complexType name="rdfstatementvector">
<all>
<element name="item" type="tns:rdfstatement" minOccurs="0" maxOccurs="unbounded"/>
</all>
</complexType>
</schema>
</types>
<!-- Abstract: define messages for passing to and from web services. -->
<message name="insertStatementRequest">
<part name="modelid" type="xsd:string" />
<part name="statement" type="tns:rdfstatement"/>
</message>
<message name="insertStatementsRequest">
<part name="modelid" type="xsd:string" />
<part name="statements" type="tns:rdfstatementvector"/>
</message>
<message name="removeStatementRequest">
<part name="modelid" type="xsd:string" />
<part name="statement" type="tns:rdfstatement"/>
</message>
<message name="removeStatementsRequest">
<part name="modelid" type="xsd:string" />
<part name="statements" type="tns:rdfstatementvector"/>
</message>
<message name="putStatementsRequest">
<part name="modelid" type="xsd:string" />
<part name="statements" type="tns:rdfstatementvector"/>
</message>
<message name="updateStatementsRequest">
<part name="modelid" type="xsd:string" />
<part name="statementToRemove" type="tns:rdfstatementvector"/>
<part name="statementToAdd" type="tns:rdfstatementvector"/>
</message>
<message name="getStatementsRequest">
<part name="modelid" type="xsd:string" />
<part name="subj" type="xsd:string"/>
<part name="pred" type="xsd:string"/>
<part name="obj" type="xsd:string"/>
<part name="isObjLit" type="xsd:boolean"/>
</message>
<message name="optionsRequest">
<part name="modelid" type="xsd:string" />
</message>
<message name="getStatementsResponse">
<part name="statements" type="rdfstatementvector"/>
</message>
<message name="queryRequest">
<part name="modelid" type="xsd:string" />
<part name="query" type="xsd:string"/>
<part name="queryLanguage" type="xsd:string"/>
<part name="resultsFormat" type="xsd:string"/>
</message>
<message name="queryResponse">
<part name="statements" type="rdfstatementvector"/>
</message>
<message name="optionsResponse">
<part name="statements" type="rdfstatementvector"/>
</message>
<!-- Set of operations. -->
<portType name="RDFNetServicePort">
<operation name="insertStatement">
<input message="insertStatementRequest" />
</operation>
<operation name="insertStatements">
<input message="insertStatementsRequest" />
</operation>
<operation name="removeStatement">
<input message="insertStatementRequest" />
</operation>
<operation name="removeStatements">
<input message="removeStatementsRequest" />
</operation>
<operation name="putStatements">
<input message="putStatementsRequest" />
</operation>
<operation name="updateStatements">
<input message="updateStatementsRequest" />
</operation>
<operation name="getStatements">
<input message="getStatementsRequest" />
<output message="getStatementsResponse"/>
</operation>
<operation name="queryStatements">
<input message="queryStatementsRequest" />
<output message="queryStatementsResponse"/>
</operation>
<operation name="options">
<input message="optionsRequest" />
<output message="optionsResponse"/>
</operation>
</portType>
</definitions>
With this HTTP binding we use a number of web principles:
GET http://example.com/foo HTTP/1.1 GET http://example.com/foo?lang=...&<otherParams> HTTP/1.1
The simplest form of a query is a plain HTTP GET. It returns all the RDF statements in the model at that URL.
Beyond this, for access to models that are either very large, stored in databases or dynamically generated, access is by query. There is simple query language that just provides a triple pattern of subject/predicate/object values or wildcards so that systems can provide a common, if limited, query service.
The query language is specified by the 'lang' parameter; this can be the URI for the language, or a short name for the query language if the server supports such things (this is merely a local replacement for the full URI). The lang parameter is always present for any Query operation, except for a plain HTTP GET. Other parameters depend on the query language.
Use of the URI for the query language is preferred; a client should use a short name only if it knows that the name is defined for this model.
One simple access mechanism is described here. Providing this language is optional – some RDF data will need specific query languages (e.g. dynamically generated RDF models).
The URI of the language is http://www.semanticwebserver.com/2003/01/Query/TriplePattern
The conventional short name is "TriplePattern". Such short names can be found using the OPTIONS operation.
| HTTP Parameter Name | Definition |
|---|---|
| lang | Required |
| subject | Either a URI (hex encoded) or the character '*' meaning
wildcard. Absence, Null value or "" implies the wildcard '*'. |
| predicate | Either a URI (hex encoded) or the character '*' meaning
wildcard. Absence, Null value or "" implies the wildcard '*'. |
| object | Either a URI (hex encoded) or the character '*' meaning wildcard. |
| literal | A literal value (a hex encoded string). |
Only one of parameters 'object' or 'literal' may be used in a single request. Absence of both implies any URI or literal.
The meaning of the query is that all statements matching the pattern are returned. A pattern is a triple, (subject, predicate, node), where each of the three slots is either a constant (URI or literal as appropriate) or a wildcard, meaning 'match any in the slot'.
Update is performed with HTTP POST. The POST body is a MIME multipart of two parts, the first is the statements to remove, encoded as an RDF graph (syntax as per MIME Content type) and the second is the statements to add, again as an RDF graph. The graph is encoded in RDF/XML.
The POST request is of the form:
POST http://example.com/foo?update HTTP/1.1
which allows other operations to be supported on the model.
A semantic web server is not required to implement this operation. It can also impose any security system it chooses.
This is a simplified example. An implementation must follow HTTP RFC 2616 (which refers to MIME RFC 2045) for multipart entities.
POST http://example.com/foo?update HTTP/1.1
Content-type: multipart/mixed; boundary=--------12345
--------12345
Content-type=application/rdf+xml
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<!-- Statements to remove -->
...
</rdf:RDF>
--------12345
Content-type=application/rdf+xml
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
<!-- Statements to add -->
...
</rdf:RDF>
Special case of update. The body of the HTTP POST is the RDF graph to merge with the target.
Special case of update. The body of the HTTP POST is the RDF graph to remove from the target.
This operation is provided with HTTP PUT. The body of the message is a single RDF graph that replaces the target model.
This operation is provided by HTTP OPTIONS. The server should return details about the named model. A request is '*' is a request to sever to return a description of all models hosted at the server.
The result is an RDF model in one or more vocabularies.
The following systems implement ideas presented in this document: