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 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. For reasons of avoiding naming collisions and to facilitate readbility and comprehension for those whom are new to an NXDL file, the following guidelines are strongly encouraged:

• All symbols used in the application definition are defined in a single Symbols table.

• The name of a symbol uses camel case without any white space or underscores.

  examples:

  nP: Total number of scan points

  nE: Number of photon energies scanned

  nFrames: Number of frames

  detectorRank: Rank of data array provided by the detector for a single measurement

• the Symbols table appears early in the .nxdl file above the NXDL group of type NXentry

example from NXtomo.nxdl.xml

<definition name="NXtomo" extends="NXobject" type="group"
  category="application"
  xmlns="http://definition.nexusformat.org/nxdl/3.1"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://definition.nexusformat.org/nxdl/3.1 ../nxdl.xsd"
>
        <symbols>
                <doc>
                        These symbols will be used below to coordinate datasets with the same shape.
                </doc>
                <symbol name="nFrames">
                        <doc>Number of frames</doc>
                </symbol>
                <symbol name="xSize">
                        <doc>Number of pixels in X direction</doc>
                </symbol>
                <symbol name="ySize">
                        <doc>Number of pixels in Y direction</doc>
                </symbol>
        </symbols>
        <doc>
                This is the application definition for x-ray or neutron tomography raw data.

                In tomography
                a number of dark field images are measured, some bright field images and, of course the sample.
                In order to distinguish between them images carry a image_key.
        </doc>
        <group type="NXentry" name="entry">
        <field name="title"  minOccurs="0" maxOccurs="1"/>
...

3.1.1.3. Annotated Structure

A representation of the basic structure of each NeXus class (its NeXus groups, fields, attributes and links, with their dimensions) is prepared from its NXDL file. Indentation shows nested structure. NeXus attributes are prepended with the @ symbol. NeXus links are shown as link followed by the target: a class path naming the NeXus field or group it is linked to.

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. NeXus 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.

NXDL links, which define a NeXus link (these specifications are typically present only in application definitions), are described by a local name, the text link, then the target: a class path naming the NeXus field or group it is linked to (see Links of a class).

3.1.1.4. Names of NeXus groups, fields, links and attributes

Name of the item. Since name needs to be restricted to valid program variable names, no “-” characters can be allowed. Name must satisfy both HDF and XML naming.

    NameStartChar ::=  _ | a..z | A..Z
    NameChar      ::=  NameStartChar | 0..9
    Name          ::=  NameStartChar (NameChar)*

    Or, as a regular expression:    [_a-zA-Z][_a-zA-Z0-9]*
    equivalent regular expression:  [_a-zA-Z][\w_]*

NeXus attributes, identified with a leading “at” symbol (@) and belong with the preceding field or group, are additional metadata used to define this field or group. In the example above, the program_name element has the configuration (optional) attribute while the thumbnail element has the mime_type (optional) attribute.

For NXDL groups, the XML attribute name may be absent. In such instances, the value shown in parentheses in the Name and Attributes column is a suggestion, obtained from the group by removing the “NX” prefix. See NXentry for examples.

When the name is allowed to be flexible (the exact name given by this NXDL specification is not required but is set at the time the HDF file is written), the flexible part of the name will be written in all capital letters. For example, in the base class NXdata, the DATA, VARIABLE, and VARIABLE_errors NeXus fields are flexible. A NeXus item whose NXDL term has nameType="any" stands for any name that no other NeXus item of the same NeXus group defines: a specified name wins.

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 NeXus 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 NXDL fields, the XML attribute type may be absent. 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 XML attribute in the NXDL file will override the default for that NXDL group or field. An NXDL attribute uses the XML attribute optional instead, and an NXDL link has no occurrence XML attributes.

3.1.1.8. Choice

The NXDL choice defines a NeXus group with a given name whose type is one of a list of base classes.

In some cases when creating an application definition, more than one choice of base class might be used to define a particular subgroup. For this particular situation, the choice was added to the NeXus NXDL Schema.

In this example fragment of an NXDL application definition, the pixel_shape could be represented by either NXoff_geometry or NXcylindrical_geometry.

    <choice name="pixel_shape">
      <group type="NXoff_geometry">
        <doc>
          Shape description of each pixel. Use only if all pixels in the detector
          are of uniform shape.
        </doc>
      </group>
      <group type="NXcylindrical_geometry">
        <doc>
          Shape description of each pixel. Use only if all pixels in the detector
          are of uniform shape and require being described by cylinders.
        </doc>
      </group>
    </choice>

The XML attribute name of the NXDL choice gives the name of the NeXus group that one of the NXDL groups listed within the choice defines. Thus, it is not necessary to specify the name in each NXDL group. (At some point, the NXDL Schema may be modified to enforce this rule.)

An NXDL choice may be used wherever an NXDL group is used. It must have at least two NXDL groups listed (otherwise, it would not be useful).