How to read a DDLm dictionary

Overall syntax

A DDLm dictionary provides a series of definitions for datanames. Each definition is contained within a "save frame", which is simply a block of text encompassed by save_ tokens:

save_xyz '_my.definition'
_description.text 'This is what it means'

In this example, we say that the 'save frame name' is xyz. Conventionally the save frame name is the same as the item being defined, but this is not required.

All of a dictionary's save frames are listed inside a single enclosing "data block", as required by the CIF syntax. Attributes in this data block (outside all of the save frames) relate to the dictionary as a whole, including version information, edit history, and dictionary name. So the basic structure of a DDLm dictionary looks like this:

# The FROB dictionary #
data_frob_dic frob
_dictionary.version 1.1
...       #Other dictionary information


## Many more save frame definitions

# Possibly more attributes for the enclosing data block

# End

Semantic structure

Attributes within each of the save frames create semantic relationships between the definitions, as well as defining the datanames. The most important relationship is the 'category' that a dataname belongs to.


DDLm requires that all datanames belong to "categories". Categories are also defined within save frames. Just as a dataname is assigned to a category, categories themselves are assigned to a 'parent' category, with the exception of the single Head category which acts as the parent of all categories within the dictionary.

Categories come in two main flavours: Set categories, and Loop categories, as stipulated by the _definition.class attribute in a category definition.

Datanames belonging to a Set category may not appear in a loop, that is, they take only a single value in a CIF datablock. Datanames in Loop categories may be appear in loops. When a Loop category is the child of another Loop category, datanames in each category may be freely mixed in a single loop, or else datanames from each category may be separated into separate loops (a separate document describes in more detail the nature of this mixing). A Set category may not be the child of a Loop category. There is no particular meaning for any other parent-child combinations of Set and Loop categories.

Basic attributes for assigning meaning to categories

The following main attributes are used to describe a category:


Must be Category


Set, Loop, or Head (once per dictionary)


Name of parent category


Name of this category

Conventionally, name of this category (unused)


Loop categories only - the values of this dataname are unique and so can be used to index the loop. This is the dataname used by dREL when using the category[key] construction.

Loop categories only - the values of these datanames are collectively unique and can be used to index the loop. Either contains a single dataname which is given in _category.key_id, or multiple datanames, none of which are the one given in _category.key_id

Dataname definitions

The following attributes must be provided in all dataname definitions.

The dataname as it will appear in a data file


When this definition was last edited


A human-readable definition for the dataname


The category that this dataname belongs to


The identifier of this dataname within a category


Whether or not values for this dataname appear in compound data types: 'Single' for a plain value, otherwise 'List' etc.


The type of the data values: Int, Real etc.

A dataname within a category is assigned an 'object id'. This allows a dataname to be referred to in category.object notation, which is useful in dREL scripts (see below). While the actual dataname that appears in a datafile (as defined in may also be written in this notation, it is not strictly required.

More information on attributes

The complete list of attributes can be found in file ddl.dic, itself a DDLm dictionary. Mandatory attributes are listed in the _dictionary_valid.application loop found towards the end of the file.


Both categories and dataname definitions can set the value of _method.expression to an expression in dREL. For a dataname, this describes how values of the dataname may be derived from the values of other datanames. For categories, this describes how keys of the category (and, optionally, other dataname values in the category) can be determined from the values of other datanames. For example, the geom_bond category can create a list of interatomic bond lengths based on bonding radii contained in the file.