Introduction to HDF5 
HDF5 Reference Manual 
Other HDF5 documents and links 
And in this document, the HDF5 User's Guide:     Files  
Datasets   Data Types   Dataspaces   Groups   References  
Attributes   Property Lists   Error Handling   Filters   Caching  
Chunking   Debugging   Environment   DDL   Ragged Arrays  

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;
   }
}
}

Introduction to HDF5 
HDF5 Reference Manual 
Other HDF5 documents and links 
And in this document, the HDF5 User's Guide:     Files  
Datasets   Data Types   Dataspaces   Groups   References  
Attributes   Property Lists   Error Handling   Filters   Caching  
Chunking   Debugging   Environment   DDL   Ragged Arrays  

HDF Help Desk
Last modified: 30 October 1998