3.2.1.1. NXDL Elements and Field Types¶

The documentation in this section has been obtained directly from the NXDL Schema file: nxdl.xsd. First, the basic elements are defined in alphabetical order. XML attributes of an element are indicated immediately following the element, such as XML attribute name. Then, the common data types used within the NXDL specification are defined. Pay particular attention to the rules for validItemName and validNXClassName.

NXDL Elements¶

attribute¶

An NXDL attribute can only be a child of an NXDL definition, NXDL field, NXDL fieldAttributes or NXDL group. It is used to define NeXus attributes to be used and their data types and possibly an enumeration of allowed values.

For more details, see: attributeType

fig.nxdl/nxdl_attribute — Graphical representation of the NXDL `attribute` element¶

choice¶

An NXDL choice is used when a named NeXus group might take one of several possible NeXus base classes. Logically, it must contain at least two NXDL groups.

For more details, see: choiceType

definition¶

An NXDL definition can only be used at the root level of an NXDL specification. Note: Due to the large number of XML attributes of the NXDL definition, they have been omitted from the figure below.

For more details, see: definition, definitionType, and definitionTypeAttr

fig.nxdl/nxdl_definition — Graphical representation of the NXDL `definition` element¶

dimensions¶

NXDL dimensions describe the shape of an array. It is used only as a child of an NXDL field.

For more details, see: dimensionsType

fig.nxdl/nxdl_dimensions — Graphical representation of the NXDL `dimensions` element¶

doc¶

An NXDL doc can be a child of most NXDL elements. In most cases, the text of the NXDL doc will also become part of the NeXus manual.

element:: {any}:

In documentation, it may be useful to use an element that is not directly specified by the NXDL language. The any element here says that one can use any element at all in an NXDL doc and NXDL will not process it but pass it through.

For more details, see: docType

fig.nxdl/nxdl_doc — Graphical representation of the NXDL `doc` element¶

enumeration¶

An NXDL enumeration can only be a child of an NXDL field or NXDL attribute. It is used to restrict the available choices to a predefined list, such as to control varieties in spelling of a controversial word (such as metre vs. meter).

For more details, see: enumerationType

fig.nxdl/nxdl_enumeration — Graphical representation of the NXDL `enumeration` element¶

field¶

The NXDL field defines a NeXus field, which describes content fields. Many different XML attributes are available to further define the NXDL field. Some of the XML attributes are not allowed to be used together (such as axes and axis); see the documentation of each for details. It is used only as a child of an NXDL group.

For more details, see: fieldType

fig.nxdl/nxdl_field — Graphical representation of the NXDL `field` element¶

fieldAttributes¶

An NXDL fieldAttributes can only be a child of an NXDL definition or NXDL group. It defines NeXus attributes that any field directly in the class (in an NXDL definition) or in the NeXus group (in an NXDL group) may have, whether or not that class or NeXus group defines the field.

For more details, see: fieldAttributesType

group¶

An NXDL group can only be a child of an NXDL definition or NXDL group. It defines a NeXus group, which describes content groups: levels of organization in a NeXus data file, similar to subdirectories in a file directory tree.

For more details, see: groupType

fig.nxdl/nxdl_group — Graphical representation of the NXDL `group` element¶

link¶

An NXDL link can only be a child of an NXDL definition or NXDL group. It defines a NeXus link: a NeXus item that names another NeXus field or group, its target. It describes a content field or group with the same shared content as one that its target describes; one of the two is a content link to the other, or both are content links to the same target.

For more details, see: linkType

fig.nxdl/nxdl_link — Graphical representation of the NXDL `link` element¶

symbols¶

NXDL symbols can only be a child of an NXDL definition. It defines the array index symbols to be used when defining arrays as NXDL fields with common dimensions and lengths.

For more details, see: symbolsType

fig.nxdl/nxdl_symbols — Graphical representation of the NXDL `symbols` element¶

NXDL Field Types (internal)¶

Field types that define the NXDL language are described here. These data types are defined in the XSD Schema (nxdl.xsd) and are used in various parts of the Schema to define common structures or to simplify a complicated entry. While the data types are not intended for use in NXDL specifications, they define structures that may be used in NXDL specifications.

attributeType¶

Any new NeXus group or field may expect or require some common NeXus attributes.

(This complex type is used internally in the NXDL schema to declare elements and XML attributes to be used in NXDL files.)

XML attributes of attributeType¶

XML attribute name¶

Name of the NeXus attribute (unique among the NeXus attributes of its NeXus group or field).

XML attribute optional¶

Is this NeXus attribute optional (if true) or required (if false)?

XML attribute recommended¶

A synonym for optional, but the NeXus attribute that this NXDL attribute defines is recommended.

XML attribute type¶

Data type of the NeXus attribute, such as NX_CHAR.

Elements of attributeType¶

dimensions¶

dimensions of the NeXus attribute, when its values are arrays

doc¶

Description of this NXDL attribute. This documentation will go into the manual.

enumeration¶

An enumeration specifies the values to be used.

groupAttributeType¶

An NXDL attribute of an NXDL group or NXDL definition: an attributeType that may also have the XML attribute valueFrom.

(This complex type is used internally in the NXDL schema to declare elements and XML attributes to be used in NXDL files.)

XML attribute valueFrom¶

The value of this NeXus attribute is not fixed but comes from the NeXus group it belongs to (see valueFromType). Cannot be combined with an NXDL enumeration.

definition¶

An NXDL definition is the element at the root of every NXDL specification; it defines a NeXus class. It may only appear at the root of an NXDL file and must only appear once for the NXDL to be well-formed.

definitionType¶

A definition is the root element of every NXDL definition. It may only appear at the root of an NXDL file and must only appear once for the NXDL to be well-formed.

The definitionType declares the XML attributes of the NXDL definition and the NXDL docs, attributes, fields and groups that will be used as its children. Could contain these elements:

attribute
doc
field
fieldAttributes
group
link

Unlike fieldType and linkType, definitionType does not extend the basicComponent complex type. (The definitionType complex type is used internally in the NXDL schema to declare elements and XML attributes to be used in NXDL files.)

Note that the first line of text in an NXDL doc in an NXDL definition is used as a summary in the manual. Follow the pattern as shown in the base class NXDL files.

XML attributes of definitionType¶

XML attribute category¶

NXDL base definitions define the NeXus items to use for these components. All NeXus items of a base class are optional, except the NeXus attribute @NX_class of a NeXus group (see NXobject). NXDL application definitions define what is required for a scientific interest. All NeXus items of an application definition are required, unless their XML attributes say otherwise. NXDL contributed definitions may be considered either base or applications. Contributed definitions must indicate their intended use, either as a base class or as an application definition.

XML attribute extends¶

The XML attribute extends allows this definition to subclass from another NeXus class, otherwise extends="NXobject" should be used.

XML attribute ignoreExtraAttributes¶

Only validate known content attributes; do not warn about unknowns. The XML attribute ignoreExtraAttributes is a flag to the process of validating NeXus data files. By setting ignoreExtraAttributes="true", presence of any content attributes that no NeXus attribute describes, in a content group of this class, will not generate warnings during validation. Normally, validation will check all the content attributes against the NeXus items of the base classes and application definitions that describe them. Any content that no NeXus item describes will generate a warning message.

The XML attribute ignoreExtraAttributes should be used sparingly!

XML attribute ignoreExtraFields¶

Only validate known content fields; do not warn about unknowns. The XML attribute ignoreExtraFields is a flag to the process of validating NeXus data files. By setting ignoreExtraFields="true", presence of any content fields that no NeXus field describes, in a content group of this class, will not generate warnings during validation. Normally, validation will check all the content fields against the NeXus items of the base classes and application definitions that describe them. Any content that no NeXus item describes will generate a warning message.

The XML attribute ignoreExtraFields should be used sparingly!

XML attribute ignoreExtraGroups¶

Only validate known content groups; do not warn about unknowns. The XML attribute ignoreExtraGroups is a flag to the process of validating NeXus data files. By setting ignoreExtraGroups="true", presence of any content groups that no NeXus group describes, in a content group of this class, will not generate warnings during validation. Normally, validation will check all the content groups against the NeXus items of the base classes and application definitions that describe them. Any content that no NeXus item describes will generate a warning message.

The XML attribute ignoreExtraGroups should be used sparingly!

XML attribute name¶

The name of the NeXus class that this NXDL definition defines; also the NXDL file name without the file extension (case sensitive). The name must be unique amongst all the NeXus base class, application, and contributed definitions. For the class to be adopted by the NIAC, the first two letters must be “NX” (in uppercase). Any other use must not begin with “NX” in any combination of upper or lower case.

XML attribute restricts¶

The XML attribute restricts is a flag to the data validation. When restricts="1", any non-standard component found (and checked for validity against this NXDL specification) in a NeXus data file will be flagged as an error. If the XML attribute restricts is not present, any such situations will produce a warning.

XML attribute svnid¶

(2014-08-19: deprecated since switch to GitHub version control) The identifier string from the subversion revision control system. This reports the time stamp and the revision number of this file.

XML attribute type¶

Must be type="group"

Elements of definitionType¶

fieldAttributes¶

Defines NeXus attributes that any field directly in this class may have, whether or not the class defines that field. Like the other NeXus items of a class, they are inherited by the classes that extend it.

symbols¶

Use a symbols list to define each of the mnemonics that represent the length of each dimension in a vector or array.

Model groups of definitionType¶

In addition to an optional symbols list, an NXDL definition may contain any of the elements allowed in an NXDL group.

definitionTypeAttr¶

Prescribes the allowed values for the XML attribute type of the NXDL definition. (This data type is used internally in the NXDL schema to define a data type.)

The value may be any one from this list only:

group
definition

dimensionsType¶

dimensions of a NeXus field or attribute (This complex type is used internally in the NXDL schema to declare elements and XML attributes to be used in NXDL files.)

XML attributes of dimensionsType¶

XML attribute rank¶

Rank (number of dimensions) of the data structure.

Value could be either an unsigned integer or a symbol as defined in the symbol table of the NXDL file.

For example: a[5] has rank="1" while b[8,5,6,4] has rank="4". See https://en.wikipedia.org/wiki/Rank_%28computer_programming%29 for more details.

Elements of dimensionsType¶

dim¶

Specify the parameters for each index of the NXDL dimensions with a dim element. The number of dim entries should be equal to the rank of the array. For example, these terms describe a 2-D array with lengths (nsurf, nwl):
1
The XML attribute value is used by NXDL and also by the NeXus data file validation tools to associate and coordinate the same array length across multiple NeXus fields in a group.

XML attribute incr¶

Deprecated: 2016-11-23 telco (https://github.com/nexusformat/definitions/issues/330)

The dimension specification is related to the refindex axis within the NeXus field ref by an offset of incr. Requires the XML attributes ref and refindex to be present.

XML attribute index¶

Number or symbol indicating which axis (subscript) is being described, ranging from 1 up to rank (rank of the data structure). For example, given an array A[i,j,k], index="1" would refer to the i axis (subscript).

XML attribute ref¶

Deprecated: 2016-11-23 telco (https://github.com/nexusformat/definitions/issues/330)

The dimension specification is the same as that of the NeXus field the XML attribute ref names, specified either by a relative path, such as polar_angle or ../Qvec or absolute class path, such as /NXentry/NXinstrument/NXdetector/polar_angle.

XML attribute refindex¶

Deprecated: 2016-11-23 telco (https://github.com/nexusformat/definitions/issues/330)

The dimension specification is the same as the refindex axis within the NeXus field ref. Requires the XML attribute ref to be present.

XML attribute required¶

This dimension is required (true: default) or not required (false).

The default value is true.

When required="false" is specified, all subsequent <dim nodes (with higher index value) must also have required="false".

XML attribute value¶

Integer length (number of values), or mnemonic symbol representing the length of this axis.

doc¶

Documentation might be necessary to describe how the parts of the NXDL dimensions are to be used.

docType¶

NXDL allows for documentation on most elements using an NXDL doc. The documentation is useful in several contexts. The documentation will be rendered in the manual. Documentation, is provided as tooltips by some XML editors when editing NXDL files. Simple documentation can be typed directly in the NXDL:

Descriptive name of sample

This is suitable for basic descriptions that do not need extra formatting such as a bullet-list or a table. For more advanced control, use the rules of restructured text, such as in the NXdetector specification. Refer to examples in the NeXus base class NXDL files such as NXdata.

Could contain these elements:

any

(This complex type is used internally in the NXDL schema to declare elements and XML attributes to be used in NXDL files.)

Note: For documentation of NXDL definitions, the first line of text in a doc is used as a summary in the manual. Follow the pattern as shown in the base class NXDL files.

enumerationType¶

An NXDL enumeration restricts the values allowed for a NeXus field or attribute. Each value is specified using an item element, such as: <item value="Synchrotron X-ray Source" />. Could contain these elements:

doc
item

(This complex type is used internally in the NXDL schema to declare elements and XML attributes to be used in NXDL files.)

source operating mode

        for storage rings
        for storage rings

Enumerations can be closed or open. A closed enumeration is one where the list of values are the only ones allowed for a specification. An open enumeration is one where the list of values is incomplete and additional values other than those listed are allowed. Open enumerations should be used sparingly as the designer of the enumeration should try to find all possible values for a given NeXus field or attribute.

In case an open enumeration is used and the data provider wants to declare that the provided value deliberately not from the given list of values, the data provider should,

for content fields, set the content attribute @custom=True.
for content attributes, set an additional content attribute @my_attribute_custom=True, where my_attribute is the name of the content attribute with the open enumeration.

Such content attributes can be used deliberately to suppress warnings in NeXus validators.

XML attributes of enumerationType¶

XML attribute open¶

Is this an open enumeration? An open enumeration allows additional values not listed.

Elements of enumerationType¶

item¶

One of the prescribed values. Use the XML attribute value.

Defines the value of one selection for an enumeration list. Each enumerated item must have a value (it cannot have an empty text node).

XML attribute value¶

The value of value of an enumItem is defined as an XML attribute rather than a name.

doc¶

Individual items can be documented but this documentation might not be printed in the NeXus Reference Guide.

fieldType¶

An NXDL field defines a NeXus field of the class or NeXus group being defined. That NeXus field describes content fields, which are stored as an HDF4 SDS (Scientific Data Set) or an HDF5 dataset. Could contain these elements:

attribute
dimensions
doc
enumeration

The XML attributes long_name, signal, axes, axis, primary, interpretation, stride and data_offset of an NXDL field give the value of the NeXus attribute with that name of the NeXus field, for example signal="1"; their declarations below constrain only the NXDL file. The XML attribute units gives the units category or an example of the units, not the value of @units. Other NeXus attributes of the NeXus field are defined with NXDL attributes.

Note that an NXDL field also includes the declarations of the basicComponent complex type. (The fieldType complex type is used internally in the NXDL schema to declare elements and XML attributes to be used in NXDL files.)

XML attribute axes¶

NOTE: Use of the XML attribute axes for an NXDL field is discouraged. It is for legacy support. You should use the NeXus attribute @axes of the NeXus group (such as in NXdata) instead.

This XML attribute contains a string array that defines the independent NeXus fields used in the default plot for all of the dimensions of the signal field (the signal field is the NeXus field in this NeXus group that is named by the NeXus attribute @signal of this NeXus group).

When there is only one item in the string array, it is acceptable to set the value to the one string. In such case, it is not necessary to make it an array of one string.

Presence of the XML attribute axes means this NeXus field is an ordinate.

XML attribute axis¶

NOTE: Use of this XML attribute is discouraged. It is for legacy support. You should use the NeXus attribute @axes of the NeXus group (such as in NXdata) instead.

Presence of the XML attribute axis means this NeXus field is an abscissa.

The XML attribute value is an integer indicating this NeXus field as an axis that is part of the data set. The data set is the NeXus field in the same NeXus group whose NeXus attribute @signal is 1. The value can range from 1 up to the number of independent axes (abscissae) in the data set.

A value of axis="1" indicates that this NeXus field contains the data for the first independent axis. For example, the X axis in an XY data set.

A value of axis=2 indicates that this NeXus field contains the data for the second independent axis. For example, the Y axis in a 2-D data set.

A value of axis=3 indicates that this NeXus field contains the data for the third independent axis. For example, the Z axis in a 3-D data set.

An NXDL field with an XML attribute axis should not have an XML attribute signal.

XML attribute data_offset¶

Deprecated: not used by any NeXus definition; NXobject defines the NeXus attribute @data_offset of every field. The declaration of this XML attribute constrains only the NXDL file: its type and default never applied to that NeXus attribute.

The XML attributes stride and data_offset are used together to index the array of data items in a multi-dimensional array. They may be used as an alternative method to address a data array that is not stored in the standard NeXus method of “C” order.

The XML attribute data_offset determines the starting coordinates of the data array for each dimension.

See https://support.hdfgroup.org/HDF5/Tutor/phypereg.html or 4. Dataspace Selection Operations in https://portal.hdfgroup.org/display/HDF5/Dataspaces

The XML attribute data_offset contains a comma-separated list of integers. (In addition to the required comma delimiter, whitespace is also allowed to improve readability.) The number of items in the list is equal to the rank of the data being stored. The value of each item is the offset in the array of the first data item of that subscript of the array.

XML attribute interpretation¶

Deprecated: not used by any NeXus definition; NXobject defines the NeXus attribute @interpretation of every field. The declaration of this XML attribute constrains only the NXDL file: its type and default never applied to that NeXus attribute.

This instructs the consumer of the data what the last dimensions of the data are. It allows plotting software to work out the natural way of displaying the data.

For example a single-element, energy-resolving, fluorescence detector with 512 bins should have interpretation="spectrum". If the detector is scanned over a 512 x 512 spatial grid, the data reported will be of dimensions: 512 x 512 x 512. In this example, the initial plotting representation should default to data of the same dimensions of a 512 x 512 pixel image detector where the images where taken at 512 different pressure values.

In simple terms, the allowed values mean:

scalar = 0-D data to be plotted

scaler = DEPRECATED, use scalar

spectrum = 1-D data to be plotted

image = 2-D data to be plotted

rgb-image = 3-D data to be plotted

rgba-image = 3-D data to be plotted

hsl-image = 3-D data to be plotted

hsla-image = 3-D data to be plotted

cmyk-image = 3-D data to be plotted

vertex = 3-D data to be plotted

XML attribute long_name¶

Deprecated: not used by any NeXus definition; NXobject defines the NeXus attribute @long_name of every field. The declaration of this XML attribute constrains only the NXDL file: its type and default never applied to that NeXus attribute.

Descriptive name for this NeXus field (may include whitespace and engineering units). Often, the long_name (when defined) will be used as the axis label on a plot.

XML attribute maxOccurs¶

Maximum occurrence of the NeXus field that this NXDL field defines. Its value is confined to zero or greater. Must be greater than or equal to the value for the XML attribute minOccurs. A value of “unbounded” is allowed.

XML attribute minOccurs¶

Minimum occurrence of the NeXus field that this NXDL field defines. Its value is confined to zero or greater. Must be less than or equal to the value for the XML attribute maxOccurs.

XML attribute optional¶

A value of “true” is equivalent to minOccurs=0 while a value of “false” is equivalent to minOccurs>0.

XML attribute primary¶

Integer indicating the priority of selection of this NeXus field for plotting (or visualization) as an axis.

Presence of the XML attribute primary means this NeXus field is an abscissa.

XML attribute recommended¶

A synonym for optional, but the NeXus field that this NXDL field defines is recommended.

XML attribute signal¶

Presence of the XML attribute signal means this NeXus field is an ordinate.

Integer marking this NeXus field as plottable data (ordinates). The value indicates the priority of selection or interest. Some facilities only use signal=1 while others use signal=2 to indicate plottable data of secondary interest. Higher numbers are possible but not common and interpretation is not standard.

An NXDL field with an XML attribute signal should not have an XML attribute axis.

XML attribute stride¶

Deprecated: not used by any NeXus definition; NXobject defines the NeXus attribute @stride of every field. The declaration of this XML attribute constrains only the NXDL file: its type and default never applied to that NeXus attribute.

The XML attributes stride and data_offset are used together to index the array of data items in a multi-dimensional array. They may be used as an alternative method to address a data array that is not stored in the standard NeXus method of “C” order.

The stride list chooses array locations from the data array with each value in the stride list determining how many elements to move in each dimension. Setting a value in the stride array to 1 moves to each element in that dimension of the data array, while setting a value of 2 in a location in the stride array moves to every other element in that dimension of the data array. A value in the stride list may be positive to move forward or negative to step backward. A value of zero will not step (and is of no particular use).

See https://support.hdfgroup.org/HDF5/Tutor/phypereg.html or 4. Dataspace Selection Operations in https://portal.hdfgroup.org/display/HDF5/Dataspaces

The XML attribute stride contains a comma-separated list of integers. (In addition to the required comma delimiter, whitespace is also allowed to improve readability.) The number of items in the list is equal to the rank of the data being stored. The value of each item is the spacing of the data items in that subscript of the array.

XML attribute type¶

Defines the data type of the NeXus field as allowed by NeXus.

See here and elsewhere for the complete list of allowed types.

XML attribute units¶

String describing the engineering units. The string should be appropriate for the value.

If a unit is not provided by the list of NeXus unit categories, instead of providing a category, an NXDL field can include an example of the units directly.

The example does not constrain the scale of the units. For example, if the unit is eV/mm, the user could specify in a data file eV/cm, or any other unit that is convertible to the example given.

It is recommended that users and application developers check if their units and their unit examples adhere to the UDUNITS standard. [1]

Conformance is not validated at this time.

[1]
https://www.unidata.ucar.edu/software/udunits/

attribute¶

NeXus attributes to be used with this NeXus field

dimensions¶

dimensions of the NeXus field

enumeration¶

An NXDL field can specify which values are to be used

fieldAttributesType¶

An NXDL fieldAttributes defines NeXus attributes that any field directly in a class or NeXus group may have, whether or not that class or NeXus group defines the field. Fields in nested NeXus groups are not affected.

As a child of the NXDL definition of a base class, it applies to every field directly in that class, and is inherited by the classes that extend it (see NXobject). No NeXus group has an application definition as its type, so an application definition may not have fieldAttributes as a direct child (checked by the repository’s Python syntax check, not by nxdl.xsd).
As a child of an NXDL group, it applies to every field directly in the NeXus group that this NXDL group defines, in addition to the fieldAttributes of the type of that NeXus group.

An NXDL attribute of an NXDL field always takes precedence over one with the same name in fieldAttributes. When several fieldAttributes contain an NXDL attribute with the same name, the one closest to the field takes precedence: the enclosing NXDL group, then the same NXDL group in the application definitions that its NXDL definition extends (closest first), then the NXDL definition of the type of its NeXus group, then the classes that class extends. The NXDL attribute that takes precedence replaces the others, as a subclass overrides an inherited NeXus item (see Inheritance in NeXus). Could contain these elements:

attribute
doc

(This complex type is used internally in the NXDL schema to declare elements and XML attributes to be used in NXDL files.)

Elements of fieldAttributesType¶

attribute¶

An NXDL attribute that defines a NeXus attribute that any field directly in the class or NeXus group that fieldAttributes applies to may have.

doc¶

Describe these NeXus attributes. This documentation will go into the manual.

choiceType¶

An NXDL choice is used when a named NeXus group might be of one of several possible NeXus base classes. Logically, it must contain at least two NXDL groups.

XML attributes of choiceType¶

XML attribute name¶

The name of the NeXus group that the selected child NXDL group defines. None of the child NXDL groups should have an XML attribute name.

Elements of choiceType¶

group¶

An NXDL group whose type is a base class that could be used here. The NXDL group will take the XML attribute name of the parent NXDL choice so do not specify the XML attribute name of the NXDL group here.

groupType¶

An NXDL group defines a NeXus group of the class or NeXus group being defined; its type is an existing class. Could contain these elements:

attribute
doc
field
fieldAttributes
group
link

Unlike fieldType and linkType, groupType does not extend the basicComponent complex type: its XML attribute name is optional. (The groupType complex type is used internally in the NXDL schema to declare elements and XML attributes to be used in NXDL files.)

XML attributes of groupType¶

XML attribute maxOccurs¶

Maximum occurrence of the NeXus group that this NXDL group defines. Note each NXDL group must have an XML attribute name that is unique among all NXDL groups and NXDL fields within a common parent element.

XML attribute minOccurs¶

Minimum occurrence of the NeXus group that this NXDL group defines. Note each NXDL group must have an XML attribute name that is unique among all NXDL groups and NXDL fields within a common parent element.

XML attribute name¶

A particular scientific application may expect a name of a NeXus group. It is helpful but not required to specify the XML attribute name in the NXDL file. It is suggested to always specify a name to avoid ambiguity. It is also suggested to derive the name from the type, using an additional number suffix as necessary. For example, consider a data file with only one NXentry. The suggested default name would be entry. For a data file with two or more NXentry groups, the suggested names would be entry1, entry2, … Alternatively, a scientific application such as small-angle scattering might require a different naming procedure; two different NXaperture groups might be given the names beam_defining_slit and scatter_slit.

XML attribute optional¶

A value of “true” is equivalent to minOccurs=0 while a value of “false” is equivalent to minOccurs>0.

XML attribute recommended¶

A synonym for optional, but the NeXus group that this NXDL group defines is recommended.

XML attribute type¶

The XML attribute type must contain the name of a NeXus base class (including contributed base classes): the type of the NeXus group that this NXDL group defines. It may not be an application definition (checked by the repository’s Python syntax check, not by nxdl.xsd).

Elements of groupType¶

fieldAttributes¶

Defines NeXus attributes that any field directly in the NeXus group this NXDL group defines may have, whether or not that NeXus group defines the field.

Model groups of groupType¶

An NXDL group may be contained within another NXDL group.

linkType¶

An NXDL link defines a NeXus link: a NeXus item that names another NeXus field or group, its target. It describes a content field or group with the same shared content as one that its target describes; one of the two is a content link to the other, or both are content links to the same target. Use it to avoid needless repetition of information.

In a data file this requires that

the content group described by the enclosing NeXus group contains a content field or group whose name is the value of the XML attribute name;
it and a content field or group that the target describes have the same shared content;
one of the two is a content link to the other, or both are content links to the same target: the content attribute @target (see NXobject) of one is the path of the other, or both have the same @target.

Either of the two may be the content link.

An NXDL link defines no type, units, dimensions or NeXus attributes of its own: those of its target apply. An NXDL link has no occurrence XML attributes, so the NeXus link it defines is required in an application definition.

A content field or group may be a content link in a data file without a NeXus link describing it. (This complex type is used internally in the NXDL schema to declare elements and XML attributes to be used in NXDL files.)

XML attribute napimount¶

Deprecated: not used by any NeXus definition. URL of an HDF5 group in another file (see HDF5 external links). NXDL enforces nothing about it.

XML attribute target¶

Class path of the target: the NeXus field or group whose content fields or groups must have the same shared content (see validTargetName). It is written with class names, so it names a NeXus item, not a path in a data file.

NXDL does not require that the value of the content attribute @target matches this path.

This XML attribute is not the content attribute @target of a content field or group in a data file (see NXobject).

For example, an NXDL group of type NXdata that contains:
<link name="polar_angle" target="/NXentry/NXinstrument/NXdetector/polar_angle"/>
is satisfied by this data, where both content fields have the same shared content:
entry:NXentry
        data:NXdata
                polar_angle:NX_NUMBER
                        @target="/entry/instrument/detector/polar_angle"
        instrument:NXinstrument
                detector:NXdetector
                        polar_angle:NX_NUMBER
                                @target="/entry/instrument/detector/polar_angle"

symbolsType¶

Each symbol element has an XML attribute name and optional documentation. Please provide documentation that indicates what each symbol represents. For example:

number of reflecting surfaces
number of wavelengths

Elements of symbolsType¶

doc¶

Describe the purpose of this list of symbols. This documentation will go into the manual.

symbol¶

When multiple NeXus fields share the same dimensions, such as the dimension scales associated with plottable data in an NXdata group, the length of each dimension written in a NeXus data file should be something that can be tested by the data file validation process.

XML attribute name¶

Mnemonic variable name for this array index symbol.

doc¶

Describe the purpose of the parent symbol element. This documentation will go into the manual.

basicComponent¶

A basicComponent declares the allowed name format and XML attributes common to all NXDL fields and NXDL groups. (This complex type is used internally in the NXDL schema to declare elements and XML attributes to be used in NXDL files.)

XML attributes of basicComponent¶

XML attribute name¶

The XML attribute name is the identifier string for this entity. It is required that name must be unique within the enclosing NXDL group. The name must match the regular expression defined by validItemName. (Historical note: Originally, the rule (validItemName) was defined to allow only names that can be represented as valid variable names in most computer languages. )

Elements of basicComponent¶

doc¶

Describe this basicComponent and its use. This documentation will go into the manual.

validItemName¶

Used for allowed values of the XML attribute name of elements: the names of NeXus groups, fields and attributes. Note: No - characters (among others) are allowed and you cannot start or end with a period (.). HDF4 had a 64 character limit on names (possibly including NULL) and the NAPI enforces this via the NX_MAXNAMELEN variable with a 64 character limit (which may be 63 on a practical basis if one considers a NULL terminating byte). (This data type is used internally in the NXDL schema to define a data type.) NOTE: In some languages, it may be necessary to add a ^ at the start and a $ at the end of the regular expression to constrain the match to an entire line.

The value may be any xs:token that also matches the regular expression:

[a-zA-Z0-9_]([a-zA-Z0-9_.]*[a-zA-Z0-9_])?

validNXClassName¶

Used for allowed names of NX class types (e.g. NXdetector). Note this is not the name of a NeXus group (e.g. bank1), which is covered by validItemName. (This data type is used internally in the NXDL schema to define a data type.)

The value may be any nx:validItemName that also matches the regular expression:

NX.+

validTargetName¶

An absolute class path naming a NeXus field or group, used as the XML attribute target of an NXDL link. Each /-separated segment is the class of a NeXus group (NXcrystal), the name and class of a NeXus group (analyzer:NXcrystal), or the name of a NeXus field (ef):

/NXentry/NXinstrument/analyzer:NXcrystal/ef
/NXentry/NXinstrument/monochromator:NXcrystal/ei
/NX_other

Because it is written with class names, it names a NeXus item, not a path in a data file. Currently it must be an absolute path; we may want to consider allowing “..” (parent of directory) at some point. Must also consider use of the XML attribute name in resolving the targets of NeXus links. (This data type is used internally in the NXDL schema to define a data type.)

From the HDF5 documentation:

Note that relative path names in HDF5 do not employ the ``../`` notation, the UNIX notation indicating a parent directory, to indicate a parent group.

Thus, if we only consider the case of [name:]type, the matching regular expression syntax is written: /[a-zA-Z_][\w_]*(:[a-zA-Z_][\w_]*)?)+. Note that HDF5 also permits relative path names, such as: GroupA/GroupB/Dataset1 but this is not permitted in the matching regular expression.

The value may be any xs:token that also matches the regular expression:

(/[a-zA-Z_][\w_]*(:[a-zA-Z_][\w_]*)?)+

nonNegativeUnbounded¶

A nonNegativeUnbounded allows values including all positive integers, zero, and the string unbounded. (This data type is used internally in the NXDL schema to define a data type.)

valueFromType¶

Where the value of a NeXus attribute of a NeXus group comes from, as given by the XML attribute valueFrom of the NXDL attribute that defines it.

(This simple type is used internally in the NXDL schema.)

The value may be any one from this list only:

class

The type of the NeXus group that the NeXus attribute belongs to, the name of a class: the XML attribute type of the NXDL group that defines that NeXus group, or the XML attribute name of the NXDL definition, for a NeXus attribute that the class itself has. For a NeXus attribute inherited from another class, such as NXobject, it is the type of that NeXus group, not the class that defines the NeXus attribute.

The xs:string data type

The xs:string data type can contain characters, line feeds, carriage returns, and tab characters. See https://www.w3schools.com/xml/schema_dtypes_string.asp for more details.

The xs:token data type

The xs:string data type is derived from the xs:string data type.

The xs:token data type also contains characters, but the XML processor will remove line feeds, carriage returns, tabs, leading and trailing spaces, and multiple spaces. See https://www.w3schools.com/xml/schema_dtypes_string.asp for more details.