SDD Primer Home   Index
	SDD Part 0: Introduction and Primer to the SDD Standard

3.4.1 Specifying the list of entities

Entities are the things that are described in an SDD document. In a taxonomic SDD document, entities will usually be taxa (species, genera etc) or specimens. In other documents, entities may be soils, diseases, vegetation communities or physical objects. SDD has been designed to be general and to accommodate taxonomic descriptions within a broader framework of general object and concept descriptions.

Entities in SDD are of two kinds - classes and objects. A class is a conceptual entity. In taxonomy, a taxon of any rank is a class (confusingly, taxonomy uses Class as one rank in the taxonomic hierarchy - this would be a class in SDD as would a species, genus etc). An object is a physical entity. In taxonomy, a specimen of an organism is an object.

Classes and objects are defined in SDD documents in much the same way, in a list in the <Entities> section. They are provided with key values by which they are then referenced throughout the document. Entities once defined may also be arranged into hierarchies or trees - see the topic Arranging entities into hierarchies (trees) for more information on this.

SDD provides mechanisms for defining entities by reference to external web services, such as names services and specimen databases. It is expected that entities will increasingly be referenced in this way, as this allows the document to remain valid under a changing taxonomy. However, entities may also be defined entirely within the document, in cases where a web service is unavailable or stand-alone integrity is required for some other reason.

Note that valid SDD documents may lack an <Entities> section, if the purpose of the document is to provide character resources without descriptions.

Example 3.4.1.1 defines two class entities (two taxa of different taxonomic rank, one defined internally and one by external reference) and an object entity (a specimen)

The <Entities> element may include a <Classes> collection and/or an <Object> collection.

Class entities are defined using one or more <Class> elements in the <Classes> collection. <Class> elements must be furnished with Key values (e.g. <Class key="1">). These are used to refer to the entity elsewhere in the SDD document. Key values for entities must be positive integers and must be unique across the set of entities specified in the document. In large projects, particularly collaborative ones, entities should be furnished with key values that are unique across the entire project, even if only a subset of entities are reported in any given SDD document.

The <ServiceProvider> element provides a URI to a web service that maintains a names catalogue relevant to the project

<ExternalID> specifies the ID (number or string) that by which the class is referenced in the nominated service provider. The information provided in <ServiceProvider> and <ExternalID> should be sufficient for a consuming application to query the service and be returned a name for the entity.

<FreeFormDescription> provides a local name for the entity. If <ServiceProvider> and <ExternalID> are provided, the name returned by the service will override any name given in <FreeFormDescription>.

<RankLevel> is used to specify a rank for the entity in a taxonomic hierarchy. The standard taxonomic ranks species, genus, subfamily, family etc should be used as content in <RankLevel>.

Object entities are defined in much the same way, in one or more <Object> elements in the <Objects> collection. <Objects> lack a <RankLevel> element.

The optional <ClassIdentification> subelement of <Object> may be used to refer the object to a specified class entity. In Example 3.4.1.1 the specimen object being defined belongs to the species Macrocheles inornatus, and is referred to that species using the class entity's key value in the mandatory ref attribute.

The IdentificationIsCertain attribute or <ClassIdentification> takes the value False if the reference to a class entity is only provisional. The default value for IdentificationIsCertain is True.

KRT Last Edit: 31 Dec 03