A STEMMA Resource represents any digital or physical artefact in your collection. The term is more often used in the context of electronic documents, pictures, scans, and recordings. However, in STEMMA it may also be a physical object, or artefact (i.e. an object of human creation), such as actual letters, original documents, medals, portraits, original photographs, personal possessions, and family heirlooms.
<Resource Key=’key’ [Abstract=’boolean’]>
[ <Title> resource-title </Title> ]
[ <URL [ContentType=’content-type’]> url </URL> ]
[ <Type [Artefact=’boolean’]> resource-type </Type> ]
[ <DataControl>
[ <Sensitivity> level </Sensitivity> ]
[ <Copyright> copyright-notice </Copyright> ]
[ <Permission> permission-notice </Permission> ] ...
[ <Prohibition> prohibition-notice </Prohibition> ] ...
[ <Attribution> prohibition-notice </Attribution> ] ...
[ TEXT_SEG ] ...
</DataControl> ]
[ <Params>
{ PARAM_DEF ... } | { PARAM_VALUE ... }
</Params> ]
[ <BaseResourceLnk Key=’key’>
[ TEXT_SEG ] ...
</BaseResourceLnk> ]
[ TEXT_SEG ] ...
</Resource>
Digital resources are located by a URL (Uniform Resource Locator). The 'scheme' prefix of the URL allows it to be applied to different file stores, e.g. file:// for local files[1] and http:// for the Internet/Intranet ones accessed via the HTTP protocol. If the digital data-type cannot be determined by the file type (e.g. by its file extension) then the ContentType attribute must be employed to specify a corresponding Internet Media Type, e.g. ‘text/plain’, ‘image/jpeg’. A URL is not required for wholly physical artefacts, and is optional for Abstract Resource entities.
Irrespective of whether the Resource is digital, non-digital, or both, the nature of the resource is described by the <Type> element. This includes: Award, Clothing, Document, Furniture, Jewellery, Letter, Map, Music, Painting, Photograph, Recording, and Video. See Extended Vocabularies for an example of defining custom resource-types.
Non-digital resources are indicated by the presence of the Artefact attribute. A value of ‘1’ (true) indicates you have a non-digital resource, such as an original letter, portrait, or item of clothing. The default is ‘0’ (false). If a URL is also specified then it indicates that a digitised copy is also held. This will usually be a digital image but it could also be a digital sound recording or video. Original non-digital recordings and video should be considered artefacts. When copying a collection for transmission to someone else, or for long-term storage, consideration should be given as to whether the Artefact attribute needs to be dropped if the physical items are not included.
This simple example provides a definition of a photographic resource and the URL through which it may be accessed, plus a sample reference to it:
<Resource Key=’MyPhoto’>
<Title>Photograph of myself</Title>
<URL> file:mydir/MyPhoto.jpg </URL>
</Resource>
<ResourceRef Key=’MyPhoto’/>
The <DataControl> element provides any notices that must be displayed to the end-user before the associated resource is copied or transmitted to another user. Software components are not expected to act on those notices themselves. They should merely be displayed in order to prevent an accidental breach of trust or copyright. Permission and Prohibition are designed for informal control, such as when a family member asks that their photographs not be passed outside of the immediate family. Copyright is a formalised type of prohibition, usually applied to works of artistic, academic, or commercial value. These concepts are discussed under Worldwide Family History Data. These settings should be honoured when bundling a collection, or part of, for transmission to another researcher. The possible Sensitivity levels are exactly as defined for the Sensitivity data attribute at DATA_ATTRIBUTE.
A Resource definition may be parameterised so that multiple resource references can reuse common information. This scheme allows the URL, resource-title, narrative elements, and Parameter values to utilise ${param-name} markers. For instance, the following definition and reference selects a specific family photograph from a common collection:
<Resource Key=’rPhotos’ Abstract=’1’>
<Title>Family photograph: ${PhotoName}</Title>
<URL> file:myphotos/family/${PhotoName}.jpg </URL>
<Params>
<Param Name=’PhotoName’/>
</Params>
</Resource>
<ResourceRef Key=’rPhotos’>
<Param Name=’PhotoName’> Me </Param>
</ResourceRef>
This effectively creates an unnamed transient Resource with the modified parameter context. It would be functionally identical to the creation of a named permanent Resource.
The next example goes to a hypothetical web site to retrieve census images for England and Wales.
<Resource Key=’rCensusImage’ Abstract=’1’>
<Title>1851-1901 Census Images of England and Wales</Title>
<URL>http://www.census.com/image?series=${Series}&piece=${Piece}&folio=${Folio}&page=${Page}</URL>
<Params>
<Param Name=’Series’/>
<Param Name=’Piece’ Type=’Integer’/>
<Param Name=’Folio’ Type=’Integer’/>
<Param Name=’Page’ Type=’Integer’/>
</Params>
</Resource>
The valid Parameter data-types are documented at: Data Types. The same ItemList approach to lists is taken as for Property values. The semantic type is indicated by the SemType attribute which may use the Dublin Core vocabulary, e.g. SemType=’DC:title’ or SemType=’DC:publisher’.
Any <Param> element may specify a default value if necessary. The default value for the Optional attribute is ‘0’ (i.e. False) which means a non-blank value must be provided. When an ItemList Parameter is substituted then the result is a comma-separated list of the component Items.
The <BaseResourceLnk> element may nominate an Abstract Resource from which data may be inherited by the current Resource, in much the same vein as base classes and derived classes in software programming. An Abstract Resource must define no embedded Keys, can only reference other abstract entities, and must contain Parameter definitions rather than Parameter settings. The previous example using a <ResourceLnk> element with Parameters could have been replaced with two distinct Resource entities: one being the generic representation of a photograph from a particular folder, and the other being a specific photograph from that folder. For instance:
<Resource Key=’rMyPhoto’>
<BaseResourceLnk Key=’rPhotos’/>
<Params>
<Param Name=’PhotoName’> Me </Param>
</Params>
</Resource>
Application of any Parameter substitution must therefore occur after the inheritance process has completed. If an implementation of this mechanism creates a temporary conglomerate entity in memory by doing a physical merge then it must not be persisted back to the data file, otherwise it constitutes a data corruption.
Electronic resources attached to a data collection present a specific issue during data exchange, i.e. import/export. Subject to privacy controls, the relevant resources should be bundled with an exported STEMMA Document and transmitted along with it to whoever the recipients are. They cannot be included in the body of the Document in any practical way. Although this area still needs work, there are several existing document container file mechanisms available. For instance:
Some basic functional requirements include: compression, optional encryption, preservation of relative directory structure, custom name-value properties per item, ability to keep STEMMA <Resource> references valid after unpacking, and ability to address each item separately from outside the container. Some interesting discussion on this topic may be found on the BetterGEDCOM wiki at: BG Container Formats and Packaging Data.
[1] RFC 1738 requires an explicit host name in a URI employing the file scheme, e.g. file://host/g:/folder/file.jpg, even if the value is left blank. RFC 3986 allows this to be optional, e.g. file:/g:/folder/file.jpg. This means a relative file specification does not require a leading ‘/’ separator at all, e.g. file:folder/file.jpg.