[oslc-core] Comments on OSLC Core Specification Version 2.0 - DRAFT

[Arthur Ryman]

I carefully read the entire spec again, this time translating it into OWL 
as a check on its overall consistency. I corrected some obvious typos. 
Here are the issues I found below. I also have some comments on how the 
Core spec relates to OWL, which I'll send in a separate note.

1. Resource value-types. There is a technical error in the description of 
Local Inline Resource and the subsequent examples. The spec incorrectly 
uses rdf:ID to refer to local resources. Recall that we introduced the 
term "local resource" to be a synonym for "blank node" because we did not 
want to depend on RDF terminology. I think we should look at this decision 
again since the new terms and descriptions we are introducing may be 
adding to the confusion instead of simplifying the specification.

The correction is to use rdf:nodeID whenever referring to a blank node 
within an RDF/XML document. The rules are described in [1].

rdf:ID is also very useful, but is not used for blank nodes. It is used to 
define URI references that are relative to the XML base of the RDF/XML 
document. [2] rdf:ID defines a unique fragment identifier within the 
document, which is then appended to the base URI + "#" to for a URI 
reference.These URI references are global, i.e. their values have meaning 
outside the document. They are useful for identifying resources within an 
RDF/XML document.

We introduced the concepts of local and inline resources to put 
constraints on the format of documents so that they would be easier to 
parse. However, we are using most of RDF/XML anyway, so maybe we should 
simply allow RDF/XML and use the correct RDF terms? A quick Google search 
shows that there are RDF parsers for all major languages.

2. dc:title and dc:description

First, we are using the dcterms namespace, so our documentation should use 
the prefix dcterms: which is the normal convention. dc: is conventionally 
used for the DC elements namespace.

Second, we had a long email discussion on using rich text for these 
properties, specifically XHTML <span> and <div> content, and this is 
recommended in Appendix A. [3] This means the datatype should be 
rdf:XMLLiteral. However, the Core uses string for these on its own 
resources. Shouldn't we follow our own recommendations?

3. Resource: Respsonse Information - the value of oslc:nextPage should be 
a resource, not a string.

4. In Conceptual Model diagram oslc:QueryCapability should be 
oslc:queryCapability - the convention is that property names start with 
lowercase letter, and class and individual names start with uppercase 
letter.

5. Namespace Definition versus Prefix Definition - I think these are the 
same thing, but both terms are used in the spec. We should use 
PrefixDefinition.

6. Resource: Service Provider - the spec says that namespace definitions, 
aka predefined prefixes, can be used in JSON respresentations, We should 
only use predefined prefixes on URLs to keep them short and readable. We 
should NOT use predefined prefixes in documents. Documents should be 
self-contained and define any prefixes they use.

7. Resource: Creation Factory - the spec uses both oslc:Factory and 
oslc:CreationFactory. These are the same. We should only use 
oslc:CreationFactory.

8. Resource: Error 
- the datatype of oslc:statusCode is Decimal. I suggest that String is 
more appropriate since a code is usually an arbitrary sequence of 
characters, not necessarily a decimal number.
- the (misspelled) property oslc:exendedMessage should be 
oslc:extendedError since it refers to an ExtendedError resource
- the text refers to the resource type oslc:ExtendedMessage but that 
should be oslc:ExtendedError

9. Resource: Extended Error
- the properly oslc:url should be renamed to the more descriptive term 
oslc:moreInfo since it refers to a document that contains more information
- the property oslc:rel has datatype Resource which is inconsistent with 
the text which defines a string value 'alternate'. The datatype should 
therefore be String
- the properties oslc:highWidth and oslc:hintHeight have datatype Decimal, 
but this is inconsistent with their use elsewhere, where it is String in 
order to allow CSS window size units. Use String here too.

10. JSON Representations
 - the text refers to QNames but should refer to Prefixed Name. A QName 
represents a pair consisting of a namespace URI and a local name. A 
Prefixed name represents a URI ref.
- the property rdf:id is used but this should be rdf:nodeID

[1] http://www.w3.org/TR/REC-rdf-syntax/#section-Syntax-blank-nodes
[2] http://www.w3.org/TR/REC-rdf-syntax/#section-Syntax-ID-xml-base
[3] 
http://open-services.net/bin/view/Main/OSLCCoreSpecAppendixADRAFT?sortcol=table;up=#Dublin_Core_Properties

Regards, 
___________________________________________________________________________ 

Arthur Ryman, PhD, DE


Chief Architect, Project and Portfolio Management

IBM Software, Rational

Markham, ON, Canada | Office: 905-413-3077, Cell: 416-939-5063
Twitter | Facebook | YouTube