Huddl's schema rules
This document lists in a human readable form the rules for creating an Huddl Formation Definition (HFD) file as codified in:
The Huddl W3C schema defines:
- http://huddl.ccom.unh.edu as namespace for all the Huddl-related XML elements.
- several xs:key-type constraints to identify element or attribute values that are unique, not nullable and always present.
The Huddl Schematron document was introduced to enforce additional constraints that are not supported by the W3C schema.
The schema root and the children format elements
Each HFD file has exactly one schema as root element.
The fact that schema is the only valid root element is implemented by the Schematron constraint check_schema_is_root.
The Huddl W3C schema enforces that:
- the schema has a mandatory version attribute that is mainly used to track changes in the schema itself that can make invalid the existing HFD files.
- the schema has at least one format element.
A format element contains all the elements required to describe a given data format.
A format element has:
- one optional prolog section,
- one mandatory content section, and
- two mandatory attributes: name and scope.
In case that a schema has more than one format elements, each of them must have unique name and scope attributes (schema rules: uniqueFormatName and uniqueFormatScope).
The format prolog element
The optional prolog element contains general information (metadata) about the data format.
A prolog element has a title and several optional elements: many possible alternate titles, a document number, a reference date, the organization that maintains the format, the revision history.
The format content element
The content element provides the actual data format description. The description is split in:
- one mandatory blocks container for block elements, with key name attribute (keyBlockName),
- one mandatory streams container for stream elements, with key revID and scope attributes (keyStreamRevID and keyStreamScope), and
- one optional experimental maps container for map elements, with key name attribute (keyMapName).
Block description
The block element provides a description of a format data block (e.g., a Kongsberg EM Series datagram).
There are a variety of pre-defined common data structures that can be used (multiple times) to describe the content of a data block:
- field: the name, type and (optionally) validity range (minimum and/or maximum values) of a data field,
- array1d: a 1D array of fixed size,
- delimited1d: a 1D array delimited by a byte character,
- array2d: a 2D array of fixed size,
- vector1d: a 1D vector of size defined by a field in the containing block,
- vector2d: a 2D vector of size defined by a field in the containing block,
- substream: a substream with information about header, tail and top blocks
A block element can have other block elements nested. It is implemented by definining the nested block as a type in the blockType element.
In adjunct, additional information to the size of the data block can be optionally provided using one of the two following elements:
- pad: used to specify the required byte alignment,
- fixedlength: used to specify a fixed length for the block.
Stream description
The stream element provides a description of a format stream (e.g., a Kongsberg EM Series format release).
The stream element has the following attributes:
- the mandatory revID and scope attributes
- the optional resynch and reclen attributes
The stream element describes:
- the mandatory header element, a reference to an existing block (schematron: check_stream_header_exists) used to cluster initial fields common to all the topBlock elements (it must have a discriminator field),
- the mandatory topBlocks container for topBlock elements,
- the optional tail element, a reference to an existing block (schematron: check_stream_tail_exists) used to cluster final fields common to all the topBlock elements,
The topBlock element has three mandatory attributes:
- the refBlock that must reference to an existing defined block``(schematron: ``check_stream_topBlock_exists),
- an alias for the block when used as a topBlock (this provides also a mechanism to have the same block referenced by different topBlock elements),
- an identifier used to identify that a data block is of a given type.
For each stream, the topBlock must have an unique alias attribute.
Map description
Under development.
tags: huddl; schema; rules