Special OSLC Core WG meeting on Specification Versioning

Scott Boswoth, Nick Crossley, Steve Speicher, Dave Johnson met to discuss how specification versioning will work and specifically how old pre-core clients will work with Core implementaitons, how Core vN clients will transition to Core vN+1 and whether generic clients can be made to work without hardcoding domain specific information.

Issues to be resolved

Here are the key specification versioning issues that we would like to resolve in the current OSLC Core specification:

• We specify specification version numbers in a confusing number of places including namespace URIs, Core version header, Domain version headers and in Service provider resources.
• We specify a Core version header and recommend that domain specs specify version headers as well. This can lead to confusing rules about how to behave given different combinations of things.
• The first round of OSLC specs were 1.0 specification and the second round will all be 2.0 specs, but the will be based on OSLC Core 1.0 specification, this is confusing.

Use cases we must support

Here are the use cases that we must support in OSLC:

• Old pre-Core clients should continue to work
• Clients that target vN of an OSLC specification should work against vN+1
• Generic clients that know only of the Core should be possible

Solution for issues

We talked about a number of ways to resolve the issues we face while supporting our use cases. In the end here are the changes we decided were best for the Core spec:

• We will refer to the OSLC Core spec as version 2.0. This will remove the confusion about domain v2 specs vs. domain v1 specs vs. Core v1.
• Resources will be returned with one OSLC-Core-Version string equal to "2.0" which will remove confusion about multiple version headers
• If the OSLC-Core-Version=2.0 header is specified, services will return the Core v2 specified version of the resource. This will allow new clients to get the new specification version of things.
• If the header is not specified, then return only v1 representation. This will allow old v1 clients to continue to function even after Core v2 has been implemented.
• In the versioning section of the Core spec we will provide guidance to help workgroups to design new versions of their specs, e.g. creating a new v3 spec as a follow-on to a v2 spec. When defining a new version of a specification:
  • Required properties (exactly-one or one-or-many) SHOULD NOT be removed, renamed or assigned new meaning because clients expect to be in representations that they receive and will place them representations that they create.

That's the current plan. Please speak up on the mailing list if you have feedback, suggestions, etc.