This page is for discussing schemes of versioning ITS artefacts.
Firstly, 'ITS' (Implementation Technology Specification, a term we re-used from HL7) indicates derivative (but generally hand-built) artefacts based on 'upstream' specifications or 'pure models'. We might reasonably say that UML or BMM are pure, lossless expressions of the specs. ITS artefacts are usually somewhat (or even very) lossy w.r.t. the upstream models/specs, e.g. they may only carry the data view.
Practically speaking, ITS artefacts are the concrete means of using or implementing openEHR in some particular kind of component. Someone who wants to build components using openEHR XML will need canonical XSDs, Schematron or some other kind of XML schemas. Someone who wants to do FHIR-ish kinds of things might want openEHR-flavoured FHIR resources.
The number of ITS artefacts (taking a set of linked files as a single artefact) is roughly No. Specification Components x No. extant releases x No. downstream technologies. Here,
When it comes to APIs, my original conception of any API such as REST, SOAP, or a native language API (i.e. Java, C#, ...) should also be seen as an ITS, based on a properly specified and abstractly (but formally) modelled API, expressed in say UML and/or IDL (or Ecore-ish form would also do). In other words, if we build a 'COMPOSITION' REST API with the logical function 'get composition by version' we imply that there is an underlying native service containing a function like get_composition_by_id (version: VERSION): COMPOSITION. In this approach, a SOAP, REST, Java, ... etc APIs should all do the same thing, just in their idiom.
Others here may see each kind of API as a primary artefact, that is fully self-defining semantically, and in some sense this is true right now, since we are building the REST APIs before having abstract APIs specified. I believe that the right approach would be to reverse engineer abstract APIs from concrete APIs, for various reasons - mainly, providing a gold standard of transactional semantics that need to be respected by all kinds of concrete APIs.
If you agree with this, then although we don't have an upstream API spec today, we should consider that REST APIs are still an ITS kind of artefact, and that we will build those abstract definitions later. If you don't agree, then you may argue that the REST APIs are not ITS artefacts at all.
Organise the ITS repo(s) in such a way that :
We had various conversations in the past about this, and the various proposals, in brief are:
This is one approach we discussed at last year's SEC meeting (wiki notes here), where each component (RM etc) has its own ITS repo, and successive releases (1.0.0, 1.0.1, 1.0.2, 1.0.3 etc) are on a single line of development and essentially replace each other.
pros:
cons:
This is the usual approach applied to primary artefacts, particularly software, that are continually maintained in multiple extant versions. Concretely here it would involve a repo per upstream component (RM, AM, SM, etc) and the use of formal branches inside each repo. Pablo also provided a diag here.
Repos:
pros:
cons:
The is the approach some of us I believe arrived at in later conversations last year. It is a pragmatic approach, and results in a repo that uses a directory structure based on upstream release ids as the structure. One such structure is:
Other structures are possible, e.g. factored by ITS technology rather than upstream component:
The particular structure probably doesn't matter that much, since either way, it's an everything-at-once approach.
pros:
cons:
TBD
