Making it easier to write (and read) domain specs (topic for next meeting?)

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

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:  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
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