[Oslc-Automation] "Findings" in Availability spec, that also appear in the Automation 2.0 spec

[John Arwe]

> (1) Section "Introduction": "mime type handling". MIME is written in 
lower
> case, but should be upper case.

Suggest fix in 2.1, older ones optional.  It's a typo that's unlikely to 
be misunderstood.

> (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. @John, do
> you mean that I should just remove this sentence? Or make a "SHOULD 
exist
> for each resource" out of it?

There are layers of issues in that text actually, in some cases because 
our understanding of how best to manage changes over time is evolving with 
experience. 

1: specs don't "define" types.  vocabularies define them.  specs use them 
and constrain them ... the constraints are most often communicated as 
"resource definition tables", which can also be expressed as resource 
shapes, but in some cases text is used as well.  example of the latter: 
Automation 2.0's re-use of oslc:Property for parameter definitions, where 
it says something like: in the context of a parameter definition, the 
oslc:propertyDefinition should be omitted.

2: Read-only properties (typical example: modified/created dates) are 
typically supplied by the server.  So you won't see them in a POST request 
message body, you might well not see them in PUT or PATCH, but you expect 
them in GET responses.

The most accurate version I can come up with quickly is: replace defined 
with used, and requested with retrieved.  I think that preserves the 
spirit of the old text.

Probably worth feeding to the Core 3 TC so those drafts fix it.

> (3) Section "Resource XYZ", dcterms:identifier. Description is "A unique
...
> John mentioned "any time you see the word 'unique', you need to qualify 
it
> w/ some scope (of uniqueness).". I copied this description for the Avail
> spec draft. I can't remember that I see any scope definition for 
uniqueness
> in the Auto spec. Or did I miss it?

Just means we have the same problem elsewhere, not that other examples are 
correct.  Open an issue against 2.0 for it, or against 2.0 Common 
Properties.

> Besides that I think the concept of "unique identifier" is very common. 
Do
> you really think I need to specify something like a "unique proceeding
> number" or so?

Scope != implementation, algorithm, or format.  The common expectation on 
:identifier is that it's value is unique *within a single service 
provider*.  If you say unqualified-unique, and a client says your 
implementation has a bug because one of your :identifier values happens to 
match one of GreenHat's, where did they go wrong reading the spec?  They 
didn't; the spec was imprecise.  THAT's the issue - clients are going to 
build implementations using the specifications.

> (4) Section "Automation Provider Sub-Domains":

Fine to raise an issue against 2.0, but that doesn't clarify *your* intent 
*here* in Availability; is Availability's intent to constrain core, or 
refer to core, or something else?  Once you copy the text, each copy has 
to be fixed to agree with its in-context intent.

> (5) Section "Automation Provider Sub-Domains":

I thought we added sub-domains in 2.1, but whatever.  Certainly same 
comment would apply to all copies.
As to what applies here: if a default is actually needed (which is not 
clear to me, and I don't accept automatically in RDF), core:default might 
fit (we'd have to read its semantics carefully; personally I'd bet 
core:default was defined by a coder not thinking in RDF terms, we have 
learned things over time).  To the first issue though, if the service 
provider does not assert a sub-domain, then none is asserted, full stop. 
Clients simply act as if the sub-domain is unknown to them, which is 
exactly the truth.  If they choose some "magic value" to use internally to 
represent this state, that is their implementation choice but it's 
completely outside the spec.

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

Given the timing, in 2.1 we should certainly clarify that JSON ==> 
OSLC/JSON.  Core 2 might contain a blanket statement for 2-based specs to 
that effect already (but I doubt it - people aren't usually that good at 
anticipating things years in advance), or one could be added now to cover 
historical cases.  Certainly the Core WG should be made aware of the 
ambiguity so it's not propagated into the Core 3 drafts.


Best Regards, John

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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://open-services.net/pipermail/oslc-automation_open-services.net/attachments/20140718/00c6b9f3/attachment-0003.html>