for Core 3 drafting - some issues found in Core 2-based specs, possibly common issues

[John Arwe <johnarwe@us.ibm.com>]

From the original [1] on open-services.net's
Automation WG list.  I suspect these were often copied from spec to
spec, i.e. Automation 2.0 is not their root source, so we should avoid
propagating them into the 3.x specs.


(2) Section "Automation Resource Definitions":
"For all resource types
defined in this specification, all required properties (those defined with
an occurrence of exactly-one or one-or-many) MUST exist for each resource
and must be provided when requested."

John's commented in the Avail spec draft to this: "Create requests
often
have looser restrictions." I'm not sure how to interpret this. 

Within the Core WG, I think we've had
enough historical discussions around this.  Net: resource definition
tables express constraints, and constraints for creation are often different
from constraints on update inputs and/or retrieval results.  Server-managed
properties like dcterms:modified are the poster child.


(3) Section "Resource XYZ", dcterms:identifier.
Description is "A unique
identifier for a resource. Assigned by the service provider when a resource
is created. Not intended for end-user display."

John mentioned "any time you see the word 'unique', you need to qualify
it
w/ some scope (of uniqueness).".

Our usual expectations for :identifier
are that it's unique within a SP, although technically it's implementation-defined.
 So the reliable consequence is that it is (at most) unique within
1 service provider; clients cannot depending on getting non-overlapping
identifiers once >1 SP is involved.



(4) Section "Automation Provider Sub-Domains":
Quote: An instance of an OSLC Automation service provider might provide
services for one or more particular automation sub-domains (e.g. test or
build automation). Automation service providers MAY declare sub-domain
information in the Service Provider document by specifying a sub-domain
value in the oslc:usage attribute on the oslc:Service resource in the
Service Provider document.  
Valid sub-domain values are:

John's comment: ":usage is permitted at other places in the SP
representation; not sure if you're attempting to constrain what Core allows
here, or not.  if not, this could be read to constrain core so you
need to
tweak; probably pointing to core instead of re-stating a subset of it."

I think in most cases the explicit MAY
on SP (vs on SP.Service, or other particular resources) is a poorly expressed
attempt to say that oslc:usage is the mechanism, and you can use it anywhere
Core says you can.


(5) Section "Automation Provider Sub-Domains":
Quote: An automation service provider which is a general-purpose automation
provider, or a provider not wanting to provide a sub-domain should provide
an oslc:usage value of http://open-services.net/ns/auto.
If no oslc:usage
attribute indicating a sub-domain is present, the default is assumed to
be
http://open-services.net/ns/auto.

Issue 1: the assumption that the lack
of an assertion is somehow invalid ("how can you have no default,
if it's optional?") or communicates nothing.

Issue 2: the conflation of a namespace
URI with a "domain" URI.  If domain==ns we were foolish
to invent a new term, if != then the identifiers cannot be identical.



(6) Section "Automation Service Provider HTTP
method support", column
labeled "JSON".

John's comment: "*which* JSON ?
...

Again, we've probably had sufficient
discussion in Core that people recognize the ambiguity now.  To some
degree we help by not carrying forward "OSLC JSON" into 3, but
in the end it may be better in the specs to just use the media type identifier
and be done with it; either in every spec, or have a table somewhere in
Core that says "whenever core 3-based domain specs say 'json', they
mean 'application/ld+json' unless otherwise noted".



[1] http://open-services.net/pipermail/oslc-automation_open-services.net/2014-July/000792.html

Best Regards, John

Voice US 845-435-9470  BluePages
Cloud and Smarter Infrastructure OSLC Lead