Re: [oslc-core-comment] Comments to the Public Review of the OSLC Core 3.0 Specifications

["Jim Amsden" <jamsden@us.ibm.com>]

Tim,
Thank you for your thoughtful and thorough
review of OSLC Core. The TC really appreciates the effort you put into
this and are carefully reviewing your suggestions for future actions. To
get things started, I've included my comments on your items below. These
do not necessarily reflect the views of the TC as a whole, but are rather
intended to stimulate further discussions in order to raise and address
any appropriate issues.


### 1) Representation
of resources: ###

Its up to the server
implementations to decide whether 2.0 compatibility is a requirement or
not. The specification only makes sure its possible, it doesn’t demand
it. In addition, its the OSLC domains that specify the actual resource
representation requirements, not Core. Core has to open enough to allow
support for any domain. 

### 2) Definition
of data structures:  ###
# 2a) Constraint
language for data structures

Instance shapes
are not mandatory for OSLC 2.0 and are not even specified formally for
the OSLC 2.0 domains. So 3.0 shouldn’t require it either. Plus the role
of ResourceShapes is to provide constraints on domain vocabularies for
a specific purpose. We would expect different servers to have different
constraints for different usages of the OSLC (or other) domains. 

OSLC vocabularies
are built on RDF and utilize open-world assumptions to reduce coupling
between tools. Tools should not expect vocabularies + shapes to result
in closed-world schemas, this would be taking a step backwards and create
the very coupling that OSLC was intended to avoid. Rather tools should
be built to minimally support the domain vocabularies, but expect those
vocabularies to be extended, and that different constraints might be applied
for different purposes. That is, they should be built to interpret what’s
given in terms of instances and constraints, not to expect a fixed set
to be the only thing provided.

Tools can implement
the vocabularies and constraint validation and interpretation any way they
want. But they should be built to be open to support vocabulary extensions
and additional or different constraints as long as both are provided in
a standard way: OWL ontologies and ResourceShapes.

# 2b) “Instance
Shape”: Identification/Mapping of the data structure

This is a common
issue when attempting to represent closed-world schemas (that scope attribute/column
names in classes/tables) as open-world ontologies. Typically these mappings
require establishing mappings between specific class::attribute and OSLC
property URIs, not the individual attributes.

What a closed-world
tool is able to or decides to implement is up to the tool. It may not be
able to support certain kinds of extensibility, or deal with information
that does not fit in its schema. That’s fine, and such a tool is free
to express constraints on what it can produce and consume, or to ignore
information provided from other servers that does not fit its persistence
schema/model. But it is not possible to codify these constraints in the
standard or OSLC would miss one of its primary goals for openness and extenibility.

# 2c) “Instance
Shape”: valueType

Again, OSLC core can’t close the world up to that
extent, it must be open for broad applicability. Tools are free to support
discovery of specific constraints they require in a standard way using
OSLC discovery and ResourceShapes.

# 2d) “Instance
Shape”: creating new resource shapes

The OSLC discovery
capabilities allow a Service to advertise its supported creation factories
which can (optionally) include a resource shape constraining what resources
can be created by that factory. Similarly an LDPC can return a link header
advertising what resource types can be created in that LDPC. But these
are not required. An LDPC could support more than one RDF type, or creation
of any RDF type. That’s a specific usage that cannot be coded in the standard.
Rather the standard describes a standard way of expressing the discovery
and constraints. 

# 2e) “Instance
Shape”: additional properties for “core#Property”

These are good
suggestions, but perhaps would be better addressed by emerging new standards
such as SHACL. We tried to minimize the changes to ResourceShapes in order
preserve OSLC 2.0 compatibility and leave room for SHACL. In any case,
toosl are free to add these properties to their resource shapes, and OSLC
provides a standard way to do that.

# 2f) “Instance
Shape”: oslc:allowedValues

See section 4.1
Overview and the following paragrpah:
The value of a
defined property may be constrained to take one of an allowed set of values.
In some cases, the allowed set of values may be large and be used in many
shapes. In this case it is useful to put the allowed values in a separate
resource so they can be easily reused. The box labeled “Allowed Values”
represents a resource of rdf:type oslc:AllowedValues.
The arrow labeled “allowedValues” represents the relation between a defined
property and its set of allowed values. The predicate of this relation
is oslc:allowedValues.

# 2g) “Instance
Shape”: enumerations

ResourchShapes
allowedValues could already reference an OWL class or list of individuals
that specified what enumerations are allowed. Again, we are attempting
to limit future investment in ResourceShapes in order to maintain compatibility
and leverage future investments in W3C SHACL.

Domains would be
free to define their own approach to enumerations. There’s some variability
in this space since enumerations are not explicitly defined in RDF. OSLC
Core recommends and uses a particular approach for its purposes. But domains
could define something else, including the proposal you made.

### 3) General
aspects of resources

This would be handled
in OSLC core by utilizing LDP for generic containment. Domains are free
to define additional properties to represent their semantics. 

### 4) Formatted
Text ###

The formatting
of a particular property is defined by the domain vocabularies and shapes,
not OSLC Core. That said, OSLC Core does define how it handles properties
that contain markup. These are the clauses for dcterms title and description:
     
  0.        dcterms:title is used
to provide a summary of oslc:ResourceShapeand oslc:Propertyresources. Its value SHOULDbe a literal of type rdf:XMLLiteral that is valid content for an XHTML
<span> element. If the value contains no XML markup then it MAYbe represented as a plain text literal or xsd:string. 
     
  0.        dcterms:description
is used to provide a description of oslc:Propertyresources. Its value SHOULDbe a literal of type rdf:XMLLiteral that is valid content for an XHTML
<div> element. If the value contains no XML markup then it MAYbe represented as a plain text literal or xsd:string. 

Domains may follow
similar conventions, but OSLC Core intentionally avoids over-constraining
what domains can define and what servers implement. 

### 5) Authentication
###

OSLC Core addresses
the in section 4.2 Authentication: services MAY provide HTTP Basic Authentication
and SHOULD provide OIDC. OSLC Core could not mandate any specific authentication
mechanism since there is tremendous  variability in this space that
tend to be platform specific and evolving.

Jim Amsden, Senior Technical Staff Member
OSLC and Linked Lifecycle Data
919-525-6575




From:      
 Tim Meyer <tim.meyer@requisis.com>
To:      
 "oslc-core-comment@lists.oasis-open.org"
<oslc-core-comment@lists.oasis-open.org>
Date:      
 09/29/2016 10:23 AM
Subject:    
   [oslc-core-comment]
Comments to the Public Review of the OSLC Core 3.0 Specifications
Sent by:    
   <oslc-core-comment@lists.oasis-open.org>

---

Dear OSLC TC members,
 
we recently started to evaluate the possibilities
of OSLC 2.0 and the state of current tool-implementations. In particular
we are interested in the interoperability of requirement management tools.
We are glad to see that there is an active development for the Core 3.0
specifications. We just learned about the Public Review some days ago and
we missed the deadline. Still, we would like to use the chance to comment
on some topics that came to our mind, when working with OSLC 2.0 and reading
the new 3.0 specifications.
 
To start with we would recommend update
the Core 3.0 webpage on open-services.net (http://open-services.net/wiki/core/Specification-3.0/).
Our first impression was that the development of core 3.0 is dead, since
the last update was November 2013. We found the Public Review only by chance.
 
Before I come with our comments, I think
I would be helpful to explain our background. For the last month/year we
helped a customer to introduce ReqIF for exchanging requirements. As preparation
steps we tested the ReqIF-Implementations of IBM DOORS, IBM DOORS Next
Generation and Polarion extensively. We also performed test-exchanges with
partner companies of our customer. Thereby we also learned a bit about
the problems and shortcomings of the ReqIF implementation in various other
RM-Tools like PTC Integrity and Siemens Teamcenter. We therefore had the
chance to get a bit of experience of what can go wrong when introducing
new Standard and the obstacles on the way to a productive use. OSLC seems
to be an interesting alternative or supplement for ReqIF in some use cases,
offering features ReqIF was not designed for. It therefore arouse our interest.
Some of the following comments may concern
a future “Requirements Managements 3.0” Domain Specification, but we
think that most concerns are general enough to be considered for the Core
3.0 Specification.
 
 
### 1) Representation of resources: ###
Changing the support of RDF/XML from “must”
to “should” will break the backward compatibility.
 
 
### 2) Definition of data structures:  ###
# 2a) Constraint language for data structures
One of our most important concerns was
already addressed in 3.0: To move the “Instance Shape” from the appendix
to the specification itself. Also, we strongly recommend making the use
of the “instanceShape” property mandatory for all resources! Without
a rigid and machine-readable definition of the data structure of a resource,
a communication and exchange of data via OSLC is simply impossible for
most scenarios we can think of.
The Core 3.0 specification states, that
other constraint languages such as SHACL could be used. We understand that
this increases the flexibility. And any domain specification could anyway
be more restrictive.  But we are worried, that this flexibility will
lead to a lot of isolated tool-specific implementations, all being “OSLC-Conform”,
but none of them can understand each other. Also adding support for other
domains into one’s own existing implementation could become a pain, if
a completely new technology-stack has to be implemented each time. So it
could be beneficial for the acceptance of OSLC 3.0 if you stick to the
“Instance Shape”-concept.
We think that the success of a Standard
does strongly dependent on the premise, that a tool that implements the
standard must not worry about how any other tool is doing the implementation!
This point is also expressed in some of the following comments on more
specific topics.
 
# 2b) “Instance Shape”: Identification/Mapping
of the data structure
From ReqIF we know how important it is,
that each tool can map the data structure of the format to its one internal
data structure. To achieve that, not only the resources themselves have
to be identifiable, but also the elements describing the type/characteristics
of the resource and its properties (“resource-type” and “property-type”).
If a resource is described by an “Instant
Shape”-resource, the URI of the “Instant Shape” can be used for mapping.
(e.g. for DOORS Next: to an “artefact type”).
In an “Instance Shape” resource, properties
are defined in ”Property”-resources. These resources are defined inline
within a “Instance Shape”-represenation. Therefore they may or may not
have an URI. Here we recommend changing the “oslc:property” representation
from “Inline” to “Resource”. Then the URI can be used for mapping (e.g.
in DOORS Next: to an attribute definition). As far as we understand, currently
only the property name can be used to identify a oslc:Property resource,
but in many tools (e.g. DOORS Next, Polarion) the name of an attribute
does not need to be unique.
 
# 2c) “Instance Shape”: valueType
Within an “oslc:Property”-resource the
oslc:valueType is “zero-or-one”. We recommend to change this to “exactly-one”.
Without knowing the basic datatype of the property is hard for a tool to
interpret the contained data.
 
# 2d) “Instance Shape”: creating new
resource shapes
As far as we understand, new resources
can only be created on the basis of “Resource Shapes” that are known
to the server. It would be helpful to have the possibility to tell an OSLC-Server
about a new “Resource Shape”, so that resources of this type can be created
subsequently. 
 
# 2e) “Instance Shape”: additional properties
for “core#Property”
We recommend adding the two optional properties
“minValue” and “maxValue”, to set a limit for the range of allowed
values for Integer, decimal, float and double. These parameters are e.g.
used in the ReqIF datatype definitions and some RM-Tools (IBM DOORS and
IBM DOORS Next Generation).
 
# 2f) “Instance Shape”: oslc:allowedValues
From the text, it wasn’t clear to us how
an “oslc:allowedValues”-Resource is actually defined.
 
# 2g) “Instance Shape”: enumerations
In our experience enumerations are very
important. The specification only recommends a way to specify enumerations
in part 7. In the document part 6 (“Resource Shape”) enumerations are
not mentioned at all. For the application of OSLC to requirement management
it is absolutely necessary to have the possibility do define enumerations.
We recommend to add a way to define enumerations
to part 6 (“Resource Shape”) of the specification. We also recommend
that there is a defined way to specify the order of the literals. 
A simple way could be:
a) Define a new Resource “EnumLiteral”,
which has the properties “number” (integer, to define the order), name
“string” and “value” (string).
b) Define a new (zero-or-many) property in “core#Property” with “EnumLiteral”
as range. It could be named “enumLiterals”.  These are all the allowed
literals.
c) Define a new “Literal Value Type” for the property “oslc:valueType”
called “enumeration”. The allowed value is an URI to an “EnumLiteral”-resource.
This concept is similar to way it is done
in ReqIF, where it has proved to be useful in practice.

 
### 3) General aspects of resources
In the RM-world most tools are representing
requirements within a hierarchical-structure. This structure carries important
semantic information. We could imagine that this is also the case in other
domains. We would therefore recommend to add optional “parent” and ”child”-properties
(valueType “Resource”) to every resource. Maybe also something like “sibling-nr”,
to define the order of siblings.
 
 
### 4) Formatted Text ###
From our experience with ReqIF we know
that the transfer of formatted text can cause a lot of trouble. In case
of requirements, formatted text is very important, if not the most important
aspect. A user has to rely on the assumption, that an exchange partner
can display any formatted text correctly in his tool. If e.g. a bullet
list would be formatted in a way that another tool does not support, important
information may be lost. In our opinion this is a huge factor for the acceptance
of a standard (at least for RM). The problem is that all tools we have
worked with have to translate the formatting in their own formatting-style.
They are not simply rendering the content in a browser, since they must
provide editing functionality.
We recommend adding a dedicated “XHTML-Literal”
to the list of “Literal Value Types”. It could be based on “rdf:XMLLiteral”,
but the content that is allowed is restricted. The must only contain a
XHTML <span> element, whereby only a reduced set of XHTML-Tags is
allowed. The list of allowed tags could be taken from the ReqIF-Standard.
Looking at the trouble we had in the past
with this topic, we can hardly imagine that text, formatted in full XHTML,
will not result in a lot of incompatibilities. Also writing an implementation
will become a pain for the developer.
 
 
### 5) Authentication ###
For some authentication methods a user
interaction is necessary (as e.g. 3-legged-OAuth). It would be very helpful,
if an implementation would always offer at least one way to avoid this
(e.g. with 2-legged-OAuth or HTTP basic authentication). This is needed
to facilitate automatic data transfer. Maybe it should be mandatory to
implement at least one authentication method, which does not require a
user to become active?
 
 
Best regards,
Dr. Tim Meyer
 
REQUISIS GmbH
Walter-Benjamin-Platz 8
D-10629 Berlin

---

Diese E-Mail enthält
vertrauliche und/oder rechtlich geschützte Informationen. Wenn Sie nicht
der richtige Adressat sind oder diese E-Mail irrtümlich erhalten haben,
informieren Sie bitte sofort den Absender und vernichten Sie diese Mail.
Das unerlaubte Kopieren sowie die unbefugte Weitergabe dieser Mail ist
nicht gestattet.

This e-mail may contain confidential and/or privileged information. If
you are not the intended recipient (or have received this e-mail in error)
please notify the sender immediately and destroy this e-mail. Any unauthorized
copying, disclosure or distribution of the material in this e-mail is strictly
forbidden.


REQUISIS GmbH
Sitz/Domicile: Berlin
Registergericht/Court of Registry: Amtsgericht Berlin Charlottenburg
HRB Nr./. Commercial Register No.: 114602
Steuernummer / Tax-ID: 27/490/31574 | DE815208474
Geschäftsführer/General Manager: Nikolai Stein-Cieslak

Wichtiger Hinweis: Die vorgenannten Angaben werden jeder E-Mail automatisch
hinzugefügt und lassen keine Rückschlüsse auf den Rechtscharakter der E-Mail
zu.

Important Notice: The above information is automatically added to this
e-mail. This addition does not constitute a representation that the content
of this e-mail is legally relevant and/or is intended to be legally binding
upon REQUISIS GmbH.