Hi Arthur, Thanks for taking the time to do a detailed review. This is very helpful. I have added each of your comments to the issues page and I will work through them and responding there for most of the issues.
http://open-services.net/bin/view/Main/OslcCoreV1Issues - Dave On Mon, Jun 14, 2010 at 2:31 PM, Arthur Ryman <[email protected]> wrote: > 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 > > > > > > _______________________________________________ > Oslc-Core mailing list > [email protected] > http://open-services.net/mailman/listinfo/oslc-core_open-services.net >
