[OSLC-RM] Discussion on requirement factory
Simon Wills
simon.wills at integrate.biz
Fri Oct 30 09:21:50 EDT 2009
A belated response to Ian's request...
These comments are not intended to impact the current v1.0 specification
effort, except inasmuch we should try to avoid decisions now that will
need to be changed later (i.e. we should aim for evolution and
extension, not revolution). So these comments pre-suppose unwritten
future scenarios, but are based on real-world experience of working and
developing in the domain.
First a few assertions (in which the term 'requirement' is used broadly
to denote 'items in the RM domain').
* Many providers hold requirements within 'containers' (in the
case of DOORS called a 'module'). Containers typically exist within a
hierarchical tree structure like a file system. In the case of
providers that don't support multiple containers or a folder structure,
this generalisation collapses to the equivalent of a single container at
the root of the folder hierarchy.
* Containers will typically hold multiple requirements in an
ordered list. They may also exist in a tree hierarchy (let's call this
a 'requirement hierarchy' to distinguish from the 'folder/container
hierarchy' above). Again, this generalisation collapses for providers
that don't support these concepts.
* Links may exist between any two requirements to assert that
they are related in some way. Links may be between requirements in a
container, or between requirements in different containers.
* It is important to note that 'requirement hierarchies' and
'folder/container hierarchies' are logical trees, whereas collections of
links are logical graphs. While related, these structures differ in
important ways.
>From that baseline, what might we reasonably expect to achieve via the
REST API?
We take it for granted that we must be able to 'walk the tree' to find
any container, and any requirement within a container. Once we have
found a requirement, we can read, update and delete it (subject to
access rights, provider capability, etc).
When we create a requirement, we must be able to define where that new
requirement will appear within the hierarchies (i.e. within which
container, and where in the requirement hierarchy). I emphasise 'must'
- if we don't achieve this, the OSLC-RM API will be an interesting
academic curiosity, but won't deliver the value it needs. So (subject
to provider support, of course) we must be able to do things like create
a requirement as a following sibling of a given requirement, as its
first child, its last child and so on. We want to achieve this in a
generic manner that doesn't load unnecessary properties onto the
requirement resource (i.e. ideally we should need nothing other than its
URI), and also doesn't dilute the 'RESTfulness' of the interface.
If all we have is the URI of the resource, how can we do this? We
mustn't attempt to infer anything from the structure of the URI
(although 'readable' URIs may be a nice to have, we can't guarantee that
a given provider will provide them, and attempting infer information
from the URI string breaks one of TB-L's axioms in any case - see
http://www.w3.org/DesignIssues/Axioms.html#opaque).
My suggestion is that we take inspiration from XPath's predicate and
location path syntax. We can then define a set of URI modifiers that
can be very powerful. Let's assume that we are working within the
context of a requirement at http://my.example.com/requirements/24. From
this, we can use modifiers that allow us to 'walk' axes of the
hierarchy. For example:
* http://my.example.com/requirements/24?first-child is the first
child of our reference requirement
* http://my.example.com/requirements/24?last-child is its last
child
* http://my.example.com/requirements/24?following-sibling is its
next sibling
* http://my.example.com/requirements/24?preceding-sibling is its
preceding sibling
* http://my.example.com/requirements/24?ancestor is its parent
* http://my.example.com/requirements/24?child is the collection
of its immediate children
* http://my.example.com/requirements/24?descendant is the
collection of its children, their children, and so on
* http://my.example.com/requirements/24?ancestor-or-self is the
collection of the reference requirement and all its parents
and so on.
We can then adopt this syntax with POST, but also in other methods.
So:
* POST on http://my.example.com/requirements/24?last-child would
create a new requirement as the last child of the reference requirement
(even if it currently has no children)
* GET on http://my.example.com/requirements/24?last-child would
return the last child of the reference requirement in the hierarchy if
it exists (or 404 if there are no children)
* POST on
http://my.example.com/requirements/24?following-sibling would create a
new requirement as the next sibling of the reference requirement
* GET on http://my.example.com/requirements/24?child would get
the collection of all the immediate children of the reference
requirement (or 404 if there are no children)
* GET on http://my.example.com/requirements/24?ancestor would
allow you to walk back up the requirement hierarchy
* DELETE on http://my.example.com/requirements/24?descendant
would (if we chose to allow it) delete all children, children's children
and so on of the reference requirement
and so on. Where providers do not support hierarchies, suitable HTML
response codes can indicate this to the client.
This approach appears to have a number of benefits:
* It is general
* It can be used on both folder/container hierarchies and
requirement hierarchies
* It recognises that hierarchies are trees, with properties of
trees, and doesn't conflate hierarchies with link graphs
* It doesn't require us to add any information to the
requirement resource to reflect its context: all we need is its URI
There is one potential conflict with the emerging v1.0 specification's
description of the requirement factory. This states that requirements
are created by POSTing to the (single) requirement factory in the
service document, and notes that the specification does not provide a
means for the client to propose the URI of the newly created requirement
resource. Clearly, this could be revised in later versions.
I hope this contribution is helpful.
Simon
From: oslc-rm-bounces at open-services.net
[mailto:oslc-rm-bounces at open-services.net] On Behalf Of Ian Green1
Sent: 26 October 2009 15:54
To: Lachlan Macpherson
Cc: oslc-rm at open-services.net
Subject: Re: [OSLC-RM] Discussion on requirement factory
Thanks Lachlan - i go along with these suggestions but see them being
outwith the scope of the current specification effort, simply because
they will require some investigation and discussion. Currently, such
discussion is somewhat implementation-centric since we don't have
scenarios concerning, what would it be, "requirements organization"?
These would be interesting to consider for the future, but for the time
being I would hope to finesse such challenges.
Do you see that such pragmatism will yield a spec. which has value?
best wishes,
-ian
ian.green at uk.ibm.com (Ian Green1/UK/IBM at IBMGB)
Chief Software Architect, Requirements Definition and Management
IBM Rational
From:
Lachlan Macpherson/UK/IBM
To:
Ian Green1/UK/IBM at IBMGB
Cc:
oslc-rm at open-services.net, oslc-rm-bounces at open-services.net
Date:
14/10/2009 15:35
Subject:
Re: [OSLC-RM] Discussion on requirement factory
--------------------------------------------------------------------------
Simon Wills
Managing Director
integrate systems engineering ltd
m: +44 (0)7967 091824
t: +44 (0)1225 859991
f: +44 (0)1225 859993
e: simon.wills at integrate.biz
w: http://www.integrate.biz/
--------------------------------------------------------------------------
________________________________
Hi All,
If we did use the existing Service Discovery mechanism, I assume that we
would still need to add extra information to the RDF / XML of the
Requirement itself. The Service Discovery mechanism would allow us to
model a "parent/child" relationship but would not handle child order
information. Would this also mean that we potentially have 2 different
URLs for a requirement? One for editing / reading the Requirement and
one in the Service Discovery document for creating child Requirements.
I'm also not sure if this is subverting the use of the Service Discovery
mechanism for something for which it was not intended to be used.
I think the easiest solution would be to have a generic factory and have
extra information such as links that linked to parents / siblings to
provide the structure. As Ian has said, this is not very generic and it
would not be right to assume that all implementers of OSLC/RM would have
structures that conform to this.
Ian mentioned having structural properties on a Requirement. Another
possibility might be having something like a container Resource (Module
in DOORS) and having structure properties on that in the form of an
ordered tree of links-to-requirements. In this, the Requirements
themselves don't need to know where they live but it is up to some other
resource to capture their context and the same Requirement could be
specified in a number of different places.. This is just some initial
thoughts I had so I thought I would just share them.
Cheers,
Lachlan
From:
Ian Green1/UK/IBM at IBMGB
To:
oslc-rm at open-services.net
Date:
13/10/2009 13:25
Subject:
[OSLC-RM] Discussion on requirement factory
Sent by:
oslc-rm-bounces at open-services.net
________________________________
Hello fellow OSLCRMers,
I'd like to continue the discussion of how we best introduce requirement
creation into the specification. My current proposal, which I outlined
on the previous call, is to to use the service discovery mechanism.
That mechanism is part of the draft spec.
(http://open-services.net/bin/view/Main/RmServiceDescription
<http://open-services.net/bin/view/Main/RmServiceDescription> ). The
OSLC "Service Provider Catalog" provides a way to address a hierarchy of
RM-specific service documents.
You will recall from that meeting that I was somewhat uncomfortable with
this approach, as was Steve. One of the limitations of this approach is
that it cannot describe richer contexts - okay for the moment perhaps,
but limiting in the longer run. This reason alone is not good grounds
to reject it from RM 1.0. Steve had a concern that this approach was
not consistent across the other OSLC domains. I'd like Steve to put
this case since I feel that we're rather generalizing from a sample size
of one (the CM specification).
I'd like to provoke some discussion on how we move forward with this
issue.
The problem is:
How do we cater for the creation of resources in some particular
context. In the case of DOORS, requirements live in a structure - in a
ordered tree, called a module in DOORS; in RRC, requirements are
organised into a folder hierarchy.
Here are some options for modelling this context:
- reflect the context in the structure of the service documents
(this is the approach i refer to above)
- describe an association between a requirement and the places in
which it occurs (or "bound").
- ignore the context and require that providers deal with the
inability to express context in OSLC RM.
This last option is really there only for completeness - i can't see
this being valuable.
On the second option, one can imagine structural properties on a
requirement which describe, for example, tree position, or perhaps
containing folder and so on. We would have to work to generalize this.
If a requirement is REQUIRED to have such context described, then the
specification MUST describe this structure. If we make such
descriptions OPTIONAL, the specification can say less, but that also
lessens the value since a client cannot uniformly treat all providers.
A variation on option 1 is to mimic the service provider catalogue
structure, but to do so wholly within the scope of OSLC RM - so that
"consistency" issues can be finessed. A family/structure of factories
could be described. The spec. could admit "progressive" factory
discovery - here I intend that a client would dig to more specific
factories, but only as required/supported by the provider. In the case
of DOORS, a usable factory would be available at the module level, but
additional, more fine-grained factories could also be discovered inside
that context if the client wanted to make a requirement at a particular
node in the requirement tree. This option offers a little more
flexibility, and we could base some of it on what is already present at
the catalogue level.
option 1 (both variants) are really an instance of option 2.
I invite your thoughts and comments.
best wishes,
-ian
ian.green at uk.ibm.com (Ian Green1/UK/IBM at IBMGB)
Chief Software Architect, Requirements Definition and Management
IBM Rational
________________________________
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
_______________________________________________
OSLC-RM mailing list
OSLC-RM at open-services.net
http://open-services.net/mailman/listinfo/oslc-rm_open-services.net
<http://open-services.net/mailman/listinfo/oslc-rm_open-services.net>
________________________________
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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://open-services.net/pipermail/oslc-rm_open-services.net/attachments/20091030/e4637c41/attachment-0003.html>
More information about the Oslc-Rm
mailing list