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. See below.

Guidance for specifying future proofed resources

We introduced a version number header in the OSLC Core spec to allow us to differentiate between old pre-Core implementations and new Core-based ones. We hope that this will be the only version header that clients will need to use and as domain specs progress from v2 to v3 they will continue to be based on OSLC Core v2 resource definitions, shapes, etc.

The rule

• A new version of an OSLC specification is not allowed to introduce changes that will break old clients.

The guidelines

• Think you need a property but cannot agree on the value-type? This is a strong indication that you should not attempt to standardize on the property. Once decide on a value-type you are stuck with it forever. Wait until you have the scenarios or implementation experience needed to agree upon a value-type.

• When defining resources, consider which ones are required to provided by clients at creation or update time vs. those which are required to be in representations returned by the server. When creating a new version of a specification: it's OK to relax restrictions on clients but it is not OK to add new required properties because that will break old clients.
• When introducing a new capability, e.g. a creation factory, query capability or delegated UI dialog; one that works differently than those specified in the Core spec or older versions of your own spec, you should create a new resource type to represent the service. Old clients will continue to use old services and new clients can use your new capabilities.

Feedback

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