# DDL in BNF for HDF5

## 1. Introduction

This document contains the data description language (DDL) for an HDF5 file. The description is in Backus-Naur Form.

## 2. Explanation of Symbols

This section contains a brief explanation of the symbols used in the DDL.

        ::=                      defined as
        <tname>                  a token with the name tname
        <a> | <b>                one of <a> or <b>
        <a>opt                    zero or one occurrence of <a>
        <a>*                     zero or more occurrence of <a>
        <a>+                     one or more occurrence of <a>
        TBD                      To Be Decided

## 3. The DDL

    <file> ::= HDF5 "<file_name>" { <file_boot_block>opt <root_group> }

    <file_name> ::= <identifier>

    <file_boot_block> ::= BOOT_BLOCK { <boot_block_content> }

    <boot_block_content> ::= TBD

    <root_group> ::= GROUP "/" { <unamed_datatype>* <group_attribute>* <group_member>* }

    <unamed_datatype> ::= DATATYPE "<unamed_type_name>" { <compound_type_def>+ }

    <unamed_type_name> ::= the assigned name for unamed type is in the form of
                          #oid1:oid2, where oid1 and oid2 are the object ids of the type

    <compound_type_def> ::=  <named_scalar_type> | <named_array_type>

    <named_scalar_type> ::= <scalar_type> <field_name> ;

    <scalar_type> ::= H5T_STD_I8BE | H5T_STD_I8LE | ...

    <field_name> ::= <identifier>

    <named_array_type> ::= <scalar_type> <field_name> <dim_sizes> ;

    <dim_sizes> ::= dimension sizes in the form of [dimsize1][dimzise2]...,
                    where dimsize1, dimsize2 are integers

    <group_attribute> ::= <attribute>

    <attribute> ::= ATTRIBUTE "<attr_name>" { <datatype>
                                              <dataspace>
                                              <data>opt  }
    // <datatype> and <dataspace> must appear before <data>.

    <attr_name> ::=  <identifier>

    <datatype> ::= DATATYPE { <named_type> } |
                   DATATYPE { "<scalar_type>" }  |
                   DATATYPE { <compound_type_def>+ }

    <named_type> ::= <hardlink>

    <hardlink> ::= HARDLINK { "<abs_name>" }

    <abs_name> ::= object absolute name

    <dataspace> ::= DATASPACE { "<dataspace_name>" } |
                    DATASPACE { ARRAY <current_dims> <max_dims> } |
                    DATASPACE { OTHER <ds_definition>+ }

    <dataspace_name> ::= <identifier>

    <current_dims> ::= a list of integers in the form of (i1, i2, ... ),
                       where ik is an integer, k = 1,2,...

    <max_dims> ::= (i1, i2, ... ) where ik is an integer or H5S_UNLIMITED

    <ds_definition> ::= TBD

    <data> ::= data {TBD}

    <group_member> ::= <named_datatype> | <named_dataspace> | <group> | <dataset> |
                       <softlink>

    <named_datatype> ::= DATATYPE "<type_name>" { <compound_type_def>+ }

    <type_name> ::= "<identifier>"

    <named_dataspace> ::= DATASPACE "<dataspace_name>" { ARRAY <current_dims> <max_dims> } |
                          DATASPACE "<dataspace_name>" { OTHER <ds_definition>+ }

    <group> ::= GROUP "<group_name>" { <hardlink> } |
                GROUP "<group_name>" { <group_attribute>* <group_member>* }

    <group_name> ::= <identifier>

    <dataset> ::= DATASET "<dataset_name>" { <hardlink> } |
                  DATASET "<dataset_name>" { <datatype>
                                             <dataspace>
                                             <storagelayout>opt
                                             <compression>opt
                                             <dataset_attribute>*
                                             <data>opt  }
    // Tokens within {} can be in any order  as long as <data> and <dataset_attribute>
    // are after <datatype> and <dataspace>.

    <dataset_name> ::= <identifier>

    <storagelayout> :: = STORAGELAYOUT <contiguous_layout>  |
                         STORAGELAYOUT <chunked_layout>  |
                         STORAGELAYOUT <compact_layout>  |
                         STORAGELAYOUT <external_layout>

    <contiguous_layout> ::= {CONTIGUOUS}    // default

    <chunked_layout> ::=  {CHUNKED <dims> }

    <dims> ::= (i1, i2, ... ), ik is an integer, k = 1,2,...

    <compact_layout> ::= TBD

    <external_layout> ::= {EXTERNAL <external_file>+ }

    <external_file> ::= (<file_name> <offset> <size>)

    <offset> ::= an integer

    <size> ::= an integer

    <compression> :: = COMPRESSION { TBD }

    <dataset_attribute> ::= <attribute>

    <softlink> ::= SOFTLINK "<softlink_name>" { LINKTARGET "<target>" }

    <softlink_name> ::= <identifier>

    <target> ::= <identifier>

    <identifier> ::= string
    // character '/' should be used with care.

## 4. An Example of an HDF5 File in DDL

    HDF5 "example.h5" {
    GROUP "/" {
       DATASET "dset1" {
          DATATYPE {
             H5T_STD_I32BE int_name;
             H5T_IEEE_F32BE float_name;
             H5T_IEEE_F64BE double_name;
          }
          DATASPACE { ARRAY ( 5 ) ( 5 ) }
          DATA {{0,0,1}, {1,1,0.5}, {2,4,0.333333}, {3,9,0.25}, {4,16,0.2}}
       }
       GROUP "group1" {
          DATASET "dset2" {
             DATATYPE {
                HARDLINK { "/type1" }
             }
             DATASPACE { ARRAY ( 5 ) ( 5 ) }
             DATA {{0,0}, {1,1.1}, {2,2.2}, {3,3.3}, {4,4.4}}
          }
       }
       GROUP "group2" {
          HARDLINK { "/group1" }
       }
       SOFTLINK "slink1" {
          LINKTARGET "somevalue"
       }
       DATATYPE "type1" {
          H5T_STD_I32BE int_name;
          H5T_IEEE_F32BE float_name;
       }
    }
    }

Last modified: 28 October 1998