Resource Shape

This document specifies the Resource Shape features that a Service Provider needs to implement on top of a domain specification for Reporting. The Reporting Consumer will base on this specification for their expectation of the Resource Shape features supported by a Service Provider on Reporting.

This document only makes references to the Resource Shape Resource as defined in the OSLC Core Specification (hereafter will be referred as OSLC Resource Shape Specification). The actual specification of Resource Shape is defined in the OSLC Core Specification and won't be repeated in this document.

This document may tighten the constraints as specified in the OSLC Resource Shape Specification, but will not relax them.

A look at the latest proposal for Resource Shape

This is a very rough draft of the latest discussion. It is included here just for reference. It will be removed when a more complete draft in Core Spec is available.

@prefix oslc: <http://open-services.net/xmlns/rm/1.0/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix dc: <http://purl.org/dc/terms/> .
<http://example.com/services/reportingProperties>
rdf:type oslc:PredicateSet ;
dc:title "Requirements Property Set for Reporting" ;
dc:description "A list of interesting properties for reporting on Requirements" ;
oslc:whenSubject [
a oslc:RdfTypeTest;
oslc:test oslc:Requirement;
oslc:property: [
a oslc:Property;
oslc:predicate dc:title ;
dc:title "Requirement Title" ;
dc:description "The title of the requirement";
oslc:occurs "exactly-one" ;
oslc:range [
rdf:type oslc:UnionDatatype ;
oslc:datatype <http://www.w3.org/2001/XMLSchema#string> , <http://www.w3.org/1999/xhtml>.
] .
];
oslc:property: [
a oslc:Property;
oslc:predicate dc:description ;
dc:title "Requirement Description" ;
dc:description "The description of the requirement";
oslc:occurs "at-most-one" ;
oslc:range [
rdf:type oslc:UnionDatatype ;
oslc:datatype <http://www.w3.org/2001/XMLSchema#string> , <http://www.w3.org/1999/xhtml>.
] .
].
];
oslc:whenSubject [
a oslc:RdfTypeTest;
oslc:test oslc:TestCase;
oslc:Property [
a oslc:Property;
oslc:predicate: dc:title ;
dc:title "Requirement Title" ;
dc:description "The title of the testcase";
oslc:occurs "exactly-one" ;
oslc:range [
rdf:type oslc:UnionDatatype ;
oslc:datatype <http://www.w3.org/2001/XMLSchema#string> , <http://www.w3.org/1999/xhtml>
] .
].
].

Resource Schema Choices for Reporting REST API

Schema Requirements

1. Reporting Consumer does not have any prior knowledge on domain resources.

2. Reporting Consumer needs schema information for
- displaying to Administrator what to expect for the resource
- specifying the mapping of resource properties to reporting system internal data model
- contructing a query for the resources to the Service Provider
- mapping resource data in the query resultset to reporting system internal data model during data loading

3. Does Reporting Consumer need syntactic or semantic information about resource, or both?

Schema of what?

Are we talking about the schema of
1. the resource itself i.e. the concept
2. the representation of the resource
3. the result of a query on the resource which relates to the resource but not the resource itself

So, the schema of which of the above three things we are interested in meeting the Reporting Consumer requiements?

A clear understanding of the above would help us to decide on choosing the technology.

Schema Choices

At this point in the development of a Reporting REST API we are exploring what schema we should use for describing an individual implementation of a reporting REST API. Currently, this page is an analysis of the 3 candidates I have discovered. However, I expect the page will ultimately contain the details of the choice we make.

To date the three candidates I have seriously consider are

1. XML Schema
2. Resource Description Framework (RDF) Schema
3. Web Ontology Language (OWL)

My initial choice would be OWL.

The Three Candidates

I have not done extensive research into other choices, but I am reasonable conversant with XML technology in general and XML schema (with a little 's') in particular. That being said, I am happy to consider other alternatives.

I have included references below for those either unfamiliar with this technology or who want to refresh their understanding thereof.

XML Schema

XML Schema (with a big 'S') is probably the best understood and most widely used language for specifying the syntax for XML documents. It forms the underpinnings of RDF Schema and OWL, the other two choices considered here.

XML Schema is a closed in document specification language, in that it is difficult and unwieldy to specify XML document types that ignore XML content not explicitly specified in the XML Schema description. The converse observation of XML Schema is that it is, of the three here, provides the facilities for the most precise syntatical description of a document type (placement of commas ',' and periods '.').

Because of the wide knowledge about XML Schema, I will not spend more time on an individual description of it.

RDF Schema

RDF provides a the XML equivalent of a multiple inheritance type system for XML document types. Two document types can be defined to both subclasses of the same two superclasses, which themselves inherit from a common root document type.

Perhaps more importantly, but not germane here, RDF is an abstract directed graph model using subject, verb, predicate tuples where each element of the tuple is an XML element (or blank node for those who really care). See the RDF Primer for a more complete description of this aspect of RDF.

In addition, RDF documents are build upon a commonly set of vocubularies (e.g. the Dublin Core). By using well known vocabularies, the business logic behind the meaning of terms of that vocabularies can be reused across different application domains or applications in a particular domain. For example dc:description has a well known meaning of an account of a resource.

Meaning is a tricky concept, especially when it comes to computer processing agents. However, as opposed to XML Schema, which deals primarily at the level of language syntax, RDF begins to work at the level of language semantics through is uses of common jargon. The Dublin Core is probably the most well known vocabulary for XML documents. There are many more in use in the IT community, as well will be probably be specifying here for reporting systems and clients.

RDF Schema is the schema definition language initially developed for specifying RDF document types. RDF documents are the root class of all XML document types specified by RDF Schema.

RDF, RDF Schema and OWL (which is built on top of RDF Schema) are less generally adopted than XML Schema. Most XML parsers systems have a mode that will accept an XML Schema document used to validate the parsing of XML documents.

OWL

OWL is one of those annoying acronyms, similar to the recursive acronyms (e.g. PHP) where the letters of the acronym are not in the same order as the expanded name, Web Ontology Language.

OWL is build upon RDF Schema.

Comparative Analysis

Working Session Summary

1. A resource "schema" is required, either manually or programmatically, for the reporting system to work. (Requesting Workgroup agreement)

• A reporting system generally has no prior knowledge of the data it is going to report on. Thus, it requires a design phase to “configure” the reporting system so that it has some idea of the data it is going to deal with. The knowledge it gains at design time will be used to deal with data coming in, every time a report is run or a data warehouse loading is initiated.
• There are three ways that a reporting system can acquire the knowledge

i. A human, like a reporting administrator, has the knowledge and manually inputs them into the reporting system
ii. The reporting system has prior knowledge on the OSLC domain specification injected. (Note: This option alone would not allow reporting on custom extensions to the base OSLC specification.)
iii. A programmatic way to discover the knowledge from the domain service provider via a defined specification.
iv. A combination of the above.

• i and ii above are out of the scope of the OSLC-Reporting.
• The third one will not be mandatory, but highly recommended, for OSLC-Reporting.

Note: The approach i above relying on human manual inputs, while is a valid use case in some situation, has significant usability implication, and thus is highly discouraged unless there is a strong rationale for doing so.

2. A reporting system needs schema information for

1. displaying to the reporting system administrator what to expect for the resource
2. specifying the mapping of resource properties to reporting system internal data model
3. constructing a query for the resources to the resource service provider

3. Key information needed from schema

• Properties of resource that are of interest for reporting. (i.e. does not need to know all properties of the resource)

- name (e.g. http://purl.org/dc/terms/creator)
- type (e.g xsd:string)
- optionally, label (e.g. “Creator”) (require internationalization)
- optionally, description (e.g. “An entity primarily responsible for making the resource”) (require internationalization)

- optionally, queryable - can this property be used as a filtering criteria (default would be yes)

• If the property is of type “resource”, it may have its own properties

- properties of the resource property that are of interest for reporting

- name (e.g. http://purl.org/dc/terms/creator)
- type (e.g xsd:string)
- optionally, label (e.g. “Creator”)
- optionally, description (e.g. “An entity primarily responsible for making the resource”)

- optionally, queryable - can this property be used as a filtering criteria (default would be yes)

4. RDFS

An attempt was done to validate RDFS suitability for the above requirements. It is concluded that pure RDFS (without extension) would not be sufficient to meet requirement.

Extract from RDF Primer:

exterms:weight rdfs:domain ex:Book .
exterms:weight rdfs:domain ex:MotorVehicle .
For any given statement using this property, say:

exthings:companyCar exterms:weight "2500"^^xsd:integer .
in order for both the rdfs:domain statements to be correct, it must be the case that exthings:companyCar is both an instance of ex:Book and of ex:MotorVehicle.

An equilvalent OSLC example would be:

dc:creator rdfs:domain oslc-rm:Requirement .
dc: creator rdfs:domain oslc-cm:ChangeRequest .

oslc-cm:ChangeRequest001 rdf:type oslc-cm:ChangeRequest.
oslc-cm:ChangeRequest001 dc:creator "Xiang Dong" .
in order for both the rdfs:domain statements to be correct, it must be the case that oslc-cm:ChangeRequest001 is both an instance of oslc-cm:ChangeRequest and oslc-rm:Requirement.

Note: The issue is with rdfs:domain semantic and there is no other (AFAIK) rdfs vocabulary that would fit. However, extension to RDFS vacabulary could address this issue.

5. Prototypical Resource

A prototype of a resource could be a way to “describe” the properties of the resource. In fact, that seems to be the approach used in a few OSLC domain specification.
e.g OSLC-RM wiki uses this to illustrate the format of a requirement.

<?xml version="1.0" encoding="UTF-8"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:oslc_rm="http://open-services.net/xmlns/rm/1.0/"
xmlns:calm="http://jazz.net/xmlns/prod/jazz/calm/1.0/"
xmlns:acme="http://acme.example.com/xmlns/"
xmlns:dc="http://purl.org/dc/terms/">

<oslc_rm:Requirement rdf:about="http://rrc.example.com/requirements/24">
<dc:creator>Ian Green</dc:creator>
<dc:created>17 July 1900</dc:created>
<dc:modified>1 August 2009</dc:modified>
<dc:title rdf:parseType="Literal">
<xhtml:div xmlns:xhtml="http://http://www.w3.org/1999/xhtml">
Signal frequency <xhtml:b>triggering</xhtml:b> shall be modulation-exempt
</xhtml:div>
</dc:title>
<dc:description>Signal frequency triggering shall be compliant with ISO-7488-II Part 4.</dc:description>
<oslc_rm:links rdf:resource="http://rrc.example.com/requirements/24/linkCollection" />

<!-- Some properties whose meaning is not defined by OSLC RM -->
<acme:processLinkage rdf:resource="urn:process-id:6363" />
<calm:implementedByCollection
rdf:resource="http://rrc.example.com/requirements/24/implementedByCollection" />
<calm:validatedByCollection
rdf:resource="http://rrc.example.com/requirements/24/validatedByCollection" />
</oslc_rm:Requirement>
</rdf:RDF>

From the above prototype, one can deduce:

Resource rm:Requirement has properties:

- dc:creator
- dc:created
- dc:modified
- dc:title (type = literal)
- dc:description
- oslc_rm:links (type = resource)
- acme:processLinkage (type = resource)
- calm:implementedByCollection (type = resource)
- calm:validatedByCollection (type = resource)

So, the mandatory requirement of getting the “name” of the properties is met. The requirement of getting the “type” of the properties is partially met. RDF typed literal (rdf:datatype) should be able to address this for fully meeting this requirement.
e.g. <cq:dateSubmitted rdf:datatype="&xsd;date">2009-05-01</cq:dateSubmitted>

There is no information on the optional requirements, namely label and description. However, the values of the properties could potentially be some sort of a “description”.

From the above information, the Administrator selects properties dc:title and acme:processLinkage for reporting and like to filter by dc:creator=”John Smith”. The reporting system should be able to construct a query to the service provider.

?oslc_query=dc:creator=“John Smith”&oslc_properties=dc:title,acme:processLinkage&namespace=dc=”http://purl.org/dc/terms/”, acme=”http://acme.example.com/xmlns/”

The next step is to ensure that the properties dc:title and acme:processLinkage in the resultset of the query are programmatically identifiable by the reporting system for processing. This will be addressed in the Resource Query working sessions.

Thus, it seems that using a prototypical resource instance could be a way to satisfy the schema requirement for the reporting system. We need to further validate with a nested containment use case such as a architecture modeling resource.

6. It has been observed that Resource Schema is a cross domain topic, which needs to be discussed in a bigger context rather than in the local context of reporting. The reporting workgroup will identify schema requirements and use cases as input to this cross domain discussion. It is anticipated that the cross-domain discussion will take some time. In the meantime, the Reporting workgroup will base on the prototypical resource approach outlined above to continue progress, and will adjust accordingly when decision made.

Initial Conclusion

References

XML Schema Part 0: Primer Second Edition

XML Schema Part 1: Structures Second Edition

XML Schema Part 2: Datatypes Second Edition

---

RDF Primer

Resource Description Framework, (RDF) Model and Syntax Specification RDF Vocabulary Description Language 1.0: RDF Schema

---

OWL Web Ontology Language Overview

OWL Web Ontology Language Reference

---

Dublin Core Metadata Element Set, Version 1.1

Comments

Add your comments here:

To request a prototypical resource, perhaps we should define some query parameter, e.g. ?prototype=true

-- ArthurRyman - 07 Nov 2009

-- TackTong - 09 Nov 2009

Yes. Either a query parameter or in fact the prototype could just be a resource with a url.

-- TackTong - 09 Nov 2009

XML assumption

There seems to be an assumption or background missing from this discussion that is missing:

1) The reporting consumer needs a schema to define an XML resource

2) The schema is for a single resource or for the result of a query (ATOM + XML content)

4. RDFS

Not sure I follow why RDFS can't define this. Would it not be that a change request and requirement each have its own URI, therefore any statements "subject" would apply to that resource?

5. Prototypical Resource

Any consideration instead on using xsi:type attribute on elements? Seems that many people jump to rdfs:datatype .

On how to get the prototypical resource

Some other options could be:

a) custom content-type

b) entry for URL in service description document

-- SteveSpeicher - 13 Nov 2009

XML Assumption The assumption is we need a schema to define the resource (not necessarily has to be the XML representation) so that we can construct a query. The returned resultset of the query is inferred from the query itself.

RDFS My point is rdf:domain itself is not suitable for our purpose and we need another vocabulary for specifying property-resource relationship.

Prototypical Resource and how to get it Yes. We should have a discussion on this.

-- TackTong - 13 Nov 2009

-- StevePitschke - 23 Oct 2009