OSLC CM Initial Specifications Architectural Direction

These are the architectural decisions that have been reached to solve a set of integration scenarios for a couple of CM products. This is intended to represent a direction for an initial OSLC CM specification and not to represent decisions for will stand the test of time and be held for next revisions and developments of the specifications. Additional architectural decisions and direction will be needed as additional scenarios are supported.

Architectural Decisions for OSLC CM 1.0

1. Default format for a collection of resources is ATOM syndication format (with content inline vs. reference) ( in spec)
   1. There is a need for a lighter-weight XML formats (ATOM-like, possibly RDF-ish)
      • This format will be used when there are collections within ATOM responses
      • ATOM responses will included by links to resource information, as well as inline resource properties.
      • Unresolved: ATOM is too heavy-weight, need to provide a light-weight alternative Owner AndreWeinand
   2. There is a need for JSON formats Owner AndreWeinand
2. A failure to create a resource can result in a 303 with redirect to Web UI. Owner SteveAbrams
3. A unattended creation is intended to be successful with a minimal set of properties. The service will try to accommodate with defaults, etc. Owner AndreWeinand (at least to propose minimal set of properties)
   • Unresolved: What are the minimal set of properties
4. Resource links are handled as a multi-valued property on a resource (in spec)
   • There are no spec'd requirements on whose responsibility storing cross repository links (uni-directional, bi-directional)
5. Services will be discoverable by traversing configuration collections until a service specification document is returned Owner SteveSpeicher, 71207
   • Unresolved: Specific contents on this document: has URIs for factories, query, version of OSLC supported, content-types supported?, ....
6. There will be a simple GET-based query syntax ( in spec )
7. There will be a way to request the amount of properties returned in response ( in spec)
8. Format requests will be based on Accept header ( in spec)
9. PUT on an existing resource URL will only modify the properties listed in the query parameter ?oscm.properties in the request that should be updated ( in spec)
10. Attempt to not require schema information by delegation to provider
    • Unresolved: Validate UI Delegation with Resource Picker (Owner AndreWeinand, 70501) and Resource Creation (Owner SteveSpeicher ,70382 )
11. Provide a miminal set of properties for resources based on Dublin Core ( in spec)
    1. Usage of dc:modifed for support in all resources, assisting in reporting tools, feed readers and other synchronization tools.
12. Resources will support at least application/xml and application/json as request and response formats (in spec)
    1. Presentations for resources can be requested using the HTTP Accept header with values such as text/html or application/xhtml+xml

Unresolved Items

These unresolved OSLC CM 1.0 items may either get resolved and be moved to the above list or addressed in a post-1.0 specification.

1. If a client had the resource URL #2(above), how could it get #5(above). In other words, if just a URL is sent to an application...can it perform a HEAD or OPTIONS or ??? on it to determine if the link is a OSLC based resource, if so then request the service doc to learn more.
   • JIA handles via a presentation service
2. Do we define our own MIME-like types for things like rich web hovers?
3. Query: how to specify which properties are queryable and which properties are selectable on a selecting a column for returned.

Items for consideration for post-1.0

Alignment of related standards:

• VTODO - need to consider aligning with task management tools?
• OpenSocial - need to evolve our delegated UIs to a widget spec when it is available?
• WSDL 2.0 - RESTful service description

Presentation requirements for resources
Some implementations have assumed different models for what HTML should be returned when requested: should it be contained in an IFrame with just dialog for change request viewing and editing? should it be its own page, with application banner and navigation bar?

Better handling of differing authenication models
We've run into some issues when clients don't always know when and how to handle form auth, like when using a batch-mode RESTful interface.

Reverse service discovery
Since resources are URL-addressable, they often get pasted into tools without going through service discovery.

A possible solution would be to support requesting the service discovery document an the change request resource URI:

• Performing a HEAD operation on the URI could return at least the CR and service document content types, then consumer would know that the URI is an OSLC one.
• Performing a GET operation on the URI with Accept header being x-oslc-cm-service-description+xml would return the service description document, not the chang request

or by embedding the service discovery doc URL in the change request resource definition

Named/Pre-defined Queries
Most, if not all, CM systems have the ability for a user to create a named query to be accessed later for execution. We could fairly rapidly provide at least read-only access to these and execution of queries.

Actions Items (if not listed above):

SteveSpeicher

1. (deferred)Work on seq diagram more detailed DefectScenario and with QM domain on alignment of work 71209

SteveAbrams

1. (done, indirectly) Provide guidance on usage of ETag, lift something from existing resource guidance docs

AndreWeinand

1. (done) elaborate the need for redundant storage of links
2. (done) elaborate the need for oslc.inline parameter no longer needed