DDLm: Next Generation

Dictionary Definition Language

by

Syd Hall, Nick Spadaccini and John Westbrook

(Version: 18 Mar 2007)

 

1. Introduction

 

This document provides the detailed specifications of DDLm, a next generation dictionary definition language designed to support the definition capabilities of the existing dictionary languages, DDL1 (Hall and Cook, 1995) and DDL2 (Westbrook and Hall, 1995), as well as provide a higher level of semantic content for domain dictionaries. While providing important new functionality to the dictionary developer, DDLm fully supports the semantic capabilities of existing IUCr data dictionaries. No changes are required in existing archival data files in order to apply domain dictionaries written in DDLm.

Data dictionaries contain precise, machine-parseable definitions of data items, and consequently play a vital role in the rapid and reliable exchange of electronic scientific data. Increasingly data dictionaries play a major role in the automatic interpretation and validation of data. In crystallography, the exchange and deposition of CIF data (Hall, Allen & Brown, 1991) is supported by CIF dictionaries for each of the different sub-disciplines (Hall & McMahon, 2005). At present CIF dictionaries are constructed using DDL1 and DDL2; the latter having evolved from the former to extend the scope and precision of dictionary definitions for macromolecular structural data.

The automatic and seamless exchange of electronic data depends implicitly on the level of usable semantic information provided by dictionaries, as this largely determines the precision of the validation and knowledge management processes. For example, the ability of a dictionary definition language to express the algorithmic methods that relate derived data items enables data definitions to assume a much more fundamental role in data validation and evaluation; a role currently performed by customized software. The advantage of using semantic knowledge stored in a dictionary for this purpose (particularly if this information has been adopted internationally by an official scientific body) is the assurance that standard, well-understood algorithms are uniformly adhered to.

Scientific data, by its very nature, are in a state of continual change and this necessitates efficient exchange processes that are in step with the evolution and creation of new data definitions. Semantically-rich and readily-updatable data dictionaries allow this to happen. DDLm is a next generation dictionary definition language. It encompasses the particular strengths of DDL1 and DDL2, and draws upon many attributes used in StarDDL, to provide a more hierarchical, concise and implicit approach to data definitions. In particular, it incorporates a methods expression language, dREL (Spadaccini, Hall and Castleden, 2000) for relating derived data items. dREL applies data items computationally in relational expressions as object-oriented variables. This, with the facility to import externally-sourced data definitions, provides dictionaries written in DDLm with a higher level of functionality which encourages modular dictionaries with shared common definitions.

For those unfamiliar with the construction of data dictionaries, we start with a brief introduction to the terminology used in this document. The term "DDL", already used above, refers to a dictionary definition language in which the lingua is composed of a prescribed set of attributes. Each attribute serves to identify a particular characteristic of a data item. The definition of a particular data item is achieved by assigning values to the appropriate attributes that describe its precise nature, and its relationship to other items. Which attributes are used in a definition, and which are not, is detailed later in 6.2. The collection of definitions for set of data items is referred to as a domain (or discipline) dictionary. It is also important to appreciate that the attributes themselves are defined within their own dictionary using the same DDL (i.e. each attribute is specified using a collection of the appropriate attributes) and this is referred to as the DDL dictionary. Finally, when a collection of data items is ascribed actual values, this is referred to as a data file or an instance document. These terms are used throughout this document.

 

 

2. Overview of DDLm

 

2.1 Main Differences to DDL1 and DDL2

The attributes of DDLm encompass those in DDL1 and DDL2, albeit with a richer syntax designed to increase the semantic content of definitions while keeping definition repetition to a minimum. The main difference to DDL1 and DDL2 are the addition of:

• methods using a symbolic algorithmic language, dREL, to relate derivable items,
• stricter and multi-level attribute inheritance between data categories,
• increased precision and flexibility in data typing,
• implicit child-parent relationship between equivalent data items, and
• procedures for importing common definitions from external dictionaries.

 

2.2 Implicit child relationships of linked items

Parent category relationships (i.e. categories of items that are derived from or members of another category) are explicitly identified in DDLm but not the child categories. Child category relationships can readily be derived on instantiation of the dictionary from the parent links. Removing the need to identify child categories in a dictionary eliminates a cumbersome and error-prove task for dictionary developers, and enhances the readability of the dictionary by reducing redundant information which obscures more critical aspects of definitions.

 

2.3 Stronger data typing.

DDLm provides an expanded attribute set for specifying data types with the introduction of attributes for establishing the nature and the origin of items. The data typing attributes now cover four basic classes of information; known simply as the container, contents, purpose and dimension attributes. The container attribute identifies the composition of the item value. Allowed container types are Single, Multiple, Array, List, Tuple and Table. The contents attribute identifies the nature of the individual value(s) within the container, in terms of numerical and character descriptors. The contents attribute types are enumerated but can be expanded in the auxiliary file com_val.dic. The purpose attribute identifies the origin and function of a data item. This information is important at many levels; it indicates, for example, if a numerical value is expected to have a standard uncertainty value or not; if the value is an active filename, or a code used to import definitions; if the value has been measured, observed or assigned. This detail is needed for manipulating data within a method expression using the algorithmic language dREL. Also, by specifying that an item is measured, observed or assigned, associated validation and evaluation processes may be handled consistently and, in some cases, automatically within the method expressions.

 

2.4 Category inheritance

In dictionaries written in DDLm the hierarchical parent relationships between categories of data items is specified explicitly. By default, each category inherits properties of its parent. The inheritance process is detailed later in §4.1.

 

2.5 Data Tag construction

The naming of individual items, and groups of items, is more flexible in DDLm. The name of a category is in most cases the leading string in an item tag. This is no longer a requirement, however, because the category tag and object tag (identified by the trailing characters) are now specified separately in a dictionary using the attributes _name.category_id and _name.object_id. Identifying the two parts of an item tag with separate attributes:

• permits the tag constructions that do not comply to the DDL2 name rules,

• avoids progressive elongation of tags for deeply nested families of categories, and

• removes the need for a period to be used to separate the category and object names.

 

 

3. Dictionary Organisation

 

The construction and organization of a dictionary written in DDLm conforms to the Star File syntax. Each item definition and each category definition is contained within a save_ frame, known as the 'definition frame'. These frames contain a sequence of 'attributes' as tag-value pairs. All definition frames in a dictionary file are contained with a single data_ block, known as the 'dictionary block'. Attributes defining dictionary-only information are contained within the data block but not within a save frame.

 

3.1 Definition frame

Each item definition and category definition in a dictionary is contained within a save_ frame i.e. the definition starts with a save_frame_name statement and ends with a save_ statement. The 'frame_name' usually matches the tag of the category or item being defined within the frame. Here an example of a category definition of ATOM_SITE from the Core_Structure dictionary.

 

Definition 3.1.1

Here is an example of an item definition from the Core_Structure dictionary.

 

Definition 3.1.2

 

3.2 Dictionary block

Each dictionary written in DDLm must start with a data block statement which identifies the dictionary. For example, in the core_structure dictionary this statement is

data_CORE_STRUCT

whereas in the dictionary defining the DDLm attributes themselves, it is

data_DDL_DIC

 

3.3 Dictionary-specific Attributes

Each dictionary block contains attributes specifying the properties of the dictionary file as a whole. These attributes are not contained within a save frame and are inherited by all other categories and items, except where the same attribute in individual definitions overrides the inherited attribute value. For example, the start of the core_structure dictionary is as follows.

 

Definition 3.3.1

 

The dictionary block must also contain a "head" category definition frame that is the parent of all other categories in the dictionary. For example, the core_structure dictionary block contains the head category definition as follows.

 

Definition 3.3.2

The dictionary block also contains dictionary audit information. For convenience, this is usually placed at end of the dictionary, following the last item definition frame. Here is a typical audit list.

 

Example 3.3.1

 

 

4. Category and Item Relationships

 

4.1 Category Hierarchy

As stated in section §3.3, each dictionary block contains a head category definition that is the "parent" for all other categories in the dictionary. The head category is at the top of a hierarchical tree of categories in the dictionary, and all other categories in the dictionary file are, directly or indirectly, its children. In a dictionary written in DDLm, lower categories in the hierarchy inherit attribute values from their parent categories, except when these are superceded by the local specification of the same attribute.

Example 4.1.1 below shows is a typical list of categories in a dictionary (category tags in blue and green), followed by the contained items (item tags in red) and categories. In this example, the items describing the crystal unit cell in the core_crystal dictionary are listed.

 

Example 4.1.1

The parent of each category is specified in its definition with the attribute _category.parent_id. For example, in the CELL category definition this attribute may have the value 'core_crystal'; whereas in the CELL_angle category definition this attribute would have the value 'cell'. The list shown in Example 4.1.1 is indented according to the hierarchical relationship of items to the parent category. Part of this relationship is the assumption that all categories of items can be subsumed (i.e. merged or joined) into the parent category. This property is however modified by the category scope, which may have either the state code List or Set (the scope state Head also exists but will not be discussed here). Whereas items in an instance document belonging to a category of scope List must appear as a looped list (see §4.2), items with scope Set need not (they may, however, be referenced as a class of objects in methods expressions - examples of this will be shown later). More importantly, items in a Set category are seen to be automatic members of the parent category whereas List items are not unless the attribute _category.parent_join is specified as Yes in the category definition.

We shall see later that the ability to specify relationships between categories of items is particularly important in enriching the semantics of data.

 

4.2 List categories and Reference Keys

When an item can have more than one value it will appear in a data file as a looped list, and all items in this list will be members of a single category or of joined categories (see §4.3). For example, the coordinates of atomic sites are defined in the ATOM_SITE category (see Definition 3.1.1 above).

Example 4.2.1

A looped list is a 2D table in which the data names are a row of header tags identifying columns of values. E.g., the tag _atom_site.label refers to the column of values 'o1', 'o2',...,'c3'. In each table at least one item must have unique values in order that other values in a row may be unambiguously accessed. These rows of values are often referred to as 'packets'or 'list instances'. The item that is designated to have 'unique' values in a category is known as the 'category key'. The key in the atom_site category above is _atom_site.label and each value of this item provides the access to the other three items in the packet. For example, 'o3' points to the values '.2502(7)', '.5705(7)' and '.6011(14)', and no others! In a dictionary the key is specified in the category definition with the _category_key.generic or _category_key.primitive attributes (see the atom_site definition in §3.1 above).

The attribute information in the atom_site category definition (see Definition 3.1.1) refers all atom_site items. That is, the properties of a category apply to all items that are defined with the attribute _name.category_id set with the value 'atom_site'.

The definition of the key item _atom_site.label is as follows.

 

Definition 4.2.1

Compared to _atom_site.description (see Definition 3.1.2), the _atom_site.label definition is compact because the attribute _import_list.id is used to insert attributes from the generic definition atom_site_label stored in the file com_att.dic. Using an import attribute here is convenient because atom label items are defined in many different categories and dictionaries, and they are identically-equivalent being derived from the labels residing in the atom_site category. Placing the common attributes of derived items in generic definition and in a separate file, then using the import commands to expand definitions at application time, is both efficient and secure (a change to the generic definition will affect all equivalent definitions).

Here is the generic definition atom_site_label which resides in the file com_att.dic

 

Definition 4.2.2

 

Note that the processing of import attributes usually assumes that locally specified attributes take precedence over imported attributes (more details are given in §6.17 and §6.18).

 

4.3 joined categories

As discussed in §4.2, the specification of an access key is essential for each List category. In this section we describe how, in special circumstances, list categories may be joined with their parent List categories at instantiation. This may apply when categories have equivalent category keys and list structures, but, for reasons of data presentation and simplification, items are instantiated as separate lists. For example, the use of separate lists can be efficient for lists in which there is significant disparity between the density of active data from packet to packets. In such cases the dense and sparse components of the packet are placed in separate list categories, with one category defined as the parent of the other (see §4.1).

The ability to join equivalent but separated list categories is specified within the definition of the 'child' category using the attribute _category.parent_join set to Yes. Note that the keys of joined categories may be used interchangeably in the instance document.

In the Core_CIF dictionary, an example of joined categories is atom_site and atom_site_ANISO. We have seen in §3.2 that the key item of the first is _atom_site.label and the definition below shows that the key item of the second is _atom_site_aniso.label. These are interchangeable.

 

Definition 4.3.1

Here is a simple data file showing items in these categories expressed as separate lists.

 

Example 4.3.1

Because the categories atom_site and atom_site_ANISO are defined as joinable, these lists may be considered to be one list by parsers. That is, as follows.

 

Example 4.3.2

The concept of joined lists is important to the generality of data relational languages, such as dREL, used in method expressions. Joinable lists are assumed to have equivalent key items, so that above, either of the items _atom_site.label and _atom_site_aniso.label may be used interchangeably as the key to the joined list. This allows items in joined lists be addressed simply in terms of the extension names of the parent category name. That is, reference to atom_site.U_11, point to the value of _atom_site_aniso.U_11.

 

4.4 LINKED List Keys

The values of category keys uniquely identify data packets in lists. If any item in a List category has the same values as a key, within or without the category, this is identified as a list link. For example, in the instance list below the item _atom_site.calc_attached_atom has the same label values as the key to the same list.

 

Example 4.4.1

This relationship is specified in the definition of _atom_site.calc_attached_atom with the attribute _name.linked_item_id indicating that _atom_site.label is the derivative parent.

 

Definition 4.4.1

In the example 4.4.1, the values of _atom_site.type_symbol are the element symbols stored in the ATOM_TYPE category list as the key item _atom_type.symbol. Again, this link is specified in the definition of _atom_site.type_symbol using the attribute _name.linked_item_id.

 

Definition 4.4.2

 

4.5 LINKED Keys of Derivative Items

The origin of data items is considered to be primitive or derivative. If a data value is measured, observed or assigned it is classified as 'primitive'. Primitive items cannot be derived from other data. All other data are classified as 'derivative'. Derivative data values may be evaluated (i.e. calculated) from their relationships to other data items, primitive and derivative. Identifying the origin of data is important because the value of a derivative item can determined from a method expression relating it to the known values of other data items. Instance values of derivative items may be evaluated singly or as entities in a category list. In some cases the entire list category may be considered derivative, and evaluated using methods expressions.

In this section, we explain how category keys are related when one list category is derived from another. If an entire list category is derivative, its list key will be dependent, or linked, to the key of list from which it was derived.

This is best understood from an example. We will use the dependence of a list of geometric bond distances between the atom sites in a molecule on the list of atom site coordinates. The distances form a 'derivative list' because are derived from the coordinate list. Using the definitions in the CoreCIF dictionary, we see that the category geom_bond items may be derived from category atom_site values [Note that for the sake of simplicity the geometry bond examples and definitions shown below have intentionally excluded the symmetry of the atomic sites].

Here is an instance file containing these two lists.

 

Example 4.5.1

These two lists are linked through their category keys. In the ATOM_SITE list, the defined key is _atom_site.label (see the definition in §3.1). In the GEOM_BOND list the key is _geom_bond.id which is a tuple made up of two ATOM_SITE keys identifying the 'bonded' atoms in the site list. That is, the GEOM_BOND key is dependent on the existence of the ATOM_SITE keys.

We will now show how this is specified in a dictionary written in DDLm. Here is the definition of the GEOM_BOND category indicating that _geom_bond.id is the category key. The definition of _geom_bond.id follows and here the relationship of the key to the individual atom labels _geom_bond.atom_site_label_1 and _geom_bond.atom_site_label_2 is specified in the _method.expression attribute.

 

Definition 4.5.1

 

Definition 4.5.2

The following definition of _geom_bond.atom_site_label_1 shows how the dependency of this label on _atom_site.label is specified with the attribute _name.linked_item_id.

 

Definition 4.5.3

That is, each value of _geom_bond.atom_site_label_1 (and _geom_bond.atom_site_label_2) must match a value of _atom_site.label, otherwise the file is in error. The link between these labels means that dREL may access the coordinate packets in the ATOM_SITE list directly using _geom_bond.atom_site_label_1 or _geom_bond.atom_site_label_2 values in the GEOM_BOND list.

 

 

6. Glossary of DDLm Attributes

 

6.1 DDLm dictionary

The purpose and function of the individual DDLm attributes are defined in their own DDLM dictionary ( filename: ddl_m.dic) using the attributes themselves. All attributes are grouped into categories but only the category tags of List categories (as opposed to Set categories) are shown (in blue capital letters) with the parent category name in parentheses. Note that unless specified explicitly using _category.parent_join List categories in DDLm cannot be joined to their parent categories (i.e. their lists cannot be merged).

 

 

 

6.2 Format of DDLm definition frames

The basic organisation of DDLm definition frames is consistent across all definitions and domain dictionaries. Certain attributes are mandatory for the construction of a valid category or item definition frame. The appropriateness of attributes in the different frames is specified formally in the DDLM dictionary using the attributes _dictionary_valid.scope and _dictionary_valid.attributes. The DDLM dictionary is the only dictionary in which these two attributes may be invoked. The syntax of the value for _dictionary_valid.attributes is as follows, where:

+ <attribute tag> stipulates that this attribute is mandatory,

. <attribute tag> stipulates that this attribute is encouraged,

! <attribute category> stipulates that this category of attributes is invalid.

 

 

The construction of dictionary definitions has already been illustrated in the Sections 3 and 4. For the category definitions, the attributes needed are relatively simple (see Definitions 3.3.2, 4.3.1 and 4.5.1). For the item definitions, the attributes required may vary considerably, but certain attributes are mandatory (see Definitions 4.2.2, 4.4.1, 4.4.2, 4.5.2 and 4.5.3).

For the sake of brevity, the description of individual attribute definitions that follow will not include every attribute applied (these may be seen in the file ddl_m.dic). Only the characteristics that uniquely distinguish each attribute will be shown and discussed.

 

 

6.3 ALIAS Attributes

The ALIAS attributes identify identically-equivalent tags that may be aliased (i.e. substituted) for the defined tag. These attributes are included when equivalent items exist in this or another dictionary.

 

6.3.1 ALIAS

 

6.3.2 _alias.definition_id

Specifies the tag of another item equivalent to the item in the current definition.

 

6.3.3 _alias.dictionary_uri

Specifies the universal resource identifier of the dictionary containing the definition of an item aliased to the item in the current definition.

6.4 CATEGORY Attributes

The CATEGORY attributes specify the group properties of a related set of items.

 

6.4.1 category

 

 

6.4.2 _category.parent_id

Specifies the parent (the next highest in the category hierarchy) category tag of the category being defined (see also 4.1 above).

 

 

6.4.3 _category.parent_join

Specifies if at instantiation time the defined List category may be joined to the parent List category (see also 4.3 above).

 

 

6.5 CATEGORY_KEY Attributes

The category_key attribute identifies the category keys of a List category. In an instance document, in order to access specific packets of item values within a looped list, these keys must have a unique value. Two keys types are provided; _category_key.generic and _category_key.primitive. The generic key is a tag identifying a single key item or an item containing a method specifying the key item(s). The generic key allows the key item(s) to be varied, and selected, according to instantiated values of items outside the category. The primitive key is a tuple containing the one or more item tags that form the basic key. The components of the primitive key are fixed.

6.5.1 category_key

 

6.5.2 _category_key.generic

Specifies the tag of the item whose value is the key to packets of items in a looped list of items in a List category. See 4.2 for an example of a generic key.

 

6.5.3 _category_key.primitive

Specifies a tuple of an item or items whose composite value is the key to packets of items in a List category. See 4.2 for an example of a primitive key.

 

 

6.6 CATEGORY_MANDATORY Attributes

The category_mandatory attribute identifies the items that must be present in an instance data list of the category items.

6.6.1 category_mandatory

 

6.6.2 _category_mandatory.item_id

Specifies the tag of the item that must be present in an instance data list of the category items.

 

6.7 DEFINITION Attributes

The DEFINITION attributes identify the nature and purpose of definition frames in a dictionary.

6.7.1 definition

 

6.7.2 _definition.class

Specifies the class or purpose of the dictionary, category or item being defined. The allowed definition classes are listed below.

 

6.7.3 _definition.id

Specifies the tag of the item or category being defined within the current definition frame.

 

6.7.4 _definition.scope

Specifies the scope of item being defined in terms of its inheritance. The allowed definition scopes are shown.

 

6.7.5 _definition.update

Specifies the calendar date (format 'yyyy-mm-dd') that the item definition was last updated.

 

6.7.6 _definition.xref_code

Specifies a code that identifies the same item defined in another dictionary identified by the DICTIONARY_XREF category of attributes.

 

 

6.8 DESCRIPTION Attributes

The DESCRIPTION attributes provide various text descriptions of the defined data item.

6.8.1 description

 

6.8.2 _description.key_words

Specifies a sequence of comma-delimited word sequences that are "key words" identifying an item for thematic searches.

 

6.8.3 _description.common

Specifies the common or usual name of the defined item.

 

6.8.4 _description.text

Specifies the text describing of the defined item.

 

 

 

6.9 DESCRIPTION_EXAMPLE Attributes

The DESCRIPTION_EXAMPLE attributes provide descriptive example values of the defined item. These values are not machine interpretable.

6.9.1 description_example

6.9.2 _description_example.case

Specifies an example value for the defined item.

 

6.9.3 _description_example.detail

Specifies the text details of an example value for the defined item.

 

 

6.10 DICTIONARY Attributes

The DICTIONARY attributes describe aspects of the dictionary as a whole. These attributes are specified within the dictionary block but not within a definition frame.

6.10.1 dictionary

6.10.1 _dictionary.class

Specifies the nature or purpose of the items defined in the dictionary.

 

6.10.2 _dictionary.date

Specifies the calendar date (format 'yyyy-mm-dd') that the dictionary was last updated.

 

6.10.3 _dictionary.ddl_conformance

Specifies the version code (nn.mm.ii) for the DDL dictionary to which all definitions in the current dictionary conform.

 

6.10.4 _dictionary.namespace

Specifies a unique name for the dictionary that may be prefixed to an item tag (defined within the specific dictionary) with a separating colon character ":" when used in dictionary applications. Because tags must be unique, dictionary namespace prefixes are unlikely to be used in data files.

 

6.10.5 _dictionary.uri

Specifies the URI location and filename of the current dictionary.

 

6.10.6 _dictionary.title

Specifies the common title for the current dictionary.

 

6.10.7 _dictionary.version

Specifies the version code (nn.mm.ii) of the dictionary. This code must match a value for _dictionary_audit.version in the dictionary audit list (see 6.11)

 

 

6.11 DICTIONARY_AUDIT Attributes

The DICTIONARY_AUDIT attributes describe the status and the origins of a dictionary.

6.11.1 dictionary_audit

 

6.11.2 _dictionary_audit.date

Specifies the calendar date (format 'yyyy-mm-dd') of the last revision of the dictionary.

 

6.11.3 _dictionary_audit.revision

Specifies the description of the revision applied.

 

6.11.4 _dictionary_audit.version

Specifies the code (nn.mm.ii) identifying the version of a dictionary (see _dictionary.version) associated with a revision.

 

 

6.12 DICTIONARY_VALID Attributes

The DICTIONARY_VALID attributes identify when attributes are used in the different definition scopes. That is, whether specific attributes are mandatory or prohibited in the dictionary, category or item definitions. The DICTIONARY_VALID attributes are only used in the DDL dictionary. For the current invocation see Section 6.2.

6.12.1 dictionary_valid

 

6.12.2 _dictionary_valid.attributes

Specifies as text the names of attributes that are mandatory or prohibited.

 

6.12.3 _dictionary_valid.scope

Specifies the dictionary scope associated with the _dictionary_valid.attributes lists.

 

 

6.13 DICTIONARY_XREF Attributes

The DICTIONARY_XREF attributes identify external dictionaries to which items in the current dictionary are cross-referenced using the _definition.xref_code attribute.

6.13.1 dictionary_xref

 

6.13.2 _dictionary_xref.code

Specifies the key code of the cross-referenced dictionary.

 

6.13.3 _dictionary_xref.date

Specifies the calendar date (format 'yyyy-mm-dd') of the cross-referenced dictionary.

 

6.13.4 _dictionary_xref.format

Specifies the format description of the cross-referenced dictionary.

 

6.13.5 _dictionary_xref.name

Specifies the common name of the cross-referenced dictionary.

 

6.13.6 _dictionary_xref.uri

Specifies the URI of the cross-referenced dictionary.

 

 

6.14 ENUMERATION Attributes

The ENUMERATION attributes specify any prescribed constraints on the values of defined items.

6.14.1 enumeration

 

6.14.2 _enumeration.default

Specifies the default value the value of the defined item, which is used if a value is not present in the instance data file.

 

6.14.3 _enumeration.range

Specifies the range of values the defined item must lie within. The minimum and maximum values are separated by a colon ":" character.

6.14.4 _enumeration.def_index_id

Specifies the tag of an item whose coded value is used as an index to select a default enumeration value from the _enumeration_default list (see 6.15). The code value must match one of the _enumeration_default.index values.

6.14.5 _enumeration.mandatory

Specifies if it obligatory that the enumeration constraints (set by other attributes) MUST be adhered to in any validation process. The default is Yes.

6.15 ENUMERATION_DEFAULT Attributes

The ENUMERATION_DEFAULT attributes specify the allowed default values for the defined item. The single default value applicable for a specific instance document is determined by the value of tag identified by the attribute _enumeration.def_index_id (see 6.14.3). The code value is used as an index to select a default enumeration value from the _enumeration_default list by matching one of the _enumeration_default.index values.

6.15.1 enumeration_default

6.15.2 _enumeration_default.index

Specifies the key index codes to the list of eligible default values. This code is matched at instantiation time with the value of the item identified by the attribute _enumeration.def_index_id.

6.15.3 _enumeration_default.value

Specifies eligible default values. The appropriate default is selected at instantiation time by matching the _enumeration_default.index code with that of the item identified by the attribute _enumeration.def_index_id.

6.16 ENUMERATION_SET Attributes

The ENUMERATION_SET attributes specify a set of predetermined values (i.e. states) for an item.

6.16.1 enumeration_set

6.16.2 _enumeration_set.state

Specifies permitted codes or 'states' for a item.

6.16.3 _enumeration_set.construct

Specifies the construction rules of permitted states in terms regular expression (REGEX) rules.

6.16.4 _enumeration_set.detail

Specifies the description of a permitted enumeration state.

6.16.5 _enumeration_set.xref_code

Specifies a cross-reference code for a permitted state with respect to the codes used in the dictionary identified with the DICTIONARY_XREF category attributes.

6.16.6 _enumeration_set.xref_dictionary

Specifies the code for the dictionary identified with the DICTIONARY_XREF category attributes.

 

6.17 IMPORT Attributes

The IMPORT attributes faciltate the importation of definition lines from external files. These attributes do not contribute to the direct definition of an item but provide a mechanism for inserting external definition material into a dictionary.

6.17.1 import

 

6.17.2 _import.block

Specifies the block of definitions to be imported from _import.file.

6.17.3 _import.file

Specifies the URI containing the definition block specified by _import.block.

6.17.4 _import.if_dupl

Specifies the action to be taken if the imported definition block already exists in the importing dictionary file. The actions allowed appear as enumerated states.

6.17.5 _import.if_miss

Specifies the action to be taken if the imported definition block is missing from the file identified by _import.file. The actions allowed appear as enumerated states.

6.17.6 _import.scope

Specifies the scope of imported definition block identified by _import.block. The scopes allowed appear as enumerated states.

 

6.18 IMPORT_LIST Attributes

The IMPORT_LIST attributes specify the importation of definition material from external files.

6.18.1 import_list

6.18.2 _import_list.id

Specifies all of the attributes described in 6.17 for the importation of definition material from external files. This attribute is a convenient composite of the IMPORT attributes in that they are presentated as a single List () rather than as a looped list.

 

6.19 LOOP Attributes

The LOOP category attributes specify the loop level of the defined item. For CIF data this will always be 1, but for STAR File data nested lists to any level are permitted.

6.19.1 loop

6.19.2 _loop.level

Specifies the loop level of the defined item.

 

6.20 METHOD Attributes

The METHOD category attributes specify methods for expressing relationships between the defined item and other defined items.

6.20.1 method

 

6.20.2 _method.purpose

Specifies the purpose code of the method for the defined item. Three method classes exist: Evaluation, Definition and Validation.

6.20.3 _method.expression

Specifies the script, in the dREL language, relating the defined item to other items.

 

6.21 NAME Attributes

The NAME attributes specify the name constructs of the defined item.

6.21.1 name

 

6.21.2 _name.object_id

Specifies the 'object tag' of the defined item. This is a unique name string identifying an object with its category.

6.21.3 _name.category_id

Specifies the name of the category the defined item is a member of.

6.21.4 _name.linked_item_id

Specifies the tag that the defined item is a derivative of, and implicitly dependent on the existence of, the linked item when used in an instance document. See 4.4 and 4.5 for examples.

 

6.22 TYPE Attributes

The TYPE attributes specify the nature and origin of the defined item.

6.22.1 type

 

6.22.2 _type.container

Specifies the container type of the defined item. This is the simplest type description of the text string representing a value. Seven container types are recognised.

6.22.3 _type.contents

Specifies the code identifying nature of the defined item. The allowed codes are specified in an enumeration list stored in the external file com_val.dic (see below).

The allowed codes for _type.contents are stored in the external file com_val.dic.

 

6.22.4 _type.purpose

Specifies the purpose, origin or function code of the defined item.

 

 

6.22.5 _type.dimension

Specifies the array dimensions (number of elements in each dimension) of the defined item.

 

6.23 UNITS Attributes

The UNITS attributes specify the units of measurement for a defined item.

6.23.1 units

 

6.23.2 _units.code

Specifies the name of the units of measurement of the defined . The allowed codes are specified as an enumeration list in the external file com_val.dic.

The allowed _units.code values are specified in the external file com_val.dic.

 

 

7. REFERENCES

 

Allen, F.H., Barnard, J.M., Cook, A.F.P. & Hall, S.R. (1995). J. Chem. Inform. Comp. Sci. 35, 412-427.

Cook, A.F.P. (1991) 'Dictionary Definition Language in STAR File Format.' ORAC Report.

Hall, S.R. The STAR File: (1991) 'A New Format for Electronic Data Transfer and Archiving.' J Chemical Information and Computer Science 31, 326-333.

Hall, S.R., Allen, F.H. & Brown, I.D. (1991) 'The Crystallographic Information File (CIF): A New Standard Archive File for Crystallography.' Acta Cryst. A47, 655-685.

Hall, S.R. & Cook, A.P.F. (1995) 'STAR Data Definition Language: Initial Specification.' J Chemical Information and Computer Science 35, 819-825.

Hall, S.R. & Spadaccini, N. (1994) 'The STAR File: Detailed Specifications.' J Chemical Information and Computer Science 34, 505-508.

Spadaccini, N., Hall, S.R., and Castleden, I.R. (2000) 'Relational Expressions in STAR File Dictionaries.' J Chemical Information and Computer Science 40, 1289-1301

Westbrook, J.D & Hall, S.R. (1995) 'A Dictionary Description Language for Macromolecular Structure.' Draft DDL V 2.1.1 (draft from ndbserver.rutgers.edu/mmcif/ddl/)