Comments on v1.0 Specification Documents from Integrate - 7 Sep 09

This note provides consolidated comments on the draft v1.0 specification documents from Integrate. We recognise that these documents are at an early stage, and so some comments may appear unfairly detailed - if so, we apologise: they are intended to be constructive!

Immediate Issues

Changing Requirements

Scenario B, step 5 calls for the ability to change a requirement. This would presumably be achieved by a PUT on the requirement resource, but this method has been left undefined in the REST API document.

img: 2009-10-1 CLOSED: Agreed, the specificaiton now includes requirement creation (factory and delegated UI)

scbw: 2009-10-14 UPDATED: Sorry, this is actually a separate issue. The issue of requirement creation is now being addressed, but this comment relates to modifying an existing requirement resource. Scenario B, step 5 is "The requirement is updated to reflect this process". To achieve this, the requirement resource would need to support PUT, but this is currently listed as undefined. Note: I am not necessarily suggesting that we expand the scope of v1.0 even further - I'm just pointing out an inconsistency.

img: 2009-10-27: I agree; I've updated the spec. to support PUT on requirement resources. Marked my mis-understood issue as closed and marking yours as UPDATED.

scbw: 2009-10-28: CLOSED: agreed.

Attributes

The v1.0 documents do not allow for attributes on requirements (or links). This is a useful simplifying assumption for v1.0, but is it sufficient to meet the requirements of the v1.0 scenarios? e.g. scenario B calls for the need to assign requirements to different delivery milestones, and suggests the use of attributes to achieve this.

img 2009-10-1 CLOSED: The specification does not exclude attributes because the representation of those resources is open. This means that providers can have attributes if they want, but that this is outwith the scope of the OSLC specification.

scbw: 2009-10-14 CLOSED: Agreed for v1.0. We have agreed separately that we may want to re-assess the 'standardised' set of attributes on requirement (and link) resources after v1.0.

img: agreed.

Link Resource Definition - Standardised Link Types

I have been uncomfortable about the idea of standardising link types (albeit with a SHOULD rather than MUST), since my experience from years of consulting is that everyone does things differently and will give you chapter and verse about why their way is the right way and everyone else's way is wrong. Having said that, I am persuaded that there is a minimal set of link types that do merit standardisation - provided that there is provision in the future to handle any arbitrary link type defined by a user to meet a specific need.

The first relationship that I would expect to see in this minimal set of link types is that between requirements themselves (conventionally satisfies / satisfiedBy). This is omitted from the Link Resource Definition, presumably because it is not considered necessary to support the specific scenarios for v1.0. This is possibly true, but only on a narrow interpretation of the scenarios. Step 4 of scenario B calls for 'elaboration and/or refinement of the requirement'. In my experience, this will almost always lead to derivation of lower-level requirements, linked back to their defining requirement via satisfaction relationships.

img: 2009-10-1 UPDATED: yes, we agree, but concede that this is outwith the scope of v1.0. I've removed the link type information that was present in the link resource definition.

scbw: 2009-10-14 CLOSED: Agreed. A discussion document for how we address this after v1.0 is at Standarised Link Types.

Link Resource Definition - 'Validate' Link Type Terminology

I would strongly recommend that we avoid using the term 'validate' (as in http://open-services.net/rdm/linktypes/validatedBy and http://open-services.net/rdm/linktypes/validates).

While I understand that some audiences will not immediately recognise this issue, and that the term 'validate' is simply a label, it is important to understand that:

a. The terms 'verify' and 'validate' are often defined very precisely in a given environment; but

b. There is no guarantee of consistency (either in common practice, or in standards) as to what these terms should mean.

It is generally accepted that there are two distinct concerns - correctness with regard to specification (i.e. 'did we build the thing right?') and correctness with regard to intent (i.e. 'did we build the right thing?'). Both of these concerns are relevant to OSLC RM. They are often (but not always) labelled as 'verification' and 'validation' respectively.

My understanding of Scenario A is that it involves establishing correctness with regard to specification - and yet the term 'validate' has been used. This is not wrong - it is just an indication of the inconsistency in the use of terminology from person to person and/or organisation to organisation.

Since OSLC RM needs to represent links that capture both concerns, I would recommend that the non-specific term 'qualify' be used instead (as already used in the definition of the link types). Hence the two link types would become http://open-services.net/rdm/linktypes/qualifiedBy and http://open-services.net/rdm/linktypes/qualifies.

Link Resource Definition - 'Implement' Link Type Terminology

Although this is a lesser concern than the use of the 'validate' terminology, the term 'implement' may also cause problems in the future. For example, what is the relationship between a design artefact and a requirement? Does the design not implement the requirement?

There is no right answer to observations of this nature, but it simply illustrates the peril of trying to standardise terminology!

Link Resource Definition - ICR terminology

Why use the specific term 'ICR'? This suggests a greater degree of process specificity that was, I think, intended. Indeed, the process described in scenario A (in which there is the intermediate step of breaking down requirements into implementation requests before they are auctioned) will be alien to some readers.

For the purposes of the v1.0 specification, I suggest using a less specific term - maybe 'implementation request', or perhaps 'work item' would be better.

Link Factory versus Link Collection Resources

I found the final section of the Link Resource Definition document to be confusing, since the roles of link collection and link factory appear somewhat mixed up.

Link factories are for creating links, using POST. As specified, we have a global link factory (that supports POST, but not GET) and a series of requirement-specific link factories (that support POST, but which also support GET to return a link collection). This means that link collections are returned in the type rm:LinkFactory, which seems slightly counter-intuitive from the perspective of naming .

img: UPDATED 2009-10-1: i've made some changes and hopefully clarified.

scbw: CLOSED 2009-10-26: Agreed

The difference in behaviour between global and requirement-specific link factories makes this feel like a slightly asymmetric solution, and the conflation of link factories and link collections confused me - but I haven't come up with a better solution.

More specifically, the final section of the Link Resource Definition document states 'Notice that entries in a LinkFactory? are inlined, unlike the entries is a RequirementCollection? '. Why? It seems a slightly strange and unnecessary constraint (and it is inconsistent with the definition in the REST API document that describes a link collection as a collection of references to links).

Why can't links in link collections be expressed as either inline literal values or references to a Link resource? This collection may be large, and so returning inlined data may be inefficient if, say, all you want to do is to count the number of links on a given requirement. (Note - this reflects part of Issue 7).

img: UPDATED 2009-10-1: i suggest we discuss this on our biweekly call.

scbw: CLOSED 2009-10-26: Complete

Link Factories in Requirement Collections

The Requirement Collection Resource Definition document states that a requirement collection includes a reference to the rm:links link factory associated with that collection. The behaviour associated with this link factory is not defined (i.e. it will presumably support GET to get the collection of links associated with the requirement collection, but will it support POST?).

img: 2009-10-1 UPDATED: updated the specificaiton to say that a GET on a factory is undefined.

scbw: CLOSED 2009-10-26: Agreed

Link Symmetry

The REST API document states that 'A requirement-specific factory is only for the creation of links whose source is that requirement'. In addition, the Requirement Resource Definition document states that a GET on the rm:links resource in a requirement fetches the collection of links whose source is that requirement.

This asymmetrical approach is how DOORS works at present, but this asymmetry has caused a fair amount of pain over the years, and there seems no reason for it.

I would much rather see a symmetrical treatment of links: let the requirement reference all links (incoming or outgoing) and let the definition of the link determine whether the requirement is the source or the target.

Surely this approach makes it much easy to navigate links in either direction?

img: UPDATED 2009-10-1; as discussed, this was a misconception which we address during a call. I updated the examples to make it clear that there is no asymmetry.

scbw: CLOSED 2009-10-26: Agreed

Access Controls

This may be beyond the realm of the v1.0 scenarios, but should we not recognise the existence of access controls and the consequence that some resources may be unreachable. Hence, a GET on a requirement resource for which the user has no access would be expected to return 401 Unauthorized.

Or is the reference to RFC 2617 HTTP Authentication sufficient to achieve this?

img: 2009-10-1 UPDATED:Yes, the provider may return an unauthorized response as it sees fit. the v1.0 spec. does not reach into any security models.

scbw: 2009-10-14 CLOSED: Understood.

Forward-Looking Issues

Managing Link Types

The v1.0 specifications acknowledge the existence of link types but omit (deliberately) any description of how we will manage them. How will we manage link types in the future?

For example, there is likely to be a need to GET a list of link types. It would not be unreasonable to achieve this with a GET on a link factory resource - but v1.0 defines the behaviour of GET on link factories as returning a link collection. Does this suggest that the conflation of link factory and link collection may cause problems in the future?

img: UPDATED 2009-10-1; agreed need to have link types, but don't think we ought to anticipate at this level of detail.

scbw: CLOSED 2009-10-14: Agreed. See also discussion document at Standarised Link Types.

Minor Issues

• RmLinkResourceDefinition document should be re-titled Link Resource Definition for consistency.
  • img:UPDATED 2009-10-1:done.
  • scbw: CLOSED 2009-10-14
• Link Resource Definition document states that providers must support both RDF/XML and JSON representations of link collections, but the API document states that only RDF/XML is required.
  • imgUPDATED 2009-10-1- json now out of spec, so removed.
  • scbw: CLOSED 2009-10-14
• The section on Factory Resources in the REST API document states 'Factory resources allow the creation of link and requirement resources as weand'. (Minor point - gibberish at the end of this sentence). This is not consistent with the section on Requirement Resources in the REST API document which states 'There is no factory for requirement resources'.
  • img UPDATED 2009-10-1- updated as a result of introducing requirement creation
  • scbw: CLOSED 2009-10-14
• Although I understand why it is present (i.e. to illustrate extensibility), the inclusion of the Jazz calm namespace in the list of 'other namespaces' in the Requirement Resource Definition document seems out of place (it confused me when I first saw it).
• Various minor typos, formatting and grammatical problems which can be identified on request.
  • UPDATED 2009-10-1: please do provide.
  • CLOSED 2009-10-14: will do so separately

-- SimonWills - 07 Sep 2009