3.1. Introduction to NeXus definitions

While the design principles of NeXus are explained in the NeXus: User Manual, this Reference Documentation specifies all allowed base classes and all standardized application definitions. Furthermore, it also contains contributed definitions of new bases classes or application definitions that are currently under review.

Base class definitions and application definitions have basically the same structure, but different semantics: Base class definitions define the complete set of terms that might be used in an instance of that class. Application definitions define the minimum set of terms that must be used in an instance of that class.

Base classes and application definitions are specified using a domain-specific XML scheme, the NXDL: The NeXus Definition Language.

3.1.1. Overview of NeXus definitions

For each class definition, the documentation is derived from content provided in the NXDL specification.

The documentation for each class consists of sections describing the Status, Description, table of Symbols (if defined), other NeXus base class Groups cited, an annotated Structure, and a link to the NXDL Source (XML) file.

Each of the NXDL files has its own version number, for which there is an associated tag in the version repository. Such as NXcrystal-1.0 is tagged in GiHub and accessible via URL: https://github.com/nexusformat/definitions/releases/tag/NXcrystal-1.0

3.1.1.1. Description

General documentation if this NXDL file.

3.1.1.2. Symbols table

The symbols table describes keywords used in this NXDL file to designate array dimensions. At present, this list is not guaranteed to be complete (some array dimension names appear only in a Structure description and not here).

3.1.1.3. Annotated Structure

A representation of the basic structure (groups, fields, dimensions, attributes, and links) is prepared for each NXDL specification. Indentation shows nested structure. Attributes are prepended with the @ symbol. Links use the characters -> to represent the path to the intended source of the information.

Indentation is used to indicate nesting of subgroups (a feature common to application definitions). Within each indentation level, NeXus fields are listed first in the order presented in the NXDL file, then groups. Attributes are listed after the documentation of each item and are prefixed with the letter @ (do not use the @ symbol in the actual attribute name). The name of each item is in bold, followed by either optional or required and then the NXDL base class name (for groups) or the NeXus data type (for fields). If units are to be provided with the field, the type of the units is described, such as NX_DATE_TIME.

NeXus Links (these specifications are typically present only in application definitions) are described by a local name, the text ->, then a suggested path to the source item to be linked to the local name.

3.1.1.5. NeXus data type

Type of data to be represented by this variable. The type is one of those specified in NXDL: The NeXus Definition Language. In the case where the variable can take only one value from a known list, the list of known values is presented, such as in the target_material field above: Ta | W | depleted_U | enriched_U | Hg | Pb | C. Selections with included whitespace are surrounded by quotes. See the example above for usage.

For fields, the data type may not be specified in the NXDL file. The default data type is NX_CHAR. See NXdata for examples.

3.1.1.6. Units

Data units, are given as character strings, must conform to the NeXus units standard. See the NeXus units section for details.

3.1.1.7. Description

A simple text description of the field. No markup or formatting is allowed.

NXDL element type minOccurs maxOccurs
group [1] unbounded
field [1] unbounded
attribute [1] 1
[1](1, 2, 3) For NXDL base classes, minOccurs=0 is the default, for NXDL application definitions and contributed definitions, minOccurs=1 is the default. In all cases, the minOccurs attribute in the NXDL file will override the default for that element (group, field, attribute, or link).