2.3.2. NXDL: The NeXus Definition Language¶
Information in NeXus data files is arranged by a set of rules. These rules facilitate the exchange of data between scientists and software by standardizing common terms such as the way engineering units are described and the names for common things and the way that arrays are described and stored.
The set of rules for storing information in NeXus data files
is declared using the NeXus Definition Language.
NXDL itself is governed by a set of rules (a schema)
that should simplify learning the few terms in NXDL.
In fact, the NXDL rules, written as an XML Schema, are machine-readable
using industry-standard and widely-available software tools for XML files such as
xsltproc
and xmllint
.
This chapter describes the rules and terms from which NXDL files are constructed.
2.3.2.1. Introduction¶
NeXus Definition Language (NXDL) files allow scientists to define the nomenclature and arrangement of information in NeXus data files. These NXDL files can be specific to a scientific discipline such as tomography or small-angle scattering, specific analysis or data reduction software, or even to define another component (base class) used to design and build NeXus data files.
In addition to this chapter and the
Tutorial chapter, look at the
set of NeXus NXDL files to learn how to read
and write NXDL files. These files are available from
the NeXus definitions repository
and are most easily viewed on GitHub:
https://github.com/nexusformat/definitions
in the base_classes
, applications
, and contributed
directories. The rules (expressed as XML Schema)
for NXDL files may also be
viewed from this URL. See the files
nxdl.xsd
for the main XML Schema
and nxdlTypes.xsd
for the listings of
allowed data types and categories of units
allowed in NXDL files.
NXDL files can be checked (validated) for syntax and content.
With validation, scientists can be certain their definitions
will be free of syntax errors. Since NXDL is based
on the XML standard, there are many editing programs [1]
available to ensure that the files are well-formed. [2]
There are many standard tools such as xmllint
and xsltproc
that can process XML files.
Further, NXDL files are backed by a set of rules
(an XML Schema) that define the
language and can be used to check that an NXDL file
is both correct by syntax and valid by the NeXus rules.
NXDL files are machine-readable. This enables their automated conversion into schema files that can be used, in combination with other NXDL files, to validate NeXus data files. In fact, all of the tables in the Class Definitions Chapter have been generated directly from the NXDL files.
Tip
Use the reST anchors when writing documentation in NXDL source files. Since the anchors have no title or caption associated, you will need to supply text with the reference, such as:
:ref:`this text will appear <anchor>`
Since these anchors are absolute references, they may be
used anywhere in the documentation source
(that is, within XML <doc>
structures
in .nxdl.xml files or in .rst
files).
The language of NXDL files is intentionally quite small,
to provide only that which is necessary to describe
scientific data structures (or to establish the
necessary XML structures). Rather than have scientists
prepare XML Schema files directly, NXDL was designed to
reduce the jargon necessary to define the structure of
data files. The two principle objects in NXDL files are:
group
and field
.
Documentation (doc
) is optional for any NXDL
component.
Either of these objects may have additional
attributes
that contribute simple metadata.
The Class Definitions Chapter lists the various classes from which a NeXus file is constructed. These classes provide the glossary of items that could, in principle, be stored in a standard-conforming NeXus file (other items may be inserted into the file if the author wishes, but they won’t be part of the standard). If you are going to include a particular piece of metadata, refer to the class definitions for the standard nomenclature. However, to assist those writing data analysis software, it is useful to provide more than a glossary; it is important to define the required contents of NeXus files that contain data from particular classes of neutron, X-ray, or muon instrument.