OSLC-CM Specification Issues and Comments

List of general comments or issues against the specification development for the Change 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 )

Submitting Comments

To make sure that comments and issues are appropriately raised, send them directly to oslc-cm@open-services.net detailing which specification, section and issue. If desired, you can also add it to the list below for tracking.

After OSLC-CM 1.0 specs were finalized:

• SteveSpeicher remove text from CmDelegatedResourceSelectionAndCreationV1, namely this sentence "Note: We provide helper classes that contain that code. bug 76689"
• PatrickStreule 1 OPEN Unnecessary (and problematic) quotes in sample in http://open-services.net/bin/view/Main/CmQuerySyntaxV1#Selecting_properties_and_inlinin
  

  ?oslc_cm.query=state="open"&oslc_cm.properties="dc:title,dc:owner{*}"

  
  should be
  

  ?oslc_cm.query=state="open"&oslc_cm.properties=dc:title,dc:owner{*}

• IanGreen namespace prefixes are misleading in selective properties. e.g., in
  

  ?oslc_cm.query=state="open"&oslc_cm.properties=dc:title,dc:owner{*}
  the interpretation of "dc" is ambiguous. i would suggest a fully-expanded form, but worry about long URIs. similar goes for JSON, though in that case the spec is explicit
  
  Proposal: Need to something like ?oslc_cm.namespace=dc==http://purl.org/dc/terms/,jfs=http://jazz.net/xmlns/foundation/1.0/
  

• MartinNally see message from 23-Nov
• RobertElves strong desire to have sample of query response with embedded ChangeRequest? in ATOM format
• Query Spec introduction discusses a "limit" parameter but not in spec. This "limit" capability is really defined in Cm REST API as the oslc_cm:pageSize parameter.
• Ferran Rodenas CM Service Description doc is not RDF/XML valid
• Handling of delegated web UIs: sample with frame and event source test assumes a spec requirement but there is no supporting spec see section

  e.source == frame.contentWindow

• Be more explict about what's allowed in the <content> of ATOM feeds

CLOSED

• SteveSpeicher
  1. CLOSED Inconsistency with http://open-services.net/bin/view/Main/CmRestApiV1?sortcol=table;up=#Managing_multi_valued_properties
     The sample in the end of the section conflicts with the statement: "Individual entries in the collection are not modeled as uniquely identifiable resources (referencable by a URI) "
     Suggested correction:
     Remove the last sample inline entry that reads:
     

     To inspect an individual link contents, we can modify the request to provide inline properties such as:

     GET /records/12234-123344/blockedBy?oslc_cm.properties=blockedBy{*}
     Accept: application/xml
     Content:
     <blockedBy oslc_cm:collref="/records/12234-123344/blockedBy">
      <blockedBy rdf:resource="/links/1255-235411">
      <dc:title>Bug 1234: Server DB issues</dc:title>
      <url>http://remotesystem/bugs/1234</url>
      </blockedBy>
      <blockedBy rdf:resource="/links/123455-2344">
      <dc:title>Defect 4: Not handling out of diskspace problems</dc:title>
      <url>/records/128312-12492</url>
      </blockedBy>
     </blockedBy>
     

     
     Fixed in version: http://open-services.net/bin/view/Main/CmRestApiV1?rev=65
     Per group decision: CmMeetings07222009
• ArthurRyman:
  • CLOSED 1. http://open-services.net/bin/view/Main/CmRestApiV1?sortcol=table;up=#Introduction
    
    ajpplication
    
    should be
    
    application
    
    Fixed in version: http://open-services.net/bin/view/Main/CmRestApiV1?rev=65
    Per group decision: CmMeetings07222009
    
    
    2.CLOSED http://open-services.net/bin/view/Main/CmRestApiV1?sortcol=table;up=#Selective_Properties
    
    word ::= /any sequence of letters and numbers, starting with a number/
    
    should be
    
    word ::= /any sequence of letters and numbers, starting with a letter/
    
    Fixed in version: http://open-services.net/bin/view/Main/CmRestApiV1?rev=65
    Per group decision: CmMeetings07222009

From OSLC-CM 1.0 spec finalization phase:

• PatrickStreule (RTC Work Items)
  1. Ensure concurrent modifications to resources are appropriately handled. Support ETag on GET, utilized on PUT and if does not match response with 412 precondition failed
     CLOSED WG agreed to add
• SamPadgett (ClearQuest? )
  1. Need for standard error response element for attended resource creation (redirect URL for web presentation)
     Proposed change is to add something generic, like: <oslc_cm:link rel="alternate" type="text/html" href="record/creationDialog"/>
     CLOSED Altered concept of "attended resource creation" to instead be "form factory". Updated CmRestApiV1, CmServiceDescriptionV1 and CmDelegatedResourceAndCreation?
     CLOSED WG agreed to add <link>
• SteveAbrams

  CmRestApiV1
  Under "media types" on http://open-services.net/bin/view/Main/CmRestApiV1
  there is a TODO for valid RDF/XML -- where are we on that?
  CLOSED validated sample and removed comment from spect
  do we not have a dfinition for application/x-oslc-cm-change-request+json? or is this stricly XML?
  CLOSED spec updated with definition
  application/xml and application/json are still mentioned as formats under "http://open-services.net/bin/view/Main/CmRestApiV1#Create_a_new_change_request" -- I think you mean application/x-oslc-cm-change-request+xml and application/x-oslc-cm-change-request+jsonl there, although if so, we do need the spec for the JSON format.
  CLOSED Spec updated. WG agreed this would be required for POST
  For attended resource ccreation, are we currently saying that you can either prpovide a 'ticket' or communicate back from the iFrame as in the picker case? If so, we're making our clients lives 2x as hard as they need to be, since they have to be prepared for either response.
  CLOSED Specs updated with "form factory" concepts. WG agreed to remove this
  Under "Get a change request" -- you do specify that the json format is allowed, but don't say what it is. Also -- are we requiring that requests text/html and application/xhtml+xml be satisfied? Are we providing a web UI in response to those requests?
  CLOSED Yes, we are redirect to our Web UI presentations in these cases
  "The formats returned MAY not represent the underlying service provider's data model." -- this actually doesn't make much sense to me; I'd strike it completely since we're not talking about underlying data models anywhere.
  CLOSED WG agreed to move this comment to an introductory section
  Under "Update a change request" - media types need to be updated to fully-qualified oslc media types. I don't think we'll accept plain application/xml or application/json here, do you?
  CLOSED WG agreed to update with more specific media type for PUT
  Under "Partial update of a change request" -- we should word this more clearly. http://foo.com/workitem/1234 is a different resource than http://foo.com/workitem/1234?propperties="headline" -- so this is not partial update of a change request: it's total update of a smaller resource. This may sound like a nit, but it's an important point (to me). Now that I think about it, we're surfacing the same incorrect mental model under both "Selected Properties" and "Response Properties" -- that should be phrased to reflect the fact that there are additional, logical resources that include only specific properties, with URLs that can be computed as described here.
  OPEN need someone to take a pass at better wording
  The "Selected Properties" discussion needs to be connected to the resources that support it in some way.
  OPEN
  On pagination: MUST be limited in size, or SHOULD be? I thought this was an advisory request...
  CLOSED change made
  Where are we on the discussion of what the media types are for inlined and subsetted resources?
  OPEN We have concluded that discussion with a result that we would not inline any resourse beyond the first level. If we do expand the first level, then only wildcard is supported. Action to make it clear that subsequent requests for inlined resources will use generic media type. For example, if requesting cr+xml and inlining a User resource, request its content with plain xml media types.
  
  OslcServiceProviderCatalogV1:
  "The media type of a Service Provider Catalog Document is REQUIRED to be..." should say "MUST be"
  OPEN According to RFC2119 MUST=REQUIRED, though we can reword to eliminate confusion
  This doesn't use the table to describe the required and optional attributes as our other ones do; I don't know if it's worth adding that table at this point but it is an inconsistency.
  OPEN Known, other things have taken priority and no one has updated
  CmServiceDescriptionV1
  says to 'rewrite with OslcServiceProviderCatalogV1" but this still needs doing.
  CLOSED a todo
  is this resource RDF/XML?
  CLOSED Yes, it validates with RDF/XML validators
  
  CmResourceDefinitionsV1
  Do we need to say that this resource accepts 'open content'? Or something to indicate that it MAY contain elemements not specified here, and indicate what the server should do when POSTs come in with additional content? Perhaps indicate in the "Introduction" here that the reason for this being a minimal resource.
  CLOSED spec updated that open conteWG agrees to update to make it clear that it supports open content

• SteveSpeicher
  1. Add text/xml support
     CLOSED updated spec CmRestApiV1
  2. Add details about inlining resources in ATOM responses
     CLOSED update spec
• ScottBosworth
  1. Need to update JSON and XML
     OPEN awaiting new samples
  2. Take pass over all introductory sections of specs to provide better overview and context.
     OPEN need contribution, some attempted like CmRestApiV1
• SamitMehta
  1. Page: CmRestApiV1?sortcol=table;up=#Selective_Properties
     <samit>
     Shouldn't
     word ::= /any sequence of letters and numbers, starting with a number/
     be
     word ::= /any sequence of letters and numbers, starting with a letter/
     </samit>
     CLOSED updated spec
  2. Page: CmRestApiV1?sortcol=table;table=up#Pagination
     Question about Pagination: When collection results are provided limited by the request parameter of oslc_cm:pagesize, will subsequent requests with "next" or "previous" be required to return data based on the original query?
     For example, one queries for all change requests and specifies a pagesize of 10 and the oslc_cm:totalCount returned is 100. Then someone submits a new change request. The URI for "next", returns another 10 records, but will the oslc_cm:totalCount be 100 or 101 in the next call.
     I would presume that it should return continue to return data based on original query, but to be sure I would suggest that the above should be clarified in the spec.
     OPEN clarify that server doesn't need to maintain state of the query
  3. Page: CmRestApiV1?sortcol=table;table=up;up=#Attended_Resource_Creation
     "inquiry" should be "inquire" in the sentence "... or a URL that can be used to inquiry about the status ...".
     CLOSED - removing attended resource creation
  4. Page: CmRestApiV1?sortcol=table;table=up;up=#Managing_change_request_links
     There are no specific standards described here for references, just examples. Wouldn't we want a standard on certain fixed references. It seems that the provider would define all the references via "custom" properties. Also the "links" themselves won't be a standard URL.
     OPEN
  5. Page: http://open-services.net/bin/view/Main/CmRestApiV1?sortcol=table;table=up;up=#Security_and_Authentication
     Shouldn't the "Security and Authentication" be a "MUST" rather than a "SHOULD" or at least "MUST" support one of those mechanisms?
     Also, is there any reason to include "Service consumers", since the rest of the document is really only talking about Service providers?
     CLOSED WG agreed that since these are HTTP-based methods and others are supported, SHOULD is the appropriate level of support
  6. Page: http://open-services.net/bin/view/Main/CmRestApiV1?sortcol=table;table=up;up=#Error_Status_Information
     typo "servier" to "service".
     CLOSED
• NiravSheth
  1. OSLC Query Syntax:The syntax should be like this oslc_cm.query=State="Open" instead of oslc_cm.query="State=Open"
     CLOSED agreed it should be corrected
     
  2. JSON Collections should include the oslc_cm:totalCount attribute to figure out how many total results can be reterived.
     CLOSED needs to be added
• Other comments received and handled in previous meetings: CmMeetings05052009 CmMeetings04292009