[oslc-core] Guidelines for specifying future-proof resources/capabilities

[Dave]

re: Specification versioning

I'm still working representations today, but I've been thinking more
about the guidance that we should provide in Core spec to help
workgroups specify "future proof" resources.

The rule

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

The guidelines

For OSLC workgroups, these are some guidelines to help you live with
the above rule and specify OSLC resources that are as future-proof as
possible.

   1) 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.

    2) 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.
This will enable old clients to continue to work against old services
and new clients to work with your new capabilities.

   3a) When defining resources, you are not allowed to remove, change
the meaning or the value-type of any properties that you defined in
earlier versions of the specification. You can add new properties but
not change those that already exist.

   3b) 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.

ISSUE: we should pick either 3a or 3b. At this point, I think 3b seems
more reasonable and gives workgroups some more leeway in making
changes, but...

ISSUE: how can we enable 3b? Do we recommend that OSLC domains provide
different shapes for creation vs. query? Do we require that domains
specify two ""occurs" values for each property: oslc:creationOccurs
and oslc:queryOccurs? Does this overlap with the oslc:queryable value
that we discussed yesterday?

I'd like to write this up (and the rest of the changes in
http://open-services.net/bin/view/Main/OslcCoreMeetings04302010) this
week, so any feedback, comments, suggestions, etc. you might share are
all most welcome.

Thanks,
- Dave