[CAS Specification Subgroup] My comments on section 5.1

[Eric Nyberg <ehn@cs.cmu.edu>]

Folks,

Here are my general comments on Section 5.1. Looking forward to your 
feedback!

Best,

-ehn

1. Section 5.1.2 requires clarification. The second paragraph invokes 
Ecore. Then the third paragraph goes on to define features, types, etc - 
is this just a summary of the contents of Ecore or a specific 
interpretation of Ecore? The text should be clear on this point.

2. The first candidate compliance point in 5.1.2 has a potential 
ambiguity. In general well-formedness constraints can be expressed as 
preconditions, postconditions, and/or invariants. I expect that it's the 
goal of the framework that all objects in each CAS conform to the type 
system at all times (invariant). For components, this might be best 
phrased as both a precondition ("components can assume that the CASes 
they receive conform to the type system") and as a postcondition ("any 
object in the CAS which is created by or modified by the component must 
conform to the type system"). The current wording could be taken to mean 
that each component must check all the objects in the CAS; I don't think 
this was the authors' intent.

3. I think it would be clearer to use UML notation consistently. 
Currently Figure 2 switches to an ad-hoc notation to denote classes and 
instances, when a UML object diagram would work just as well.

4. The Apache UIMA Notes (end of 5.1.2 on page 22) indicates that the 
spec is evolving to a simpler design, and that the Apache UIMA 
implementation is catching up. However, I find the second sentence in 
the last paragraph a little confusing - is this implementation detail 
really relevant for the spec? If it's important for each implementation 
to follow the same pattern, then this needs to become part of the spec 
itself rather than a side note. The same comment applies to the Apache 
UIMA note box in 5.1.4.5, page 28.

5. I think that the sofa example in 5.1.3 could be clearer... even 
though I've written sofa aware code I had to follow the example very 
carefully to make sure I understood it. It might be better to have an 
example that uses the sofa in a more application-motivated way (like the 
multiple text translations example in the SDK document).

6. The degree of flexibility in how to do XML attribute serialization 
has a direct impact on how hard it is for implementations to comply 
(5.1.4.3, etc.). My reading of 5.1.4 is that there is more than one 
legally specified way to represent an XCAS? Shouldn't it be a design 
goal to have a single, unambiguous way to represent an XCAS?

7. I'm not sure of the proper role of XMI Extensions in the UIMA 
framework. Section 5.1.4.7 mentions that XMI lets you extend a type 
system with domain/application specific information. Are we going to 
indicate the kinds of metadata that an implementation should contemplate 
here?