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      ::= PrefixedName 
PrefixedName    ::= /* see "SPARQL Query Lanaguage for RDF", http://www.w3.org/TR/rdf-sparql-query/#rPrefixedName */
nested_prop     ::= property "{" properties "}"
wildcard        ::= "*"

identifier

The term identifer contains both the namespace prefix and the local part of the property name. This syntax is referred to as a PrefixedName in SPARQL Query Lanaguage for RDF. We therefore use the syntax of PrefixedName? for identifier.

wildcard

The wildcard term is equivalent to the list of all property names. For example, the query parameter oslc.properties=* specifies that every property of the resource MUST be returned in the HTTP GET response. In contrast, an HTTP GET request that omits oslc.properties MAY only return some subset of the properties, e.g. it MAY return only some default set of properties.

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      ::= PN_PREFIX
PN_PREFIX   ::= /* see "SPARQL Query Lanaguage for RDF", http://www.w3.org/TR/rdf-sparql-query/#rPN_PREFIX */
uri_ref_esc ::= /* an angle bracket-delimited URI reference in which > and \ are \-escaped. */

prefix

The term prefix defines the syntax of a namespace prefix. This syntax is the same as PN_PREFIX in SPARQL Query Language for RDF.

uri_ref_esc

The term uri_ref_esc is an angle bracket ("<" and ">") delimited URI reference in which all occurances of the right angle bracket character ">" MUST be replaced by the string "\>", and all occurances of the backslash character "\" MUST be replaced by the string "\\". This delimiting and 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

Replaced the grammar for QName with PrefixedName since it is exactly what an identifier is.

-- ArthurRyman - 22 Mar 2010

Replace the grammar for NCName with PN_PREFIX for consistency with PrefixedName.

-- ArthurRyman - 22 Mar 2010

Resolved OSLC Core Spec V1 issue an delimiting URIs with angle brackets to distinguish them from strings in oslc.where. Modified the uri_ref_esc grammar term to capture this. The syntax of oslc.prefix should also use this syntax so we have only one grammar term for URIs.

-- ArthurRyman - 09 Apr 2010