Notation

The following notation will be used in each section in order to indicate the model structure, including its cardinality, ordinality, and optionality.

[ Optional ]

An optional collection of elements or sequence of attributes.

{ Grouping }

A mandatory collection of elements. The braces are implied if square brackets have not been employed but they are sometimes necessary where a collection of elements can be repeated.

| Choice |

An exclusive choice of elements. For instance: { choice1 | choice2 | choice3 }.

|| Choice ||

An inclusive choice of elements. For instance: { choice1 || choice2 || choice3 }. In other words: one or more of the choices.

... Repeated

Ellipsis following an element or a collection of elements indicates that it can be repeated a further 0-or-more times. Hence, “[term]...” represents 0-to-many instances while “{term}...” represents 1-to-many instances.

SUBSTRUCTURE

Indicates a sub-structure defined elsewhere in the document, e.g. NARRATIVE_TEXT. Giving common element collections and common attribute sequences their own name allows the structure to be factorised to improve both readability and consistency.

Here are a few examples for illustration:

{ a b c }	Mandatory collection of items a, b, and c. Any order.
{ a b } [ c ]	Mandatory collection of items a and b, optionally followed by c
{ a \| b } [ c \| d ]	Mandatory choice of a or b, followed by optional choice of c or d
{ a \| b } ...	Repeated sequence of 1-or-more items, each of which is a or b
[ a \| b ] ...	Repeated sequence of 0-or-more items, each of which is a or b

Identities

Note that [a]... (mandatory 0-or-more sequence) and [a ...] (optional 1-or-more sequence) are therefore equivalent. Also, [a || b] includes all combinations (a, b, ab, and none), and so is equivalent to [a] [b].

Although this notation uses XML syntax to show element values and attributes, it is designed to show the entity relationships and can be converted directly to a traditional ER diagram if necessary. Hence, there is no specific ordering implied between consecutive elements (at the same hierarchical level) or attributes in the notation. However, the order of the actual elements in a STEMMA Document should be treated as meaningful and preserved during import/export. With attributes — which function to characterise an entity or element — there is no associated ordering that needs preservation.

The text in all the STEMMA documentation capitalises the names of STEMMA entities and elements to distinguish them from the common usage of those English terms, e.g. Person as distinct from person, or Place as distinct from place. It also hyphenates technical polynyms that may also be confused with words in common use, e.g. event-type, citation-element, person-property.

Some special element data and attribute value names are defined. These may be used as-is or used to qualify another data name by forming a suffix to it:

iso-date= subset of ISO 8601 Gregorian date standard (i.e. yyyy[-mm[-dd]]).

iso-datetime= full ISO 8601 Gregorian date and time, i.e. yyyy-mm-ddThh:mm:ssZ.

narrative-text= text incorporating semantic and descriptive mark-up (including nested <Text>), and <Ucf> elements.

[*-]orig-text= Original text, possibly with alternate meanings or spellings identified. Text incorporating descriptive mark-up, and optional <Alt>, <Ucf> elements.

std-date= STEMMA date referenced in specific calendar, analogous to iso-date. Calendar can be specified by optional prefix, as suggested under Dates and Calendars research notes, or implied by the syntactic context. Also accepts “?” as per value.

std-fulldate= full STEMMA date reference in specific calendar. That is, with a granularity of only one day. Also accepts “?” as per value.

ucf-text= text with possible uncertain characters. Text incorporating optional <Ucf> elements.

[*-]value= representation of a value of a particular data-type (e.g. in mark-up, or a property, or a date). The special value “?” explicitly indicates not known or not provided — obviously important for deaths.