Copyright © 2010 . This document is available under the W3C Document License. See the W3C Intellectual Rights Notice and Legal Disclaimers for additional information.
SA-REST is a poshformat [Poshformat] to add additional meta-data to (but not limited to) REST [REST] API descriptions in HTML or XHTML. Meta-data from various models such an ontology, taxonomy or a tag cloud can be embedded into the documents. This embedded meta-data permits various enhancements, such as improve search, facilitate data mediation and easier integration of services.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications can be found in the W3C technical reports index at http://www.w3.org/TR/.
By publishing this document, W3C acknowledges that the Submitting Members have made a formal Submission request 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. A W3C Team Comment has been published in conjunction with this Member Submission. Publication of acknowledged Member Submissions at the W3C site is one of the benefits of W3C Membership. Please consult the requirements associated with Member Submissions of section 3.3 of the W3C Patent Policy. Please consult the complete list of acknowledged W3C Member Submissions.
Semantic Annotations for REST (SA-REST) define three basic properties that can be used to non-intrusively annotate HTML/XHTML documents, typically to embed ontological meta-data. These properties, defined as a poshformat [Poshformat], are included as part of the XHTML document allowing a capable processor to gain extra information about the content of the document. Poshformats are the superset of microformats [Microformat]. While a poshformat may follow certain microformat design principles, it may not have gone through a rigorous community process as defined by microformat process guidelines [MicroformatProcess].
are specified using the
class attribute and the
attribute defined by the HTML specification [HTML
4.01]. Similar to microformats, the scope of the annotation is defined by the HTML element that bears the
The following example illustrates an XHTML fragment embedded with SA-REST annotations. The original text fragment is from Wikipedia for the subject computer([Computer]). The markup in bold highlight the SA-REST annotations.
(001) <p> (002) A <b><span class="sem-class" title="http://tap.stanford.edu/#computer"> computer </span></b> (003) is a <a href="/wiki/Machine" title="Machine">machine</a> that manipulates (004) <a href="/wiki/Data_(computing)" title="Data (computing)">data</a> according (005) to a set of <a href="/wiki/Source_code" title="Source code">instructions</a>. (006) </p> (007) <p> (008) <span class="domain-rel" title="http://www.owl-ontologies.com/ComputingOntology.owl#History_of_Computing" > (009) Although mechanical examples of computers have existed through much of recorded human (010) history, the first electronic computers were developed in the mid-20th century (1940–1945).</span> </p>
Line (002) illustrates the specification of the term
computer using the
sem-class property. Lines (008) to
(010) exemplify the marking up of the text fragment to indicate that it
belongs to the domain History of Computing.
The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119 [RFC 2119].
When describing abstract data models, this specification uses the notational convention used by the XML Infoset [XML Infoset]. Specifically, abstract property names always appear in square brackets (e.g., [some property]).
Table 1 lists XML namespaces that are used in this specification. The choice of any namespace prefix is arbitrary and not semantically significant.
|rdfs||http://www.w3.org/2000/01/rdf-schema#||RDF Schema [RDFS]|
A list of design patterns to follow when designing a XHTML based microformat is defined by the microformat community [Microformat]. These principles are exemplified in the hCalender microformat specification [Hcal]. Two main design considerations taken into account in designing SA-REST are listed below.
SA-REST has two types of properties. These types are only meant to distinguish the capability of a property to nest other properties. As listed in Section 2.3, all properties are multi-valued.
SA-REST has three basic properties.
domain-relproperty allows a domain information description for a resource. If a given resource (such as a blog post) has content spanning multiple domains, it is desired to add multiple
domain-relproperty entries, each corresponding to a section of the resource. If such a separation cannot be made, the resource may be attached with an enumeration of values as the
sem-relproperty captures the semantics of a link and evolves from the popular
sem-relproperty enables the addition of externalized annotations to third party documents. A
sem-relproperty may only be used with an anchor (
sem-classcan be used to markup a single entity within a resource. The entity may be a text fragment or embedded objects such as a video.
Basic usage examples are illustrated below. The preferred style is
to use a generic language/style container (see [HTML
4.01]) surrounding the text fragment of interest.
title attributes are used to indicate the property and the
value. When adding a generic structural element is cumbersome or not
possible, any structural element with
attributes may be used.
<span class="domain-rel" title="http://apihut.com/schemas/socialnetworking#socialnetworks" > The growing trend of "liking" has recently caught a lot of attention of both network users as well as developers. </span>
<span class="domain-rel" title="http://apihut.com/schemas/socialnetworking#socialnetworks http://apihut.com/schemas/economy#recession" > One often wonders the future ofadvertisement driven Web applications in the current economic scenario. For example, social networking applications such as... </span>
<a href="http://foo.xsd" class="sem-rel" title="http://taxonomy.org/computerscience#firstname" > This is the input schema </a>
One striking observation in evolution of <span class="sem-class" title="http://tap.stanford.edu/#computer">Computers</span> is the relationship between speed and size.
SA-REST can be used to annotate RESTful API descriptions. The following example depicts an annotation across an HTML description of an API. The following HTML snippet is from the Yahoo! Developer Network mail Web Service API documentation [YDN-JSON-RPC]. These annotations highlight the use of the existing block elements to seamlessly integrate the annotations into an existing document.
The number of API descriptions available in programmableWeb [ProgrammableWeb] as of March 2010 is 1763, a 200% increase in one year. A general purpose search engine, such as Google, treat API documents like any other when indexing and ranking APIs. As a result, search for APIs (even when specific queries like "Maps API") results in API resources being scattered all over the result set. Web API directories like programmableWeb do present a more domain-specific solution. However, they largely rely on user tags for classification and searching. Addition of meta-data to capture the various facets of APIs (functionality, supported message types, clientside bindings, protocol etc) is essential for better indexing and searching. One such effort is APIHut [APIHut]. SA-REST can significantly improve faceted search by attaching explicit meta-data to the API descriptions.
Other enhancements include improvements to domain specific search capabilities. There is an ongoing effort with NCBO [NCBO] to test-drive the annotations on a selected set of NCBO Web services to improve the search capabilities.
Preferred methods to process SA-REST annotations are GRDDL [GRDDL] and XSLT [XSLT] to extract a useful representation. For example in most cases an RDF/XML (see [RDF]) would be useful. However SA-REST annotations may also be used to generate a structured representation such as a Web Services Description Language (WSDL)[WSDL] document. A simple GRDDL transformation reference is illustrated below.
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:grddl='http://www.w3.org/2003/g/data-view#' grddl:transformation="glean_api.xsl" >
This submission includes use cases contributed by the following individuals and teams.
This submission has been developed as a result of discussions with and supported by the following W3C member institutes (listed with the W3C representative).
We also acknowledge the contributions from Jonathan Marsh of WSO2 during the early phases of SA-REST.
The service model in RDFS/N3 is listed below.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> . @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> . @prefix sarest: <http://www.knoesis.org/research/srl/standards/sa-rest/#> . sarest:hasParameter rdf:type owl:ObjectProperty ; rdfs:range sarest:Parameter ; rdfs:domain sarest:Message . sarest:hasAddress rdf:type owl:ObjectProperty ; rdfs:domain sarest:Operation ; rdfs:range sarest:URITemplate . sarest:hasInputMessage rdf:type owl:ObjectProperty ; rdfs:range sarest:InputMessage ; rdfs:domain sarest:Operation . sarest:hasMethod rdf:type owl:ObjectProperty ; rdfs:range sarest:HTTPMethod ; rdfs:domain sarest:Operation . sarest:hasOperation rdf:type owl:ObjectProperty ; rdfs:range sarest:Operation ; rdfs:domain sarest:Service . sarest:hasOutputMessage rdf:type owl:ObjectProperty ; rdfs:range sarest:OutputMessage ; rdfs:domain sarest:Operation . sarest:InputMessage rdf:type owl:Class ; rdfs:subClassOf sarest:Message . sarest:OutputMessage rdf:type owl:Class ; rdfs:subClassOf sarest:Message . sarest:Parameter rdf:type owl:Class . sarest:HTTPMethod rdf:type owl:Class . sarest:Message rdf:type owl:Class . sarest:Operation rdf:type owl:Class . sarest:Service rdf:type owl:Class . sarest:URITemplate rdf:type owl:Class . sarest:DELETE rdf:type owl:Thing , sarest:HTTPMethod . sarest:GET rdf:type owl:Thing , sarest:HTTPMethod . sarest:POST rdf:type owl:Thing , sarest:HTTPMethod . sarest:PUT rdf:type owl:Thing , sarest:HTTPMethod .