QM Specification Issue Tracking

List of general comments or issues against the specification development for the Quality Management domain.

Spec comments being worked (Closure description included after each comment, with prefix CLOSED. If unresolved or spec needs to be updated, it will have a prefix of OPEN )

OSLC-QM 1.0 Draft spec comments:

QmResourceDefinitionsV1

1. CLOSED XMLRepresentation of the Test Plan/Case Resource - the "dc:title" representation says "...This is sometimes referred to as the headline or summary of the request". Shouldn't it say "... of the resource." Instead? Also, I have noticed the "rdf:about = xsd:anyURI". Is this the URI of the resource (test plan or test case)? (IngridJorgensen 12/10/2009)
   • Response changed "request" to "resource". Added explanation of rdf:about to the list of test plan and test case properties (PaulMcMahan)

QmQuerySyntaxV1

1. CLOSED Introduction - it is mentioned that "... we also introduce a limit modifier ...". I cannot find this modifier in the "BNF" session. It only mentions "modifiers ::= sort?" (IngridJorgensen 12/10/2009)
   • Response I propose dropping the QM Query Syntax specification in favor of the Oslc Query Syntax specification . It has the same issue so I logged a comment. (PaulMcMahan)
   • Update Discussed adoption of the common OSLC reporting spec in workgroup meeting. We decided to correct the QM spec and discuss adoption of the common spec with ArthurRyman (PaulMcMahan)

QmRestApiV1

1. CLOSED Terminology - should we introduce a "QM Resource" term and define it to mean a Test Plan Resource or Test Case Resource? As I see it Paul, you're using QM Resource throughout the spec in in places where either Test Plan Resource or Test Case Resource are appropriate (this is useful I think and basically is a step towards OSLC common services specs). Note that I think there is an issue carrying this terminology throughout - specifically to the Media Types section. (ScottBosworth)
   • Response added a definition of QM resource to the terminology section (PaulMcMahan)
2. CLOSED URL Parameters - should the oslc_qm.pageSize parameter that is discussed under Get a Collection of QM Resources be listed? (ScottBosworth)
   • Response added oslc_qm.pageSize paramter to table (PaulMcMahan)
3. CLOSED Media Types Used - A media type is defined for QM Resource. Shouldn't we instead be specifying media types for QM Test Plan and QM Test Case? This comment applies across the spec where the QM Resource media type is referred to. (ScottBosworth)
   • Response The purpose of the media type header is to allow the client to indicate the desired format for the response. All QM resources have the same basic format so having one media type for all the QM resources should be specific enough. The alternative would be to define a separate media type header for each type of resource. IMO defining additional media types would complicate the API without providing much benefit.
4. CLOSED Requesting Formats - should this section be updated to use the MAY, MUST,... notation for specifying how service providers are to deal with different mime-type situations? E.g. should "If the requested {mime-type} is unknown, a HTTP response code of 415 Unsupported Media Type will be returned." be changed to say "a HTTP response code of 415 Unsupported Media Type MUST be returned." (ScottBosworth)
   • Response Added more concise language in this area of the spec. (PaulMcMahan)
5. CLOSED Get a Collection of QM Resources - reponse section is a bit confusing. It indicates that there are 3 ways a provider may respond, but then the reponse code table does not seem to follow through on those 3. Why is the 406 code listed here? Is there a reason to call out this HTTP response code (I assume other error codes are also possible)? Also, the 200 response code applies for "all results" and "a page of results", shouldn't the table should mirror the descriptive language that precedes it? (ScottBosworth)
   • Response Removed the table which showed the response codes as it did not flow with the preceding text. Moved the details about response codes directly into the text. (PaulMcMahan)
6. CLOSED Get a Collection of QM Resources - should the sentence "The number of entries in the collection response are driven by HTTP query parameters oslc_qm.query." also reflect that the number of entries in the response can be driven by the oslc_qm.pageSize property? (ScottBosworth)
   • Response corrected the typo (PaulMcMahan)
7. CLOSED Pagination - why are we explicit about the next and previous uri elements from RFC5005, but silent on the first and last uri elements that are desribed in RFC5005? Are we simply saying that pagination MUST be supported as described in RFC5005? Or something different? What about Archived feeds? Are both Paged and Archived feeds to be supported? Are we saying that Paged feeds MUST be supported but Archived feeds MAY be? Are we implying anything about the entries in the QM resource collections (see discussion about paged and archived in RFC5005) if we say we are supporting Paged feeds but not Archived feeds? (ScottBosworth)
   • Response added next and previous uri elements as optional. Feed archiving is discussed in the RFC document that we use as a reference on feed paging but is not required or (as far as I can tell) relevant to the discussion on paging QM resources. I don't think we want to either require or disallow feed archiving. I struggled with coming up with the right words to say "ignore the section of that document that discusses feed archiving, unless you want to implement it..." and opted to remain silent since its possible QM service provider might want to use feed archiving in some way. (PaulMcMahan)
8. CLOSED Delegated Resource Actions - wording in this paragraph seems confusing. Perhaps the following is clearer? "Quality Management tools often have web-based UI's that allow users to create or locate QM Resources. These UI's can perform complex handling of rules associated with resource creation and can also handle search and query methods for locating the resources. The OSLC-QM specification includes services that allow client tools to utilize these QM tool capabilities within their own Web UIs using some simple standards-based methods for cross application interaction. This interaction is detailed in a separate document titled Delegated Resource Selection and Creation. OSLC-QM compliant service providers MUST support this delegated model." (ScottBosworth)
   • Response alternate text accepted. (PaulMcMahan)
9. CLOSED Delegated Resource Actions - DelegatedResourceSelectionandCreation? link is broken - has this document been created yet? (ScottBosworth)
   • Response fixed borken document link
10. CLOSED Update a resource - it seems that the description of the Status Code "415 Unsupported Media Type" is missing. I suppose it should contain the text "If the Content-type of the body of the request is not known to the service provider" like in the "Resource Creation" session. (IngridJorgensen 12/10/2009)
    • Response updated the text as suggested (PaulMcMahan)
11. CLOSED Managing multi-valued properties and resource links - This design adopts the design for multi-valued properties documented in the CM spec. I don't think this is a good design and we shouldn't propagate it. The OSLC estimation workgroup is doing this the "right" way, as shown in this example:

<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
   xmlns:dc="http://purl.org/dc/elements/1.1/"
   xmlns:ems="http://open-services.net/software-metrics/">
   <ems:Project
      rdf:about="http://braintwistors.example.com/ems/v1.0/Project/4201">
      <dc:title>Tsunami 1.0</dc:title>
      <dc:description>
         The goal of ... 
      </dc:description>
      ...
      <ems:hasEstimate
         rdf:resource="http://braintwistors.example.com/ems/v1.0/Estmate/4203" />
      <ems:hasEstimate
         rdf:resource="http://braintwistors.example.com/ems/v1.0/Estmate/4204" />
      ...
      <!-- other properties of this project resource have been omitted for brevity -->
   </ems:Project>
</rdf:RDF>

In other words, a multi-valued property is just what it says - a property with multiple values, as illustrated here by "ems:hasEstimate". You do not introduce a separate collection resource with separate link resources - that design is not in the spirit of REST, it's just an old-fashioned OO programming API exposed via http. (MartinNally 12/9/2009)

• • Response The approach of using multi-valued properties for resource linking has been dropped from the spec. The direct linking approach will be used instead.