A SAC is a Semantic Annotation Collection, which allows users or applications to store and share bookmarks, comments, and other annotations. This implementation is a prototype one, which may or may not become the project's main SAC implementation. There are other implementations (loosely) planned. See the project's 'vision' for the overall plan, and the list of user stories for the detailed functionality we expect to add in the future. The parent of all the SACs in the service. This returns an HTML page listing the available SACs. Retrieve human-readable information about the SAC service. The content of the response is not otherwise specified, but it might include things such as the SACs that are available. This part of the interface is only available in a 'multiSAC', which is a SAC which contains multiple separate SACs. In a standalone SAC this resource might not be nameable. Text describing the SAC service An individual SAC The name of the SAC to be operated on Retrieve a SAC or, if the metadata query parameter is present, retrieve the SAC's metadata. The configuration metadata is discussed in the documentation for the PUT action. The HTTP 'Accept' header may be present in the request, and if so should be one of the representations listed below as success responses. If the metadata query parameter is present, with any value, then return the SAC's metadata instead of its content. Return a representation of the RDF content of the SAC. The SAC does not exist. The content includes text explaining this. The SAC (or its metadata, if that was requested) cannot be represented in an acceptable format. The content includes text explaining this. Make a SPARQL query against the SAC The HTTP 'Accept' header may be present in the request, and if so should be one of the representations listed below as success responses. See the POST SPARQL method for detailed discussion. A URL-encoded SPARQL query. The value of the query query parameter is a URL-encoded SPARQL query, as appropriate for the application/x-www-form-urlencoded MIME type. For more information about HTML form encoding, consult the HTML4 specification, section 17.13.4, and the URL specification, RFC1738. The encoding algorithm is usefully summarised in the documentation for the java.net.URLEncoder class. The results of the SPARQL query, in the appropriate MIME type for the query N-triples format (for SPARQL construct and describe queries); or the string 'yes' or 'no' for SPARQL ask queries; or an ascii-art table for SPARQL select queries SPARQL query result format (for SPARQL select and ask queries). See SPARQL query results spec Comma-separated-values (for SPARQL select queries) Tab-separated-values (for SPARQL select queries) Malformed SPARQL request Unacceptable MIME type in Accept header Post RDF to a SAC and get a claim back. The posted RDF – which must have as its content-type one of the request MIME types listed below – is parsed with the new claim URI as its base-URI, so it should refer to the claim itself with <> (in Turtle) or rdf:about="" (in RDF/XML). The claim URI is returned in the response's Location header. If there is no RDF in the request body, that is an error. For example, the following RDF would be acceptable as a claim: @prefix skua: <http://myskua.org/claimtypes/1.0/> . @prefix dc: <http://purl.org/dc/elements/1.1/> . <> a skua:bookmark; skua:ref [ a skua:webpage; skua:url <http://n2.talis.com/wiki/SPARQL_Demo>; dc:title "SPARQL Demo - N2 wiki"; ]; skua:tag "semanticweb", "rdf", "sparql", "tutorial"; skua:time "2008-01-21T18:11:58Z" . Returns the ID of the created claim in a Location header The full URL of the newly-created claim There was no RDF included in the request body, or else the posted RDF did not refer to the claim URI. Make a SPARQL query against the SAC. See the SPARQL spec for full documentation. SPARQL CONSTRUCT and DESCRIBE queries produce RDF, and so if an Accept header is present it must be one of the RDF MIME types below, namely text/rdf+n3, application/rdf+xml, text/turtle or text/plain (N-triples). SELECT queries produce a list of results, and so the result must be one of the list types below, namely application/sparql-results+xml, text/plain (ascii-art output), text/csv or text/tab-separated-values. ASK queries can produce either of the types application/sparql-results+xml or text/plain (containing one of the strings yes or no), with a 200 status if the query succeeds, irrespective of whether the answer is true or false. The results of the SPARQL query, in the appropriate MIME type for the query N-triples format (for SPARQL construct queries) SPARQL query result format (for SPARQL select and ask queries). See SPARQL query results spec Comma-separated-values (for SPARQL select queries) Tab-separated-values (for SPARQL select queries) Malformed SPARQL request Unacceptable MIME type in Accept header Update the SAC metadata by posting to the {sacName}?metadata URL. The content of the post must abide by (a profile of) an unversioned update in the Talis Changeset Protocol, except that (currently) we may have only one ChangeSet per posting, and each addition and removal must have the subjectOfChange as its subject. The changeset can only (at present) be posted to the SAC's {sacName}?metadata URL. The content must be RDF/XML. It is parsed with the sacName as its base URI. If the changeset is in any way malformed, or the protocol's preconditions are not satisfied, return status 400. Create a SAC by PUTing metadata to what you have chosen as the new SAC URI -- that is, making a choice for the {sacName} in the URI. If the SAC already exists, you will receive the status code 409 Conflict. The metadata can be anything, but might include for example Dublin Core information. The uploaded RDF is parsed with the new SAC name as its base URI, and so should refer to the SAC with <> (in Turtle) or rdf:about="" (in RDF/XML). The metadata can be retrieved at the URI which is the SAC's name, with a '?metadata' query suffixed (see above). As well as documenting the SAC's purpose, the metadata can also be used to configure the SAC. You must supply at least some metadata for the SAC, or else the SAC will response with an error 400 Bad Request. For example, the SAC creation metadata might be as simple as the following @prefix dc: <http://purl.org/dc/elements/1.1/>. <> dc:description "My SAC"; dc:creator "Norman". The RDF content of the SAC's metadata. If no Content-Type is supplied, then the SAC defaults to application/rdf+xml Returns 201 (Created) if the SAC has been successfully created, and returns the URL of the SAC in a Location header. The URL of the newly-created SAC (which will be the same as the URL to which this request was posted). No metadata was supplied, or the metadata did not refer to the resource <>, or the metadata could not be parsed as RDF. You cannot create a SAC which already exists Delete the SAC The SAC and its contents have been discarded. Return 404 if the SAC can't be found A submodel which is included in the SAC; this will typically be an ontology of domain-specific knowledge. Queries over the SAC include the contents of the submodel as well as the claims. An identifier for a specific submodel. Retrieve the submodel The RDF representing a submodel Return 404 if the submodel cannot be found in the SAC Add or overwrite the existing submodel. The content of the message is parsed with the submodel URI as the base URI. If no Content-Type is present, then default to application/rdf+xml Response to PUTting a submodel. Return 201 (Created) if the submodel has been written (whether or not it existed before). Return 404 (Not Found) if the claim was not found. The submodel has been successfully created or overwritten The SAC that this purports to be a submodel of does not exist Delete the submodel The SAC and its contents have been discarded. Return 404 if the SAC or the submodel can't be found An individual claim. The structure of the claim URIs is described here only in order to document the methods which may be used on those URIs. However you should not rely on this structure, and a SAC service is free to mint claim URIs with a different structure. You do not need to generate claim URIs at any point, and should instead use only the URIs which are returned in the Location header when you create claims as described above. An identifier for a specific claim Retrieve the claim RDF The RDF representing a claim Return 404 if the claim cannot be found in the SAC Overwrite the existing claim data. As when creating the claim (see above), you must refer to the claim itself in the updated claim RDF. You can do this by explicitly including the claim URI in the RDF, or more conveniently by referring to the claim with <> (in Turtle) or rdf:about="" (in RDF/XML). If no Content-Type is present, then default to application/rdf+xml Response to PUTting a claim. Return 204 (No Content) if the claim existed and has been successfully overwritten, 404 (Not Found) if the claim was not found, or 400 (Bad Request) if the updating RDF did not refer to the claim The claim has been successfully overwritten The updating RDF did not refer to the claim The claim was not found Delete the claim The claim has been deleted The claim does not exist Provide version information, including information about what functionality is compiled in. Text describing the versions available An individual component within the SAC software The component is present, and has the given version number The component is not present The component is not recognised RDF/XML is the only RDF serialisation which has been fully standard by W3C. See the definition at http://www.w3.org/TR/rdf-syntax-grammar/. Turtle is a well-established but still experimental text syntax for RDF. It's very closely related to Notation3, but without some of that syntax's non-RDF extensions. The MIME type is not yet registered, but text/turtle is being requested; Turtle has also been served with the MIME type application/x-turtle. Notation-3 is a well-known, but not fully formally specified serialisation for RDF. The application/n3 MIME type is recognised but deprecated (see W3 discussion), since its IANA registration was never completed; text/rdf+n3 is the preferred MIME type for Notation3. The SPARQL query language for RDF is defined in http://www.w3.org/TR/rdf-sparql-protocol/.