Annotation and annotation display XML reference

The XML format for defining annotations and their display properties in the task files (see "Creating a New Task") is described in this document. Use cases can be found here. Click here for a split-screen view.

There are two methods for defining annotations and their display elements. The legacy method consists of the <annotation_set_descriptor> element and its children, along with the <annotation_display> element and (most of) its children. The new method, more concise and differently organized, is represented by the <annotations> element. For a comparison of the two mechanisms, see the use cases here.

It's possible to combine the two methods. In that case, the processing order is first <annotation_set_descriptors>, then <annotations>, then <annotation_display>.

Element hierarchy

<annotation_set_descriptor>
<annotation>
<attribute>
<range>
<choice>
<label_restriction>
<attributes>
<annotation_display>
<label>
<gesture>
<attribute>
<choice>
<label_group>
<gesture>
<annotations>
         <annotation_set>
<span>
<effective_labels>
<label>
                    <d_gesture>
<display_group>
<int>
<choice>
<int_set>
<int_list>
<string>
<choice>
<string_set>
<string_list>
<float>
<float_set>
<float_list>
<boolean>
                <positive>
                <negative>
<filler>
<filler_type>
<filler_set>
<filler_list>
            <d_gesture>
<spanless>
<int>, <int_set>, <int_list>, <float>, <float_set>, <float_list>,
<effective_labels>, <string>, <string_set>, <string_list>,
<boolean>, <filler>, <filler_set>, <filler_list>, <d_gesture>
<display_group>
<span>, <spanless>, <display_group>

<annotation_set_descriptor>

The toplevel element. Each annotation set descriptor corresponds to a subset of the annotations used in your task.

For simple tasks, there's no reason to define more than one set of content annotations. If your task is more complex - e.g., if you have both mentions and relations between them, for instance - you may choose to have multiple content annotation sets; you can specify that particular steps in your workflow modify or add different sets, and you can do mixed-initiative annotation for each set separately, if you have different trainable engines for the different sets. You can even have sets which contain attributes of annotations which were introduced in a different set, so you can edit these attributes in their own step.

XML attributes

Children

<annotation> (of <annotation_set_descriptor>)

Each annotation type in the set descriptor is defined by one of these elements. Note that the attributes for the annotation are defined as sister elements, not children, to make it possible for attributes to be defined in separate sets from their annotations.

XML attributes

<attribute> (of <annotation_set_descriptor>)

Attributes are defined separately from the annotations that bear them. The reason for this is to enable annotation sets, and steps which edit them, which only add an attribute to an existing annotation (e.g., part-of-speech tagging implemented as adding a "POS" attribute to the "lex" tag).

The default value of every attribute is null unless otherwise specified.

XML attributes

Children

<range> (of <attribute>)

For "int" and "float" attributes, you can define a range for the possible attribute values. You can define both endpoints of the range, or only one.

For "int" attributes, <choice> and <range> cannot cooccur.

XML attributes

<choice>

For "string" and "int" attributes, you may provide a list of explicit choices. If the attribute has at least one <choice> child, the choices listed are the only permitted values. The <choice> element enclosed text is the choice itself.

You can further specify choices as "effective labels", which are notional labels which are actually implemented as a label + attribute/value pair, e.g., "PERSON" implemented as "ENAMEX" + "type" = "PER". You can refer to these effective labels in various places in the task and annotation set descriptor specifications, as marked.

If one <choice> element has an effective label, they all must; and no more than one attribute for a given annotation type may define effective labels. The effective label must be distinct from all other effective labels in the set, and all other annotation labels.

For "int" attributes, <choice> and <range> cannot cooccur.

XML attributes

<label_restriction> (of <attribute>)

For "annotation" attributes, you must define at least one label restriction. Every value of the attribute must satisfy at least one of the restrictions. The restrictions can be a simple label or effective label, or they can also bear attribute/value restrictions.

XML attributes

Children

<attributes> (of <label_restriction>)

Label restrictions may also bear attribute/value pairs which must be satisfied in order to satisfy the restriction.

XML attributes

<annotation_display>

This element defines all the display-related properties in the MAT UI of the elements defined in an <annotation_set_descriptor> element. Most of what you can do here is define the display-related properties of labels, although you can also define some of the properties of attributes, and also define groups for hierarchical annotation displays.

Note that the order in which the elements in <annotation_display> are defined is the order in which the CSS display rules are defined; so the styling of <label> and <label_group> elements takes precedence of the styling of previous <label> and <label_group> elements.

The <annotation_display> element and (most of) its children, along with the <annotation_set_descriptors> element and its children, constitute the legacy method for defining annotations and their display elements. For a more concise and differently organized mechanism, see the <annotations> element. For a comparison of the two mechanisms, see the use cases here. Note that the <gesture> element on spans is only definable in the legacy <annotation_display> subsystem.

It's possible to combine the two methods. In that case, the processing order is first, <annotation_set_descriptors>, then <annotations>, then <annotation_display>.

Children

<label> (of <annotation_display>)

This element defines the display-related properties of true or effective labels.

Attributes

Children

The syntax of the presented_name attribute

The presented_name attribute is a simple string, with format directive of the form $(...). The values within the parentheses can be any of the attributes of the label (in which case the format directive will be replaced by the attribute value), or one of the special values listed below. The format directive can also contain key-value pairs, as in $(val:a=b,c=d). We describe the possible key-value pairs below as well.

key	available for	possible value	interpretation
truncate	_text	integer	If specified, the UI will ensure that the spanned text is no longer than n characters long. This value cannot be less than 5. The UI will show the beginning and end of the text, and show the truncated medial text with ellipses (...).
truncate	_parent	integer	If specified, the UI will limit the number of parent annotations listed, and indicate the remainder of the list with ellipses (...).
showLabel	_parent, any annotation-valued attribute	"no"	By default, when the UI displays an annotation attribute value as part of the name of an annotation, it contains the label of the annotation value. If you don't want the label displayed, provide this key-value pair.
showIndices	_parent, any annotation-valued attribute	"yes"	By default, when the UI displays an annotation attribute value as part of the name of an annotation,it does not display its start and end indices. If you want these indices displayed, provide this key-value pair.
showFormattedName	_parent, any annotation-valued attribute	"yes"	By default, when the UI displays an annotation attribute value as part of the name of an annotation, it does not display the value's formatted name. If you want the formatted name displayed, provide this key-value pair.
showFeatures	_parent, any annotation-valued attribute	"yes"	By default, when the UI displays an annotation attribute value as part of the name of an annotation, it does not display the values attribute-value pairs. If you want these pairs displayed, provide this key-value pair.

So, for example, if you want the presented name of your annotation to contain the text truncated to 20 characters, your value for presented_name would be "$(_text:truncate=20)".

<gesture> (of <label>)

In some cases, you may want to customize the annotation menu actions for an existing annotation. These actions will appear in the annotation popup menu when you select an existing annotation, not when you create a new one. You'll need to be able to do some programming to implement the action. If this gesture is defined in the scope of a true label which corresponds to effective labels, the gesture will be made available to all the effective labels.

See also the for_label attribute of the <gesture> subelement of <annotation_display>.

Attributes

<attribute> (of <annotation_display>)

This element defines the display-related properties for specific annotation attributes.

Attributes

Children

<choice> (of <attribute>)

When you select an existing annotation in the UI, you have the option of modifying choice attributes of that annotation via the annotation popup menu. The purpose of the <choice> element in the annotation display is to specify a keyboard accelerator you can use to select a particular choice attribute. The value of the choice attribute is the text it delimits, and that text must match precisely the value defined in the corresponding <choice> element in the annotation set descriptor. If this task has a parent task, and an accelerator for this annotation, attribute and choice is defined, it will be inherited unless overridden locally.

Attributes

<label_group> (of <annotation_display>)

Under some circumstances, you might want to create cascaded annotation menus in the MAT UI, perhaps in order to group together similar annotations, or provide options for more or less general annotations, or to compress the screen real estate taken up by the annotation popup menu. You can use the <label_group> element to accomplish this.

Each label group has a name. This might correspond to a known true or effective label (in which case it refers to that annotation), or it might be a previously unknown name, in which case it serves merely as a group. The children of each label group can be actual annotation names, or other known label groups. The annotations the label group refers to must be content annotations. If the label group is not otherwise known, it has the option of declaring CSS styling for the menu entry.

Any known label referenced here must be styled. The whole point of <label_group> is to create cascades for annotation menus, and if the label isn't styled, it doesn't appear in the annotation menu at all. As a result, it's an error for a reference label of <label_group> not to be styled.

Attributes

<gesture> (of <annotation_display>)

This element defines arbitrary menu gestures for the annotation popup menu. Its functionality is similar to the custom_editor and url_link attributes of the <attribute> element. When for_label is not present, this gesture is a gesture on a swiped text span, and will only be available in the spanned annotation pane. When for_label is present, this gesture is applied to annotations and duplicates the functionality of the <gesture> subelement of the <label> element in <annotation_display>.

Attributes

<annotations> (of <task>)

The <annotations> element, introduced in MAT 3.1, provides a more concise and differently organized mechanism for defining annotations and their display elements, in comparison with the legacy <annotation_set_descriptors> element and its children, along with the <annotation_display> element and (most of) its children. For a comparison of the two mechanisms, see the use cases here.

It's possible to combine the two methods. In that case, the processing order is first, <annotation_set_descriptors>, then <annotations>, then <annotation_display>.

Attributes

Children

<annotation_set> (of <annotations>)

The <annotation_set> element, introduced in MAT 3.3, allows the user to define annotation sets before they're referenced. This has two uses:

• The user might want to declare a non-default category for the annotation set in a more explicit manner than using the of_category attribute the first time the annotation set is referenced.
• The user may want to control whether the annotation set is managed or not.

Attributes

Virtually all annotation sets are managed. The one circumstance in which you might want to define an unmanaged set is if you have an automated engine which adds tokens simultaneously with another type of annotation (e.g., sentences). In this case, you'd have to define the set which contains the sentence annotation as unmanaged, because the step you'll declare will add both annotation sets, and you can't define a step which adds both managed and unmanaged annotation sets simultaneously. Since tokens are unmanaged, and the engine adds them and sentences at the same time, sentences must also be unmanaged.

<span> (of <annotations>)

This element defines a spanned annotation type.

Attributes

Display attributes

All attributes related to the display of this annotation in the MAT UI begin with "d_".

Children

<effective_labels> (of <span>)

An <effective_labels> attribute is a special type of string attribute. String (and integer) attributes can have explicit lists of choices as possible values for the attribute. An "effective label" is a notional label which are actually implemented as a label + attribute/value pair, e.g., "PERSON" implemented as "ENAMEX" + "type" = "PER". You can refer to these effective labels in various places in the task and annotation set descriptor specifications, as marked. Because these string choices can be given notional names and their own display properties, we've chosen to break out these string attributes in their own definition.

Attributes

Children

<label> (of <effective_labels>)

Each <effective_labels> element can have multiple <label> children, each of which has a value and an optional label (which defaults to the value). The label attribute defines what the user sees; e.g., if an ENAMEX annotation type has a "type" <effective_labels> attribute which a <label> whose value is "PER" and whose label is "PERSON", an ENAMEX annotation with a "PER" value for the "type" attribute will see the label "PERSON" in the UI.

Attributes

Display attributes

Because these labels are essentially the same as true toplevel labels from the point of view of the UI, the display attributes here are identical to those for the <span> and <spanless> elements.

All attributes related to the display of this attribute in the MAT UI begin with "d_".

Children

<d_gesture> (of <label>)

This child of <label> is identical to the <gesture> element of the <label> element of the legacy <annotation_display> element.

<display_group> (of <effective_labels>)

This child of <effective_labels> defines a display group whose parent name is, by default, the name of the annotation which bears the <effective_labels> attribute, and whose children are the effective labels. See the definition of <display_group> below (note that unlike that definition, this one has no children; it modifies the behavior of its sister <label> elements). If you want a different name (and, optionally, style) for the parent of this group, specify the name and css attributes here.

Attributes

<int> (of <span>)

This element defines an integer-valued attribute.

Attributes

Display attributes

All attributes related to the display of this attribute in the MAT UI begin with "d_".

Children

<choice> (of <int>)

The <choice> element can be used to declare a possible value for this integer-valued attribute. It can cooccur with the choices attribute described above. One situation where you might want to use the element instead of the attribute is when you want to define a keyboard accelerator.

Attributes

<int_set> (of <span>)

Equivalent to specifying an <int> element with aggregation="set".

<int_list> (of <span>)

Equivalent to specifying an <int> element with aggregation="list".

<string> (of <span>)

Attributes

Display attributes

All attributes related to the display of this attribute in the MAT UI begin with "d_".

Children

<choice> (of <string>)

The <choice> element can be used to declare a possible value for this string-valued attribute. It can cooccur with the choices attribute described above. One situation where you might want to use the element instead of the attribute is when you want to define a keyboard accelerator; another might be where your possible value contains both commas and whitespace.

Attributes

<string_set> (of <span>)

Equivalent to specifying an <string> element with aggregation="set".

<string_list> (of <span>)

Equivalent to specifying an <string> element with aggregation="list".

<float> (of <span>)

Attributes

Display attributes

All attributes related to the display of this attribute in the MAT UI begin with "d_".

<float_set> (of <span>)

Equivalent to specifying an <float> element with aggregation="set".

<float_list> (of <span>)

Equivalent to specifying an <float> element with aggregation="list".

<boolean> (of <span>)

This element defines a boolean-valued attribute.

Attributes

Display attributes

All attributes related to the display of this attribute in the MAT UI begin with "d_".

Children

<positive> (of <boolean>)

This element allows the user to specify UI properties for the positive setting of the parent boolean attribute. This control is not available in the legacy annotation set description method.

Attributes

<negative> (of <boolean>)

This element allows the user to specify UI properties for the negative setting of the parent boolean attribute. This control is not available in the legacy annotation set description method.

Attributes

<filler> (of <span>)

This element defines an annotation-valued attribute. For each <filler> element, you must define at least one filler type. Every value of the attribute must satisfy at least one of the types. The types can be a simple label or effective label, or they can also bear attribute/value restrictions.

Attributes

Display attributes

All attributes related to the display of this attribute in the MAT UI begin with "d_".

Children

<filler_type> (of <filler>)

This element defines a filler type which the annotation filler can match. You can use this element in conjunction with the filler_types attribute above. One situation in which you might want to use this element is if you want to define further attribute/value pairs which the filler must match, or if the label contains whitespace and commas.

Attributes

<filler_set> (of <span>)

Equivalent to specifying an <filler> element with aggregation="set".

<filler_list> (of <span>)

Equivalent to specifying an <filler> element with aggregation="list".

<d_gesture> (of <span>)

Equivalent to the <d_gesture> element found in <effective_labels>, but for true labels rather than effective labels. See the <gesture> element of the <label> element of the legacy <annotation_display> element.

<spanless> (of <annotations>)

This element defines a spanless annotation type. The child elements which define the annotation attributes are identical to those for the <span> element.

Attributes

Display attributes

All attributes related to the display of this annotation in the MAT UI begin with "d_".

Children

<display_group> (of <annotations>)

Under some circumstances, you might want to create cascaded annotation menus in the MAT UI, perhaps in order to group together similar annotations, or provide options for more or less general annotations, or to compress the screen real estate taken up by the annotation popup menu. You can use the <display_group> element to accomplish this.

If the display group does not have a name, its first child must be either a <span> element or a <spanless> element, and that element will be chosen as the parent of the group. If the group does have a name, it must be otherwise unknown, and that name serves as the parent of the group. In this latter case, you can style the name via the d_css attribute.

Any <span> or <spanless> children must be styled. The whole point of <display_group> is to create cascades for annotation menus, and if the label isn't styled, it doesn't appear in the annotation menu at all. As a result, it's an error for a child of <display_group> not to be styled.

Attributes

Children