OSLC CM Spec V2 Issues

The new V2 issues page HAS MOVED

This section captures the issues raised via review comments on:

• CmSpecificationV2 - the OSLC-CM V2.0 Specification

Issues are organized via the spec outline.

Note: dates below use US format (mm/dd/yyyy)

Here's what the states mean:

• OPEN - indicates that we have no response for the issue yet
• RESOLVED - indicates that we have a response that we believe resolves the issue
  • RESOLVED - indicates it is resolved as by above definition and edits in the draft specification have been made.
• CLOSED - issue has been resolved and the resolution has been reviewed by the workgroup
• DEFERRED - indicates that issue will be addressed in guidance after the specification converges
• TABLED - indicates that issue will be reconsidered at some later but unspecified date

After Finalization of 2.0

1. CLOSED The following states oslc:domain is part of oslc:ServiceProvider but really should say oslc:Service: "OSLC CM service providers MUST supply a value of http://open-services.net/ns/cm# for the property oslc:domain on either oslc:ServiceProvider or oslc:ServiceProviderCatalog resources. " (IanGreen, 12/03/2010)
   • Response Agree, need to update (simply remove the "Provider" from oslc:ServiceProvider.
     Fixed in revision 92 (SteveSpeicher 01/04/2011)
2. CLOSED MOVED to OslcCoreV2Issues oslc:discussion is listed as a common property but it is not listed as such in OSLCCoreSpecAppendixA Also suggest a better name like oslc:discussedBy (WikiName? , 01/07/2011)
   • Response Possible ways to handle: move to oslc_cm namespace or update common properties table. (SteveSpeicher 1/21/2011)
3. CLOSED MOVED to OslcCoreV2Issues oslc:discussion is also listed as a property of oslc:Comment in OSLCCoreSpecAppendixA though with a different meaning (WikiName? , 01/07/2011)
   • Response Possible ways to handle: remove oslc:discussion from oslc:Comment or rename to something like oslc:partOfDiscussion. (SteveSpeicher 1/21/2011)
4. CLOSED MOVED to OslcCoreV2Issues How to create oslc:Comment resources? Appears to be no guidance, perhaps a Core issue? (WikiName? , 01/07/2011)
   • Response Possible ways to handle: add informative section saying to use creation factories or simply use resource update, adding a new comment entry. There once was a statement about POSTing to the Discussion URL to create comments, not sure why it was removed.. (SteveSpeicher 1/21/2011)
5. DEFERRED In the OSLC-CM v2 spec, we say that OSLC CM service providers must support Query Capabilities and Creation Factories I think we may be too vague here because we don't say what "support" means. (DaveJohnson, 01/11/2011)
   • Response Propose we mark this deferred (SteveSpeicher mm/dd/2010)
   • Response Agreed to defer (SteveSpeicher 02/21/2013)
6. DEFERRED oslc_cm:tracksChangeSet description uses term "target" which is not typical. Also, need to have a better description to allows for a wider set of possible resource types (WikiName? 02/09/2011)
   • Response Proposed response: change "target" to be more inline with RDF terms "object". We need core term support for this? The description should include or forward reference the "tracks" description below the table. (SteveSpeicher mm/dd/2010)
   • Response Agreed to defer (SteveSpeicher 02/21/2013)
7. CLOSED Need to determine how to reference or recommend new addition to Core of Dialog resize (SteveSpeicher, 03/14/2011)
   • Response Propose that we don't make a change and 'defer' this (SteveSpeicher mm/dd/2011)
   • Response Agreed nothing needed to do (SteveSpeicher 02/21/2013)
8. DEFERRED Consider removal of partial update as the guidance never advanced to a finalized status. (SteveSpeicher, 04/11/2011)
   • Response Propose that we remove a this section on PATCH-based partial update (SteveSpeicher mm/dd/2011)
   • Response Agreed to defer, not fix in 2.0 (SteveSpeicher 02/21/2013)
9. CLOSED "Resource Shapes for Query Capability" link is broken in this section on the CM spec. http://open-services.net/bin/view/Main/CmSpecificationV2#Query_Capabilities. (SamPadgett, 05/05/2011)
   • Response Fix the link (SteveSpeicher mm/dd/2011)
   • Response Remove the links in http://open-services.net/bin/view/Main/CmSpecificationV2?rev=98 (SteveSpeicher 02/21/2013)
10. CLOSED The namespace URIs resolve to vocabularies, should make them more obvious in the spec. (SteveSpeicher, 05/05/2011)
    • Response Consider making the URI linkable. (SteveSpeicher mm/dd/2011)
    • Response made namespace URI linked (SteveSpeicher 02/21/2013)
11. CLOSED dc:type and Dublin Core's guidance wrt rdf:type. (SamPadgett, 11/15/2011)
    • Response Consider updating usage of dc:type to match Dublin Core's recommendation. (SteveSpeicher mm/dd/2011)
    • Response Remove property and defer further to 3.0 (SteveSpeicher 02/21/2013)
    • Completed Moved dc:type to deprecated section (SteveSpeicher 10/03/1013)
12. DEFERRED Current language around state predicates unclear. The ChangeRequest resource lists that they are optional, but the State Predicates section says they MUST be queryable (seeming to imply that they're required). (SamPadgett, 03/26/2012)
    • Response Defer to 3.0 as the state predicates are being reworked (SamPadgett 02/21/2013)
13. CLOSED Proposal and problem Suggested improvements to "link label" specification writeup. (Steve Speicher, 02/02/2012)
    • Response Made change in revision 97 as preposed in above (SteveSpeicher 04/10/2011)

During Convergence and Finalization of 2.0

1. CLOSED Should we specify properties that don't have value-types, example: priority, severity (ScottBosworth begin_of_the_skype_highlighting end_of_the_skype_highlighting, 05/12/2010)
   • Response resolved to exclude these properteis (SteveSpeicher 05/19/2010)
2. DEFERRED Need specification for state transitions (SteveSpeicher, 05/12/2010)
   • Response Proposed has been drafted and put in an experimental status to get more review, implementation feedback needed. (SteveSpeicher 05/19/2010)
3. CLOSED Need multi-valued property partial update (SteveSpeicher, 05/12/2010)
   • Response Adopt multi-valued property partial update from guidance (SteveSpeicher 05/12/2010)
4. CLOSED Moving resource definition oslc_cm:Discussion to core (SteveSpeicher, 05/18/2010)
   • Response Done: see OSLCCoreSpecAppendixADRAFT#Common_Resource_definitions (SteveSpeicher 05/21/2010)
5. CLOSED Need to identify dialogs for relationship properties (SteveSpeicher, 05/19/2010)
   • Response Propose to add property name or resource type to Dialog definition, added oslc:usage property (SteveSpeicher 07/07/2010)
6. CLOSED Change of state predicate of oslc:open to be oslc:closed, as it is more straightforward (SteveSpeicher, 05/23/2010)
   • Response Proposal to change to oslc:closed (SteveSpeicher 05/25/2010)
7. CLOSED Naming of some of the relationship properties, those that start with manages* would be better named tracks* (SteveSpeicher, 05/23/2010)
   • Response Proposal to adopt these changes (SteveSpeicher 05/25/2010)
8. DEFERRED Proposal to change ProgressTracking? properties to be workCompleted (double), workTotal (double), workUnit (localized string), workProjectionValue (double, Projection value is negative for work behind, or positive for work ahead, 0 for 'on time') (MartinAesclimann? , 05/25/2010)
   • Response Plan to get more implementation feedback and adding to experimental page (SteveSpeicher 06/22/2010)
9. CLOSED Specification is missing a writeup that helps clarify the limitations of change request creation based on shape (SteveSpeicher, 05/25/2010)
   • Response Recommend adding a section that discusses resource creation and client expectations (SteveSpeicher 05/25/2010)
10. CLOSED State predicate oslc_cm:validated, what is it used for? Is it supposed to be oslc_cm:verified? (AndreWeinand, 05/26/2010)
    • Response Recommend changing to oslc_cm:verified (SteveSpeicher 05/26/2010)
11. CLOSED Relationship properties don't appear to align with core guidance and some other specs, how link value URIs imply type of resource (ScottBosworth, 05/26/2010)
    • Response Brought spec current with link guidance (SteveSpeicher 06/22/2010)
12. CLOSED suggestion to add in the introduction some mention that these specs regard both data types and protocol elements regarding the service interfaces behaviours (i.e. OSLC-CM is not a data format nor a simple API, but a full set of a quit extensive protocol) (OlivierBerger, 05/27/2010)
    • Response Agree to update intro (SteveSpeicher 06/02/2010)
13. CLOSED add in terminology something about "Resource" mentioning somehow the RDF / SemWeb? context (hence URIs, resource links, etc.) (OlivierBerger, 05/27/2010)
    • Response This is done in the Core Spec (SteveSpeicher 06/02/2010)
14. CLOSED Base requirements / Compliance : which OSLC-Core version explicitely ? (1.0 ?) must OSLC-CM V2 be compliant with ? (I assume not any later version without OSLC-CM version increment ? (OlivierBerger, 05/27/2010)
    • Response Will attempt to reword this section, making requirements more clear (SteveSpeicher 06/02/2010)
15. CLOSED Resource formats / UIs : mentioning (X)HTML explicitely for UIs (since REST HTTP-based protocol, that would make sense/ be implicit ?) ? (OlivierBerger, 05/27/2010)
    • Response Agree we should add this.(SteveSpeicher 06/02/2010)
16. CLOSED Authentication, Error response, Pagination, etc. up to CM Resource Definition may not be placed early in the docs, as not so much important, and the impatient reader may prefer to learn... (OlivierBerger, 05/27/2010)
    • Response attempted to do this and agree these sections should be first. (SteveSpeicher 06/02/2010)
17. CLOSED State Predicates : definition of what a predicate is should go first (or in terminology at beginning ?) : on the 3 paragraphs, the last one should be first IMHO : the rules first, and the rationale / use case later.(OlivierBerger, 05/27/2010)
    • Response Agree to improve these sections (SteveSpeicher 06/02/2010)
18. CLOSED dc:creator : this has been discussed several times but the end result / rationale is not clear (OlivierBerger, 05/27/2010)
    • Response Creator is the person (or person who owns an agent id) that is responsible for the resource to be created (SteveSpeicher 06/02/2010)
19. CLOSED rdf:type : should it be constant and set to http://open-services.net/xmlns/cm/2.0#ChangeRequest ? (OlivierBerger, 05/27/2010)
    • Response should be constant and multiple rdf:types can be used to indicate a subclass of. (SteveSpeicher 06/02/2010)
20. CLOSED oslc:serviceProvider : shouldn't it be more "meaningful" if named like : changeManagementService, even if the target resource is a oslc:Serviceprovider ? (OlivierBerger, 05/27/2010)
    • Response oslc:serviceProvider is common property and makes it easy for clients to just ask any OSLC resource for its service provider definition. Agree that it should be zero-to-one (SteveSpeicher 06/02/2010)
21. CLOSED The naming convention used for oslc:testedByTestCase, oslc:affectsTestExecutionRecord, and oslc:blocksTestExecutionRecord relationship properties includes the target resource type. Their inverse relationships are currently listed as oslc:tests, oslc:affectedBy, and oslc:blockedBy. Following the naming convention they should instead be oslc:testsChangeRequest, oslc:affectedByChangeRequest, and oslc:blockedByChangeRequest. (PaulMcMahan, 06/7/2010)
    • Response We are no longer defining the inverse links in CM, QM should define its relationships (SteveSpeicher 06/22/2010)
22. CLOSED The QM work group is defining two resources for test execution - TestExecutionRecord and TestExecutionResult. The change request relationship properties listed in the CM spec currently include oslc:affectsTestExecutionRecord and oslc:blocksTestExecutionRecord which both imply the same type of target resource (TestExecutionRecord). I would suggest instead oslc:affectsTestExecution*Result* and oslc:blocksTestExecutionRecord. The corresponding inverse links in the QM spec are currently defined this way. (PaulMcMahan, 06/7/2010)
    • Response We have eliminated inverse links from CM spec, have updated r37 to include new list (SteveSpeicher 06/22/2010)
23. CLOSED See previous issue posted re: TestExecutionRecord and TestExecutionResult. I suggest an additional relationship property of oslc:relatedTestExecutionResult for Change Requests (PaulMcMahan, 06/7/2010)
    • Response Have added oslc:tracksTestExecutionRecord (SteveSpeicher 06/22/2010)
24. CLOSED Some properties are missing read-only attribute, like dc:modified (PaulMcMahan, 06/7/2010)
    • Response Propose to review and update those specific properties (SteveSpeicher 06/22/2010)
25. CLOSED Seems undesirable to require OSLC-Core-Version as it will require every version going forward to have it. Would be better if there was a 1.0 requirement or way that it would be clear (SteveSpeicher for JDR, 06/15/2010)
    • Response No other workable alternative could be reached, going forward with current model (SteveSpeicher 7/01/2010)
26. CLOSED dc:identifier : the rationale of having it in addition to the resource URI may be necessary, ... (OlivierBerger, 05/27/2010)
    • Response Will provide example to illustration dc:identifier usage (SteveSpeicher 06/02/2010)
27. CLOSED dc:type : ain't it a core property (since "dc", would look like") ?... (OlivierBerger, 05/27/2010)
    • Response Will provide example to illustration dc:identifier usage (SteveSpeicher 06/02/2010)
28. CLOSED oslc_cm:status : maybe should refer to the predicates ? ... (OlivierBerger, 05/27/2010)
    • Response will need to clarify the relationship between the two (SteveSpeicher 06/02/2010)
29. CLOSED State predicate properties : that is far from clear and needs examples. May a basic workflow diagram / matrix help here, since some predicates values seem mutually exclusive ? ... (OlivierBerger, 05/27/2010)
    • Response agree, need to provide more claification (SteveSpeicher 06/02/2010)
30. CLOSED Relationship properties : the specs should convey non-ambiguous semantics (OlivierBerger, 05/27/2010)
    • Response Aligned with core guidance and refined naming. TODO: clearly define resources used (SteveSpeicher 06/22/2010)
31. CLOSED Relationship descriptions would benefit from some OWL like domain + range resource types (OlivierBerger, 05/27/2010)
    • Response agree, incorporate additional relationship guidance from core (SteveSpeicher 06/02/2010)
32. CLOSED Version Compatibility with 1.0 Specifications / Media Types : what's the difference (not) with 1.0, exactly here ? (OlivierBerger, 05/27/2010)
    • Response action to update spec (SteveSpeicher 06/02/2010)
33. CLOSED Partial Update is currently a MUST requirement but recent spec has been published, concerns on cost/complexity as a MUST (SteveSpeicher, 07/07/2010)
    • Response Propose to lower the requirement to a SHOULD. (SteveSpeicher 07/13/2010)
34. CLOSED How to discover if service provider supports partial update (SteveSpeicher, 07/13/2010)
    • Response Those that don't support it can respond with 501 (not implemented). Concerns over whether clients will support patch if not all service providers will implement. This can be done using OPTIONS and Allow header on response to indicate which HTTP Verbs are supported (SteveSpeicher 07/21/2010)
35. CLOSED Need a way to prime a link label (PatrickStreule, 08/18/2010)
    • Response Added reified statements to links in spec (SteveSpeicher 09/01/2010)

Template

1. OPEN Sample/template issue (copy and paste) (WikiName? , mm/dd/2011)
   • Response Need response (SteveSpeicher mm/dd/2011)