Linked issue: Annotation subclassing prototypes

[clams-bot]

A dummy issue to link an old issue at clamsproject/mmif#23. This issue was automatically created during repository separation. For details on the separation, see clamsproject/mmif#112

[keighrim]

Now I think it's a good timing for revisit this issue as we have (or will have soon) some new development in versioning and version compatibility.

---

What I think is that we re-write AnnotationType class (currently just an enum that lists all CLAMC vocab types) into many custom python classes for each and every vocab types. Technically, it wouldn't be re-writing the AnnotationType code, but re-writing the code for auto-generation of vocabulary subpackge instead. Here's a more detailed proposal;

I want vocabulary package generation code to do the following:

1. download and read in the corresponding vocabulary.yaml file using the __specver__
2. for each vocab type defined in the yaml file, define a new classmethod in the AnnotationType based on the short name of the type that works as a factory method that returns a particular vocab typed-instance under current spec version.
3. AnnotationType has __repr__ or __str__ method that returns @type URI string, aliased to value method for backward compatibility with enum implementation
4. to construct such a URI string, the an instance of AnnotationType keeps things like baseuri, specver, and shortname at its instance variable
5. AnnotationType class implements __eq__ method that returns true if everything of two instances except for a certain level of version difference is identical

In summary, the usage of vocabulary would stay mostly the same, but we'll use some sort of beefed-up enum-like as the internal implementation of the classes in the package.

And then in other parts of the code base, wherever at_type as a string is referenced (as method parameter or variable), we need to change those references to use newly generated classes instead of plain strings (from enum.value).

[marcverhagen]

A few questions:

• How is this better than having an AnnotationType class that uses the vocabulary yaml file to determine its behavior?
• How do we deal with user types? This question is perhaps also relevant to the current type with its enumeration.

[keighrim]

• How is this better than having an AnnotationType class that uses the vocabulary yaml file to determine its behavior?

This new class (#170 ) only implements a non-trivial (compared to simple enum +str) representation of @type value that aims to solve the version comparison issue (#163). It still utilizes vocabulary.yaml file to auto generate python instances for all pre-defined vocabulary types. It doesn't try to implement behavior of those classes, if you meant python APIs for getting/setting properties and validation of those properties by behavior (Now I think #170 solves more of #64 than #23, and the branch name should have been 64-xxx).

• How do we deal with user types? This question is perhaps also relevant to the current type with its enumeration.

In the previous implementation, there were three base types (thingtype, annotationtype(⊳thingtype), documenttype(⊳thingtype)) (⊳ means superclass) and all CLAMS vocab types fell under annotationtype and documenttype based on their membership in the hierarchy. Non-CLAMS types (lapps, etc) should inherit from thingtype, but in most cases they just were floating around as plain str.

In the new implementation (#170), I added a middle person to implement patch-agnostic comparison of @type values for CLAMS vocab types, namely clamstype(⊳thingtype), and annotationtype(⊳clamstype), documenttype(⊳clamstype). User types still use thingtype as base as before, and if a user passes a plain string as a @type to a python MMIF object, internal implementation will force cast it to an instance of thingtype-family unlike before.

[keighrim]

As we prepare for v1.0.0 release, I wonder if our last conclusion from #163 will still be valid upon or after the release of 1.0.0, which will be our first bump in the "major" version number.

@marcverhagen I don't exactly remember our latest discussion (in the in-person meeting around last Nov) on this question, but one thing I remember is that clamsproject/clams-python#129 was an issue written from that discussion. Other things I remember for sure are;

• 1.0.0 will be almost "minor" update from what we have as 0.4.x in terms of features or specification changes.
• we agreed that all apps support (or are written for) 0.4.x should also support 1.0.0
• also agreed that MMIF files with clams.ai/.../0.4.x/AtType annotations should also be consumable at least for a while after the 1.0.0 release.

Given that, it seems that we need to make some changes in the base at_type implementation, in that

• minimally, hard-code compatibility between 0.4.x and 1.0.x
• more generally, in line with any changes in our conclusion regarding the "compatibility" (or equality) of annotation-type objects between different versions (long-discussed in Linked issue: meanings of digits in semantic version #14) .