• Issue 1 (CLOSED) we need a way of describing service documents. describing them as RDF models by way of RDF/XML is not really satisfactory. The current approach is to use a custom (non-RDF) syntax for the service documents and English text to describe the schema.
  • Action taken by Ian: the RM service description document differs slightly from the CM service document in order that it is properly well-formed RDF/XML.

• Issue 2 (DEFERRED) we require a resource representation for links; there are a number of alternatives that we need to discuss and perhaps seek guidance on from the OSLC Leadership. There is a number of concerns and options:
  • Consistency with OSLCCMV1
  • RESTfulness
  • Complexity for clients and for humans
  • <rdf:Description rdf:about="source><jazz:propertyName rdf:resource="target"/></rdf:Description>
  • Use of custom RDF vocabulary - <rdm:Link/>
  • Use of custom XML Action taken by Ian: Adopted explicit <rdm:Link/> representation in in RDF/XML.
  • 2009-10-1 Updated 1 October 09: There is some cross-OSLC work being done on link representation. We will try to track that work in the scope of RM v1.0.
  • 2009-12-09: Marked as DEFERRED to 2.0. The OSLC RM 1.0 spec. has been changed so that link resources are not part of the model; Scenarios do not require such link resources, nor do the scenarios require link properties.

-- IanGreen - 18 May 2009

• Issue 3 (DEFERRED) the question was raised, "can a PDF document be a requirement?" This raises key issues about the level of abstraction....this is worth a whole article to discuss: Requirement vs Representation.
  • 2009-10-1 Comment: yes, it can, but it must have a x-oslc-rdm-requirement+xml representation.
  • 2009-10-27: Marked as DEFERRED
• Issue 4 (CLOSED). Should collections be polymorphic?
  • Action taken by Ian: There are currently two collections, and they are typed - collections of links have a content-type and vocabulary which is different from collections of requirements. I think this is reasonable since the two collection types are actually rather different semantically.
• Issue 5 (CLOSED). What is the content model of a requirement? Should <rdm:Requirement/> define the content model of the properties for which it defines a meaning? For example, should rdm:primaryContent be XHTML when the primary content is presented inline?
  • Action taken by Ian: The dc:description of a requirement can be a separate resource, and HTTP content negotiation can be used when fetching that resource. This means that any defined MIME-type that is understood by both client and server could be used. However, the specification does not describe this interaction in any detail. Should V1.0 require that the supplied dc:description of a requirement is simply XHTML or perhaps plaintext?
  • Decision taken at meeting 28th August 2009: Keep to simplest case where the content is in-line; the need for "external" resources needs to be explored further. But we get 80% of the value from the simple in-line case. We will support plaintext (no markup) and xhtml content. The resource model will allow clients to detect which has been provided.
• Issue 6 (CLOSED). Volcabulary for "primary content" of a requirement? Does this warrant rdm:primaryContent? Spec. reads as dc:description at the moment.
  • 2009-10-1 Updated by img: No objections received to dc:title and dc:description, so closing.
• Issue 7 (DEFERRED). A RequirementCollection? and a LinkFactory? have overlapping behaviours. To what extent should they be harmonised? Should requirement collections support an inline representation for which the Requirements are inlined; conversely, is it correct that LinkFactories? always inline the links they contain? How to add and remove entries from a RequirementCollection? : GET/PUT of the collection will work but POST/DELETE might be more efficient when RequirementCollections? grow in size: in that case, what would be POSTed? (Note: there is no requirement for RequirementCollections? to be updated, but I'd like to anticipate such behaviour for subsequent revisions of this specification.)
  • 2009-10-1 Updated by img to deferred: leaving this open for the v1.0 specification, to be addressed in the future.
• Issue 8 (CLOSED). Should "RDF/XML" or "RDF/XML ABBREV", be the basis of the specification, or should RDF model be the basis? Mostly, this does not matter but the rules for abbreviated RDF/XML are such that DOM-based XML parsers may break when small changes are made to the underlying RDF graph instance. Related to this, is the variability we see in supporting JSON resource formats: should we uniformly adopt RDF/JSON? If we were to adopt RDF model, then RDF/XML, JSON etc would simply be examples - the underlying graph being the subject of the specification.
  • Agreed to find out is JSON is needed: Ian to talk to Steve about need for JSON. If don't need it, JSON representations will be excluded from 1.0.
  • 2009-09-03: Steve Speicher's view was that specificatioin need not mandate JSON representations, but that the specification should allow service providers to provide such content types. Ian updated the RmRestApiV1 to that effect.
  • 2009-10-1 Updated by img: closed since no objections raised to lack of JSON representations.
• Issue 9 (CLOSED). The V1.0 specification does not require support for all the HTTP verbs on all the resources the specification describes. For example, POST on a requirement has no meaningful role. Should such cases be explicitly excluded "Providers MUST return 405 (Method not allowed)" or should the spec. be more forgiving, for example, "is indeterminate; not defined by this specification". The value is leaving the spec. open is that we may find it allows greater latitude in the future when we come to extend beyond V1.0.
  • Decision taken at meeting 28th August 2009: Leave all behaviour that does not need to be specified explicitly indeterminate in the specification. Thus the specification may use words along the lines of "this specification does not specify the behaviour of POST on this resource".
• Issue 10 (CLOSED). What role should query play?
  • 2009-10-1 Updated img: no plans for query in v1.0
  • 2009-10-14 Marked as CLOSED.

-- SimonWills - 07 Sep 2009

• Comments on the draft v1.0 specifications from Integrate are here: IntegrateComments07Sep09

-- DominicTulley - 07 Sep 2009

• CLOSED: In the RestApi? specification, the error reporting rules state that any error report in the body of a failure response should be in the format for the requested media type. I think this is not quite what we want to say as it suggests describing the error report in the format of a requirement for instance. If the request is for some XML (whether x-oslc-...-requirement or x-oslc-...-link for instance) then the body should be in a common xml format. If the request is for some JSON then we should have a common JSON error response format et c.
  • Updated by img: Updated this section to reflect that all RDF/XML-based formats MUST have errors in RDF+XML. There are no non-RDF/XML formats, so this is all that is required for now.
• CLOSED: The RestApi? spec talks about the "about=..." part of the rdf being ignored on POSTs. Is it worth saying that on a POST the Name header is also ignored, since this is the more traditional way to declare where you would like something to be stored?
  • Updated by img: Strengthened the wording.
• CLOSED: The RestApi? spec describes the outcome of DELETEing a collection of requirements - that a subsequent GET will return 404 or 410. It says nothing about the contents of that collection and what a subsequent GET on one of those will do. I think we should say something, even if it is simply undefined.
  • Update by img: Agreed. Added that effect on collected requirements is undefined.
• CLOSED: Do we really mean SHOULD for the use of HTTPS in the RestApi? , or do we mean MAY?
  • Here i was following the example set by the CM v1.0 specification. We can discuss.
  • 2009-10-14: Inclined to agree that MAY is correct. Updated to MAY.
  • 2009-10-27: CLOSED
• CLOSED: In the RestApi? spec the requirement resource spec says that the only acceptable media type is application/x-oslc-rdm-requirement+xml and attempts to use others should be met with errors (406, 415). For other resources such as links and collections this is weakened to say that the x-oslc... media type must be supported but the use of others is admitted. Is this a deliberate special case (in which case why) or simply an inconsistency?
  • Updated by img: this was an error. My intention was that this specification only defines the behaviour on oslc media types. I've reworded, and emphasised the intended scope of the spec.
• CLOSED: The service description spec says that only GET is defined on a service description document and that the behaviour of the other verbs are not covered by this spec. In the spirit of the RestApi? spec, we should consider formally defining the behaviour of those verbs as "undefined" and recommending clients place no reliance on them.
  • Updated by img: yes, agreed. I've reworded to indicate that other verbs and media types are Undefined.
• CLOSED: The RequirementCollection? spec lists the possible rdf properties on the collection, then in the following text lists rm:archive as an optional property. Surely it should just be in the table with the others?
  • Updated by img: this was a typo. removed.
• CLOSED: Ths use of the rdf:type Bag in the RequirementCollection? seems weak. The rdf:type property is listed as optional but it seems like for this version of the spec all collections are expected to be Bags so perhaps the property should be mandatory and always say Bag for now. Also the text is unclear in this area, saying a collection should (in lower case) be treated with Set semantics.
  • Updated by img: I agreed. I've updated along these lines.
• CLOSED: The RequirementCollection? spec admits an rm:links property but does not talk about operations on that property. Maybe the place for that is in the API, but can a user POST to a collection's rm:links collection to add a link, for instance?
  • Updated by img: yes, this is what i intended. update the rest api to this effect.
• CLOSED: The LinkResourceDefinition? spec tells us that GET on a link factory will give us all the links associated with that factory (associated in some undescribed way). However, the API spec says that the behaviour of a GET on a global link factory is undefined.
  • I'm not sure i see this: have i already accounted for this comment?
  • The text is still there - I think it's a minor issue really.
    The RmLinkResourceDefinition page says:
    

    A link collection resource allows the creation of new link resources, as well as providing a means of enumerating those links associated with some resource.

    but the RmRestApiV1 page says:
    

    The provider MUST support application/x-oslc-rdm-link-collection+xml for all link collections other than the global link collection (rm:linkFactory). The behaviour of GET on the global link collection is undefined

    
    I think there's nothing broken, just a need to be as clear on one page as you are on the other.
  • 2009-10-1 Updated by img: I believe the spec. has been updated.
• DEFERRED: Is pagination required over RequirementCollection? /LinkCollection resources?
  • Action on Matt and Ian to investigate. (General feeling at meeting on 2009-10-05 was that yes, pagination required, but not in v1.0)
  • 2009-10-14 Ian wrote this on pagination of collections and the team need to discuss.
  • 2009-10-27: DEFERRED. This revision of the spec. will not suport pagination of resource representations.
• OPEN: How do we provide context to programmatic requirement creation? Is hierarchy of service documents satisfactory?
  • Action on Ian to get consensus from the group on approach.

TorgeKummerow - 15 Sep 2009

Requirements Management REST API r19 Link

Core resource summary

I still don´t quite get the reason why PUT and DELETE aren´t REQUIRED

img: it is more that i think we have something valuable without requiring that providers support such verbs.

Don´t we have a bootstrap problem if not? Where do the requirements come from?

img: requirement URIs come from the delegated web UI (or perhaps by some mechanism outwith this specification).

I know we discussed this at the last conference, so I won´t argue about it but I want to at least underline my position that this would be fundamental.

img: 2009-10-1 CLOSED the specification to support Requirement Factory resource (described in the service document) and a delegated UI to create requirements.

Factory Resources

Description says the factories support creation of links AND requirements, but in the table there is no word about requirement creation. Instead it is about selecting existing requirements.

img: CLOSED. There is no facility to create requirements.

img: 2009-10-1 CLOSED to specify requirement factory and delegated creation UI.

General Remarks

„Providers implementing this specification SHOULD refrain from using MIME types with a subtype having "x-oslc-" as a prefix.“

Maybe the server should reject all unknown mime-types starting with „x-oslc-“ with an appropriate error code to prevent accidental miss usage in case the specification isn't read carefully enough by the programmer of the client, who might be driven by staying conform with the naming already used which would be: starting with „x-oslc-“.

img: CLOSED. what we want to do is allow for compliant providers to be extended without changing the behaviour of any client which has followed the spec. and has not "consumed" any undefined behaviours. if we were to define the behaviour in the specification, clients could (deliberately or otherwise) come to rely on that defined behaviour. if and when the spec. is extended, providers will have a more difficult upgrade path to follow since some clients will break.

Compliance

Should 'OPTIONAL' sections return „405 Method not allowed“ if not implemented?

img: CLOSED: i'm not sure; i don't think this section should describe such details, but that the later more detailed sections should - have i missed something in one of those sections?

Requirement Resource

What is the behaviour of DELETE if the requirement is linked? Will the link be deleted? Or stay as an orphan or inconsistent link with only one side? Is it a client choice to delete adjacent links?

img: DEFERRED: to discuss. can i have a link without endpoints? A system cannot in general know of links that impinge upon its resources, and even if such links are known about, to delete them as side-effect in all cases is something we would not want to require in this specification. I propose we leave that matter outside the specification.

Torge: So we are handling it completely like HTML pages, where I have no Idea who is linking to me? And thus the data will include more and more dead links which will end nowhere with time passing by? Can´t we at least within our own scope try to keep the data intact?

2009-10-27: DEFERRED.

Create a Link

Why is there a requirement specific link factory supporting only link creation from that particular requirement, wouldn't it be more wise to have one single requirement factory, handling all link creations starting at a requirement?

img: DEFERRED. we can discuss what "wise" might mean. this resource model has some redundancy - there is more than one way to create a link. offering a requirement-specific link creation seems natural to me - it is not necessary to use the service document if the URI of a more narrowly scoped collection is handy. also, there is a need to be able to ask for the links on a requirement, so a collection is required for other reasons.

And what is with bi-directional links between a requirement and a non-requirement?

2009-10-27: DEFERRED

img: DEFERRED. I'm not sure i understand. I create a link between a requirement and something else. the spec. does not know/enforce/require bi-directionality. perhaps i'm misunderstanding your question. is there a scenario that we could focus on?

Torge: Sorry, maybe I am too influenced by my past projects. In all similar projects there were the possibility to also set undirected/bi-directional links.

img: UPDATED 2009-10-1; OK, this will be an interesting thing to consider in the future. I suggest we leave this unclosed and deal with it after v1.0.

2009-10-27: DEFERRED

Maybe one global link factory is enough after all.

img: UPDATED. it is complete in one sense, but see my comment above.

Requirements Management Service Description r17 Link

Sevice Discovery

If at step 3 no „Service Description Document“ has been returned, is it deemed also as „4. Configuration has completed“? Maybe by a default configuration? Doubtful! Its more likely that the configuration has failed. Which should be mentioned here then, I guess.

Service Description Document

The formation of the specification used in the „Service Provider Catalog“ is much clearer as the table in this section.

img: CLOSED. I don't understand this statement. I think you're suggesting that the format in the service descriptioin document is poor? I agree. Let's improve it.

Torge: Sorry I ment formatation

Link Resource Definition Link?

I think it would be good to define a catalog of standardised link types.

img: DEFERRED. we discussed on previous call that we would not do this for 1.0

Torge: Yes I know, but wanted to note it down for later use.

Img: 2009-10-1ok, will leave this OPEN to address in the future.

2009-10-27: Marking as DEFERRED

They should be navigable by categories and if necessary subcategories, as well as filterable by source/target type.

img: DEFERRED. yes, such topics will be part of any link typesystem.

However they should be as clearly distinctive as possible with none or only minor overlapping. If two types do overlap heavily in functionality one should be removed.

img: DEFERRED. in a nutshell, this was the main motivation for the decision to exclude all link types from the v1.0 specification - that we'd not discussed this matter in sufficient depth to be confident that we would get it right etc.

Reasoning: In my experience most people use what is already there, if it suites their needs, before adding new stuff. However, if the types overlap too much in their use, it is very likely, that different teams will use different types even if they follow the same purpose. By giving a useful set of clearly distinct types the likelihood of matching standards in two separate groups will increase drastically IMHO. However, ofcourse it should still be possible to add your own types and to support some kind of matching between two types, making them aliases from one another.

img: DEFERRED. Agreed.

2009-10-27: Marking as DEFERRED

ChrisMcGraw - 15 Sep 2009

Requirements Management REST API

• CLOSED: The 'after the fact' discovery of unsupported methods doesn't look right. Wouldn't a client want to know if it could delete a requirement before it committed to posting one? If the spec defines a method as something that 'MAY' be supported, I think it should also define how a client discovers the what methods are supported for a given implementation - before the methods are called? I'm thinking of something standard like the HTTP OPTIONS method.
  • Updated - yes, i agree, and like the use of OPTIONS - i've incorporated that into the spec.
  • ChrisMcGraw CLOSED
• CLOSED: Thereis a typo under the Factory Resources header : 'Factory resources allow the creation of link and requirement resources as weand..'. Should this be something like 'Factory resources allow the creation of link and requirement resources as we[ll as selection of those resources]'? The inclusion of the UI resource in the table don't make much sense otherwise.
  • updated by img: reworded
  • ChrisMcGraw CLOSED