Re: Questions Of Versioning in OASIS

Hi David,

On Tue, Apr 19, 2016 at 6:10 AM, david.snelling@uk.fujitsu.com <david.snelling@uk.fujitsu.com> wrote:

Are there any recommendations for version changes within our documents. We have some documents that will change slowly, like the interface specifications, but others like the model will change more regularly. There will also be backward compatible changes (additions to the model) and non-backward compatible changes (change in the structure of the exist model). Is there an OASIS resource addressing these issues or are we on our own with general industry best practice?

That is your call following industry best practices. We don't have any governing rules. In general, what other TCs do is use point versions for minor updates and whole number versions for major changes. Certainly if a revision contained non-backwards compatible changes, it warrants e.g. v1.0 to v2.0 change. I am sure that that TCs have also upped the version number if there are substantial changes to a spec.

Other related questions we have are:

Is there any way to manage the basic difference between the model and the interface specs.

I don't really get the question. However, check out the examples below to see if any of these are similar.

Is there an example TC where there are some long standing interface specs, but one of more data models evolve over time?

This sounds to me something like what XACML ( http://docs.oasis-open.org/xacml/ ) and SAML ( http://docs.oasis-open.org/security/saml/Post2.0/ ) have done. These are both core specifications and then numerous related profiles, bindings, etc. You'll also notice that the directories are quite busy. You could talk to some of the players at either of these TCs to see how they have tried to manage the challenge.

Since we've moved to the organizing scheme for docs.oasis-open.org, the organization of work products has become easier to follow. Here are some other TCs that might give you some ideas on how others have approached this:

- Emergency Management

TC: https://www.oasis-open.org/committees/emergency/

Publications: http://docs.oasis-open.org/emergency/

Primary spec is Common Alerting Protocol (CAP). In addition, a series of related specifications grouped under the common name of 'Emergency Data Exchange Language (EDXL)'. See for example Common Types at http://docs.oasis-open.org/emergency/edxl-ct/v1.0/edxl-ct-v1.0.html

- Open Building Information Exchange (oBIX) TC

TC: https://www.oasis-open.org/committees/obix/

Publications: http://docs.oasis-open.org/obix/

Primary spec is OBIX at http://docs.oasis-open.org/obix/obix/v1.1/obix-v1.1.html. It is version 1.1. Then a series of bindings at version 1.0 level.

- PKCS 11 TC

TC: https://www.oasis-open.org/committees/pkcs11/

Publications: http://docs.oasis-open.org/pkcs11/

This is really 4 related OASIS Standards building off the base specification.

- OASIS Key Management Interoperability Protocol (KMIP) TC

TC: https://www.oasis-open.org/committees/kmip/

Publications: http://docs.oasis-open.org/kmip/

This is a primary spec (http://docs.oasis-open.org/kmip/spec/v1.3/kmip-spec-v1.3.html) and a number of related profiles. If you drill into them or even just check out the Related work section of the cover pages, you'll see that they are have a variety of version numbers to juggle and keep in sync.

If any of these look relevant to you, I'll be happy to introduce you to the chairs for follow up discussion.

Does this give you what you need?

/chet

Any other advice you can point us at.

--

Take care:

    Dr. David Snelling < David . Snelling . UK . Fujitsu . com >

    Senior Research Fellow

    Research Transformation and Innovation

    Fujitsu Laboratories of Europe Ltd.

    +44-7590-293439 (Mobile)

/chet
----------------
Chet Ensign
Director of Standards Development and TC Administration
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

coel message