Inheritance is a mechanism that allows an entity to share the definition of an abstract base entity. An abstract entity must define no embedded Keys (e.g. in embedded <Text> elements) and can only reference other abstract entities. There may be other restrictions imposed depending on the entity type. In STEMMA, inheritance occurs for Events, Citations and Resources. A lighter introduction may be found at: Genealogical Inheritance.
Inheritance should not be confused with parent entities. Some entities have parents that help construct bottom-up trees (e.g. Person/Animal lineage, Place/Group hierarchies, Event hierarchies, and Citation chains).
When an entity initially inherits the definition of a base entity, its explicit parts override any corresponding inherited parts. NB: Nothing is actually copied from base entity to the derived entity, meaning the result of the inheritance must not be persisted in any subsequent export operation; this overriding occurs in memory only.
Parameterisation is a mechanism where the Parameter values are applied to an entity in order to modify its context. This applies to both Citations and Resources. The Parameters may be inherited from a base entity, declared explicitly in the body of an entity, or applied to a link from one entity instance to another (see below). All of these schemes can be used together.
The set of valid Parameter names and types must be defined in an Abstract Citation or Resource, as appropriate. In the case of a Citation entity, the URI implies one higher level of inheritance from an external repository. If the URI is defined in such a repository then the initial Parameters names and types are retrieved from there. If both definitions are available then they must be identical. One Abstract entity inheriting from another can add default values to existing Parameters, or define new Parameters. For non-Abstract, or concrete, entities, only Parameter settings, rather than definitions, are allowed, and the names and types are validated against their original definitions. The Parameter order is unimportant.
During an entity link, the associated <ResourceLnk>/<ResourceRef> or <CitationLnk>/<CitationRef> elements may provide a partial set of explicit Parameter values. These merely override any equivalent Parameters in the target entity in order to create an unnamed transient entity. NB: it is an error if the Parameters in those links do not correspond to the declared Parameters in the target entity. In the Citation case, the transient entity may be given an explicit chain of parent entities, and this will override any specified in the Citation entities themselves.
An important point regarding the application of parameter substitution is that it always occurs after the inheritance process has completed. Hence, the following distinct stages may occur:
Consider the case of a short-hand source citation for a general census page of England & Wales for a particular year, e.g. [RG 13/3178/51/12]. While this particular form is not recommended, a purely catalogue-reference example makes an illustration easier to read.
<Citation Key=’cCensus1901’ Abstract=’1’>
<Title> 1901 Census of England and Wales </Title>
<DisplayFormat Mode=’RefNote’>
<Text Language=’eng’>
[<Subs><i>${Series}/${Piece}/${Folio}/${Page}</i></Subs>]
</Text>
</DisplayFormat>
<URI> http://www.nationalarchives.gov.uk/census </URI>
<Params>
<Param Name=’Series’>RG 13</Param>
<Param Name=’Piece’ Type=’Integer’/>
<Param Name=’Folio’ Type=’Integer’/>
<Param Name=’Page’ Type=’Integer’/>
</Params>
</Citation>
This abstract citation provides a default citation-title, a simple citation-template for reference-note citations, the applicable source-type URI (contrived for this example), and a list of required Parameters — one of which has a default value.
We could then create a derived Citation for a specific household as follows:
<Citation Key=’cCensus1901ManningGrove’>
<Title> 1901 Census for Manning Grove </Title>
<BaseCitationLnk Key=’cCensus1901’/>
<Params>
<Param Name=’Piece’>3178</Param>
<Param Name=’Folio’>51</Param>
<Param Name=’Page’>12</Param>
</Params>
</Citation>
The BaseCitationLnk causes all the data from cCensus1901 to be inherited. The title is then overridden with a more specific one. The values of the last three Parameters are also given explicit values. The first Parameter retains the default value declared in the base Citation.
Now consider an associated Source entity for the 1901 census of this particular English household. Its <Frame> element could refer directly to the derived Citation, created above, or create an unnamed transient equivalent directly from the base Citation.
<Source Key=’eCensus1901ManningGrove’>
<Frame>
<!-- Alternative 1 -->
<CitationLnk Key=’cCensus1901’>
<Param Name=’Piece’>3178</Param>
<Param Name=’Folio’>51</Param>
<Param Name=’Page’>12</Param>
</CitationLnk>
<!-- Alternative 2 -->
<CitationLnk Key=’cCensus1901ManningGrove’/>
</Frame>
</Source>
In alternative-1, we use the generic Citation for the 1901 census and simply pass explicit Parameters (ignoring the first which has a default value). In alternative-2, we reference a specific Citation for the corresponding household.
There are some subtle differences here: Alternative-1 only allows the creation of a modified transient entity through parameterisation, either from an Abstract or “concrete” (non-Abstract) entity. You cannot add an explicit title, or add narrative. Alternative-2 is the recommended approach in this situation because it provides a named Citation to which other data can be added. A typical example where alternative-1 might be used is for referencing discrete pages of a single book.
Note that during parameter substitution the search for a matching name will use the parent hierarchy if necessary. In the case of a Citation, this means the search will follow the Citation chain in order to locate an appropriate Parameter name.