Introduction‎ > ‎Extensibility‎ > ‎

Extended Properties

The ExtendedProperties element defines additional property names and types for usage within the current Dataset. These are effectively implemented as name-value pairs that can be used in subsequent Person or Place elements.

 

EXTENDED_PROPERTIES=

 

<ExtendedProperties>

[ <PersonProperties>

<PropertyDef Name=’prefix:name’  [Type=’type’] [Units=’units’] [DCType=’dc-type’] [ItemList=’boolean’]/>  ...

</PersonProperties> ]

[ <PlaceProperties>

<PropertyDef Name=’prefix:name’  [Type=’type’] [Units=’units’] [DCType=’dc-type’] [ItemList=’boolean’]/>  ...

</PlaceProperties> ]

[ <GroupProperties>

<PropertyDef Name=’prefix:name’  [Type=’type’] [Units=’units’] [DCType=’dc-type’] [ItemList=’boolean’]/>  ...

</GroupProperties> ]

</ExtendedProperties>

 

PROPERTY_VALUE=

 

{ <Property Name=’name’  [Key=’key’] [Value=’value’] [Units=’units’]

[DATA_ATTRIBUTE] … >

orig-text

</Property> }

|

{ <Property Name=’name’>

{ <Item [Key=’key’] [Value=’value’] [Units=’units’]

[DATA_ATTRIBUTE] … >

orig-text

</Item> } …

</Property> }

 

For Properties that accept the optional Value attribute, the value defaults to the original written value if the attribute is absent. This presumes that the original written value is syntactically valid for the given data-type.

 

For custom Properties, as opposed to the predefined STEMMA ones, a namespace prefix should be present. See Extended Vocabularies. In the case of properties of type EnumList then each term may have such a prefix, e.g.

 

Value=“pre1:Term1.pre2:Term2”

 

The list of valid data-types includes:

 

  • Text – simple text item (default data-type). Value may still be applicable, e.g. if there are corrections to the original.
  • Integer – non-negative whole number. Value applicable.
  • Number – decimal number. Value applicable.
  • Measure – decimal number with units. Value and Units applicable
  • Boolean – 1=true, 0=false. Value applicable.
  • Date – Requires std-date date-value, or a <Date> date-entity (see Dates). Value applicable.
  • Enum – Enumerated set of possible values. Value applicable.
  • EnumList – As per Enum but multiple entries can be concatenated with a period to create a dependent list, i.e. where each term is interpreted in the context of the previous one. Value applicable.
  • PersonRef – Person (or Contact) reference. Key applicable.
  • PlaceRef – Place reference. Key applicable.
  • GroupRef – Group reference. Key applicable.
  • EventRef – Event reference. Key applicable.

 

See Extended Vocabularies for defining custom data-types. The semantic type is indicated by the DCType attribute which uses the Dublin Core vocabulary, e.g. DCType=’DC.Title’ or DCType=’DC.Publisher.CorporateName.Address’.

 

Q: Should there be a variant of the ‘Text’ data-type that corresponds to text in particular language. For instance, in order to distinguish the name of an article – which may be in English – from a textual reference code (e.g. RG13) which would be language-independent?

 

When defining a property, the Units attribute can provide a list of valid unit terms, separated by commas, with the default being the first one. An example of this is used to define the STEMMA ‘Age’ property at Properties.

 

If ItemList is true (i.e. ‘1’) then the value may be an array of items, each of which is represented using an <Item/> element. If the value is represented by an entity Key, or has associated Units, then the respective attribute will be on the <Item> element. In the case of a list containing a single value, the non-Item syntax is acceptable even though ItemList was true.

 

For example:

 

<Dataset Name=’Example’ xmlns:t=’http://example.com/types’>

 

<ExtendedProperties>

<PersonProperties>

<PropertyDef Name=’t:PlaceOfEducation’ Type=’PlaceRef’/>

</PersonProperties>

</ExtendedProperties>

 

A sample reference might be:

 

<Person Key=’me’>

<Sex> 1 </Sex>

<Property Name=’t:PlaceOfEducation’ Key=’wPeoplesCollege’/>

<Names>

<Sequences>

<Canonical>Tony Proctor</Canonical>

<Sequence>

<Tokens><Token>Tony</Token></Tokens>

<Tokens><Token>Proctor</Token></Tokens>

</Sequence>

</Sequences>

</Names>

</Person>

 

Having presented this case as an example, we’ll now learn why it’s a bad example. Most data is related to a specific date, or to a range of dates, and a place of education is no different. The dates of admission and leaving from a place of education would be better represented as protracted Events with a PlaceLnk element pointing to the institution.

 

A better use of this feature might be adult ‘Height’ or ‘Weight’ for a Person, and ‘Ward’ for a Place. The Height and Weight properties would make use of the Units attribute and so we’ll give an example:

 

<ExtendedProperties>

<PersonProperties>

<PropertyDef Name=’t:Height’ Type=’Measure’ Units=’cm,inch’/>

<PropertyDef Name=’t:Weight’ Type=’Measure’ Units=’kg,lb’/>

</PersonProperties>

<PlaceProperties>

<PropertyDef Name=’t:Ward’ Type=’Text’/>

</PlaceProperties>

</ExtendedProperties>

 

A sample reference might be:

 

<Person Key=’me’>

<Sex> 1 </Sex>

 

<EventLnk Key=’eEnlistment’>

<Property Name=’t:Weight’ Units=’kg’ Value=’72.3’> 11st 5lb </Property>

<Property Name=’t:Height’ Units=’inch’ Value=’71’> 5ft 11in </Property>

</EventLnk>

 

</Person>

 

No list of accepted units is prescribed here, although the PropertyDef element can declare the accepted units using a comma-separated list in a Units attribute. Either the full name or the standard abbreviation may be used, together with the correct prefix if relevant (e.g. cm). Care should be taken not only to differentiate metric from imperial units, but also the UK/US differences for gallons, pints, tons, ounces, etc., wet and dry differences such as ounces versus ‘fluid ounces’, and nautical miles.

Comments