OSLC Syntax for Property Selection and Namespace Prefixes
Early Draft Initial draft created, some of this has been lifted from
CM 1.0 Specs.
Table of Contents
Introduction
This document proposes a method for requesting a selective subset of a full resource's properties utilizing URL query parameters. Also it will provide a method for defining namespace prefixes for usage in the property requests.
Sample: Request the change request resource at
http://bugserver/bugs/bug123
and only the properties of
title
and
creator
Request:
GET http://bugserver/bugs/bug123?oslc.properties=dc:title,dc:creator&oslc.prefix=dc=http://purl.org/dc/elements/1.1/
Accept: application/rdf+xml
Response content:
<?xml version="1.0" encoding="UTF-8"?>
<oslc_cm:ChangeRequest
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/terms/"
xmlns:oslc_cm="http://open-services.net/xmlns/cm/1.0/"
rdf:about="http://bugserver/bugs/bug123">
<dc:title>A Defect</dc:title>
<dc:creator rdf:resource="http://bugserver/users/bob" />
</oslc_cm:ChangeRequest>
Notation and Conventions
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in
RFC2119. Domain name examples use
RFC2606.
Selective Properties
A client MAY request a restricted number of resource properties as well as properties from a referenced resource using a HTTP query parameter named
oslc.properties
.
Service providers MUST support the
oslc.properties
parameter on HTTP GET requests on individual resource requests as well as on resource collections. If the
oslc.properties
parameter is omitted on a HTTP GET request, then all resource properties MUST be provided in the response.
If any of the properties listed in the
oslc.properties
do not exist for the resource, a HTTP response status of 409 Conflict MUST be used.
If the resource does not exist at the request URL, a HTTP response status of 404 Not Found MUST be used.
Parameter: oslc.properties
Syntax:
BNF
oslc_properties ::= "oslc.properties=" properties
properties ::= property ("," property)*
property ::= identifier | nested_prop | wildcard
identifier ::= QName
QName ::= /* see "Namespaces in XML 1.0", http://www.w3.org/TR/REC-xml-names/ */
nested_prop ::= property "{" properties "}"
wildcard ::= "*"
identifier
The term
identifer
contains both the namespace prefix and the local part of the property name. However, these names will often appear in XML documents as element and attribute names where they are referred to as QNames. The grammar for QName is formally defined by W3C in
Namespaces in XML 1.0.
QName is also an XML Schema built-in datatype. We therefore use QName as the syntax for the term
identifier
.
Inlined Properties
Resource descriptions may include properties that have complex content themselves.
Sample: Request the Change Request resource at
http://bugserver/bugs/bug123
and only the properties of title and full creator details.
Request:
GET http://bugserver/bugs/bug123?oslc.properties=dc:title,dc:creator{*}
Accept: application/rdf+xml
Response content:
<?xml version="1.0" encoding="UTF-8"?>
<oslc_cm:ChangeRequest
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:dc="http://purl.org/dc/terms/"
xmlns:oslc_cm="http://open-services.net/xmlns/cm/1.0/"
rdf:about="http://bugserver/bugs/bug123">
<dc:title>A Defect</dc:title>
<dc:creator>
<User rdf:about="http://bugserver/users/bob" >
<name>John Doe</name>
<email>foo@email.com</email>
</User>
</dc:creator>
</oslc_cm:ChangeRequest>
Property Name Prefixes
The property names, e.g.
dc:title
,
ex:priority
, include
XML namespace prefixes which are either well-known prefixes that are predefined by the service or are explicitly defined using URL query parameters.
Sample definition of namespace prefixes
dc
and
ex
?oslc.prefix=dc=http://purl.org/dc/elements/1.1/,ex=http://example.net/bugns/
Sample added to a change request resource URL as following:
http://bugserver/bugs/bug123?oslc.properties=dc:title,ex:priority
&oslc.prefix=dc=http://purl.org/dc/elements/1.1/,ex=http://example.net/bugns/
The
oslc.prefix
query parameter SHOULD contain at most one definition for any given prefix. If a prefix is defined more than once then the behavior is undefined.
Parameter: oslc.prefix
Syntax:
BNF
oslc_prefix ::= "oslc.prefix=" prefix_defs
prefix_defs ::= prefix_def ("," prefix_def)*
prefix_def ::= prefix "=" uri_ref_esc
prefix ::= NCName
NCName ::= /* see "Namespaces in XML 1.0", http://www.w3.org/TR/REC-xml-names/ */
uri_ref_esc ::= /* a URI reference in which certain characters are escaped, see below */
prefix
The term
prefix
defines the syntax of a namespace prefix. The
XML syntax for namespace prefixes is defined by NCName (non-colonized name).
NCName is also an XML Schema built-in datatype.
uri_ref_esc
The
oslc.prefix
query parameter lets you define one or more prefixes in a comma-separated list of prefix definitions. Commas that appear in URI references must therefore be escaped. The term
uri_ref_esc
is a
URI reference in which all occurances of the comma character "," MUST be replaced by the string "\,", and all occurances of the backslash character "\" MUST be replaced by the string "\\". This escaping MUST be undone to recover the actual value of the URI reference.
2010-02-22, Arthur: Used QName as syntax for identifier. Added BNF for oslc.prefix.
--
ArthurRyman - 23 Feb 2010
Should this not be a bad request response?
"The oslc.prefix query parameter SHOULD contain at most one definition for any given prefix. If a prefix is defined more than once then the behavior is undefined. "
--
IanGreen - 23 Feb 2010
Behaviour of queries involving undefined prefixes should be standardized?
--
IanGreen - 23 Feb 2010