Allowed at-type version differences in same pipeline

[marcverhagen]

Now a component looking for NamedEntities that is using MMIF 0.3.1 will look for http:/mmif.clams.ai/versions/0.3.1 in views and miss any entity that is of MMIF version 0.3.0.

[keighrim]

This directly relates to discussion in clamsproject/mmif#14 . But the original issue is somewhat outdated by now, and I think a good place to start to update the discussion is to define what breaking changes are, based on our experience from past year or so.

[marcverhagen]

Yes, it does relate, and I think it is a good idea to cast the discussion in terms of what breaking really means, at least for now. I see several levels of breakage associated with the major-minor-patch changes:

1. The JSON schema are different. This breaks the syntax and could, and probably even should, throw an error. We agreed that this could be the thing that gets us to bump up the major version once we finally hit version 1.0.0. A complication here is that some changes will invalidate things that used to be okay and others won't. For example, making a property optional won't break anything, making it required would, at least for all the cases where we do not have that property in the MMIF file.

2. We add, remove or change an annotation type (where changing means adding, removing or changing a property or metadata property). We had been thinking of these as changes to the minor version. Here we could glue together a chain with and EAST version that uses MMIF 1.2.0 and Tesseract that uses MMIF 1.3.0. This probably won't break the chain unless an app is set up to throw an error when required input isn't there (and I think the app should in that case set up to be really specific about what kind of input it misses and put that in the error message). Glueing together these components may break the intended result if there are enough changes in MMIF pertinent to the annotation types that EAST and Tesseract use. For example, Tesseract would return an empty result because it did not find and bounding boxes of the right version.

3. No breakage at all. Any pipeline runs exactly as it did before the MMIF change. When MMIF changes at this patch-level nothing else needs to change.

Loose thoughts:

• The hard thing is to decide what to do with the second case.
• App metadata never refer to the version of a required annotation type, which is as it should be, the question is whether the MMIF version used by the app not only determines what the app creates but also what it needs as input.
• I don't like at all the idea of all applications needing to be changed following a minor change in the specifications, even if those changes to not impact the app at all. This would be unmanageable.
• Maybe ClamsApp.annotate() in clams-python could throw an error when the app's major MMIF version conflicts with the major MMIF version in the input MMIF file.
• The clams-python package is set up to require a specific X.Y.Z version of the mmif-python package. I don't know what exactly the nature of this dependency is. Would it be feasible to use a range? At least for the patch-level and maybe also for the minor version.

Maybe this should be in clamsproject/mmif#14.

[keighrim]

For implementing this, I'd also like to propose we re-visit #23 (and possibly #64). See comment for more details.

[keighrim]

Here are places where the information / documentation on versioning is written outside of this repository. They also need to be updated when this issue is addressed.

• https://mmif.clams.ai/versioning/
• https://sdk.clams.ai/introduction.html#note-on-versions