Re: [oslc-core] Making it easier to write (and read) domain specs - rdfs:range vs expected range - where is that defined?

[Martin P Pain <martinpain@uk.ibm.com>]

Thanks for the clarification Ian.

Do you know where we define that?



Martin Pain
Software Developer - Green Hat
Rational Test Virtualization Server, Rational Test Control Panel
OASIS Open Services for Lifecycle Collaboration - Automation technical
committee chair

E-mail: martinpain@uk.ibm.com Find me on:  and within IBM on:

IBM United Kingdom Limited
Registered in England and Wales with number 741598
Registered office: PO Box 41, North Harbour, Portsmouth, Hants. PO6 3AU



From:      
 Ian Green1/UK/IBM
To:      
 Martin P Pain/UK/IBM@IBMGB,

Cc:      
 oslc-core@lists.oasis-open.org
Date:      
 16/07/2014 14:42
Subject:    
   Re: [oslc-core]
Making it easier to write (and read) domain specs (topic for next meeting?)

---

Hi Martin
Range in the tables is not rdfs:range.
 The meaning of Range is the meaning that you are proposing for "Expected
Range".  So a new column is not necessary. 

best wishes,
    -ian

ian.green@uk.ibm.com (Ian Green1/UK/IBM@IBMGB)
IBM Rational

<oslc-core@lists.oasis-open.org> wrote on 14/07/2014
13:43:06:

> From: Martin P Pain/UK/IBM@IBMGB
> To: oslc-core@lists.oasis-open.org
> Date: 14/07/2014 13:43
> Subject: [oslc-core] Making it easier to write
(and read) domain 
> specs (topic for next meeting?)
> Sent by: <oslc-core@lists.oasis-open.org>
> 
> As part of writing the OSLC Actions Specification and OSLC 
> Availability Specification (as part of the OSLC Automation WG), 
> there are a few things that have come up that I think we could 
> address in v3 to make it easier both to write specs and to read specs.
> 
> (tl;dr? Find the "***" markers) 
> 
> 
> Firstly, a small idea: 
> 
> At John Arwe's prompting, I tend to prefer describing properties in
> terms of something along the lines of "it is expected that the
> target resource be of type X but this is not necessarily always the
> case." This is because "range" in the resource type
properties 
> tables is rdfs:range, and so has RDF Inference consequences. That
> is, by stating an rdfs:range, you are asserting that ALL targets of
> that property are of that type, even if they are not stated to be
so
> anywhere else. (Sometimes this makes sense, for specific properties,
> but less so when we're aiming for reusable ones.) 
> 
> *** So I propose that we add a new row into the property tables (and
> possibly a new predicate into resource shapes? or vocab defs? I propose
both) 
> for this "Expected Range" *** 
>  - which is a hint to the people implementing consumers, rather
than
> an assertion of something that can be inferred. This would be in 
> contrast to the "Implied Range (rdfs:range)". 
> 
> There could also perhaps be a third one "REQUIRED Range"
(ref 
> RFC2119) which is saying that if the target is not of that type then
> it is not conforming to the spec, but this means that other specs
> can reuse the term without limitations of rdfs:range on it. Or it
is
> more of a resource shape thing than a vocab thing. (However I'm not
> 100% convinced of the usefulness of this one.) 
> 
> 
> Second, larger idea: 
> 
> In the Actions spec, in some areas rather than saying "the client
> MUST" we said "in order to do X, the client performs steps
A, B and 
> C". So rather than normative requirements, just defining what
it 
> means to do a certain thing. Then the client can decide whether or
> not it wants to do X, rather than confusing the spec with 
> conditional MUSTs on the client. Do you think this is a pattern or
> an anti-pattern? 
> 
> So, I wonder if it would be easier to write the domain specs (less
> so the core specs) if we actually tried to reduce the number of 
> MUSTS - especially on the client - and defined things more as "in
> order to do X, the client performs steps A, B and C" for the
client,
> and "in order for the server to expose/afford L, it does/exposes/
> sets M, N O and P". I guess I ought to come up with some examples,
> but I'm a little short on time right now. There would still have to
> be some MUSTs ("if the server/client does F, then it MUST do
G"). 
> We might then be able to be more scenario-driven (which would make
> reading easier) as it's less a collection of MUSTs and MAYs, and 
> more a definition of how to achieve things. We could then put the
> MUSTs that we do need for minimum interoperability into a 
> "conformance" section, which references the other definitions
of how
> to do things for its full normative meaning. (Perhaps some specs 
> already tried doing this, but it's not what I've picked up from my
> reading & editing.) 
> I expect this would avoid the need for some of the boilerplate in
> the domain specs, such as the tables of MAYs/MUSTs for media type
> support & dialog/query capability support for each resource type,
> unless it really needed to set these to something specific (it could
> refer back to core for some defaults). I also find the lists we have
> in the "compliance" sections at the moment (e.g. http://open-
> services.net/wiki/automation/OSLC-Automation-Specification-
> Version-2.0/#Compliance) to take up a lot of space with not much 
> value to the meaning of the spec, and making it harder to read If
> these were scenario- or behaviour-oriented (and those scenarios or
> behaviours then stated that they had a dependence on things like 
> unknown properties and content, perhaps transitively through a 
> behaviour such as "to create a resource using a Creation Factory").
> (We could trial this with the Availability Specification - which is
> about automation for controlling high-availability & redundancy
> groups of systems). 
> 
> *** The best I can come up with a concrete for a proposal here is
> "to make the compliance tables and domain spec definitions more
> scenario- or behaviour-oriented", but that's a bit abstract.
*** 
> 
> 
> So, can you follow those two trains of thought? And do you agree or
> disagree with the direction? If I haven't made myself clear (or used
> too many words) let me know.
> 
> Thanks,
> 
> Martin Pain
> Software Developer - Green Hat
> Rational Test Virtualization Server, Rational Test Control Panel
> OASIS Open Services for Lifecycle Collaboration - Automation 
> technical committee chair 
> 
> E-mail: martinpain@uk.ibm.com
> Find me on: [image removed]  and within IBM on: [image removed]
  
> 
> [image removed] 
> 
> 
> 
> 
> IBM United Kingdom Limited
> Registered in England and Wales with number 741598
> Registered office: PO Box 41, North Harbour, Portsmouth, Hants. PO6
3AU
> Unless stated otherwise above:
> IBM United Kingdom Limited - Registered in England and Wales with
> number 741598. 
> Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire
PO6 3AU
> 
> Unless stated otherwise above:
> IBM United Kingdom Limited - Registered in England and Wales with
> number 741598. 
> Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire
PO6 3AU

Unless stated otherwise above:
IBM United Kingdom Limited - Registered in England and Wales with number
741598. 
Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6
3AU