RNTuple Validation Suite

The RNTuple Validation Suite provides conformance tests for the RNTuple Binary Format Specification. The goal is to cover all parts of the specification with implications on the format. It can be used to validate both writer and reader implementations of the RNTuple specification. To that end, each test comes with a written description of the schema and the expected data. Reference files for version 1.0.0 can be found under the GitHub Release.

Test Categories

Tests in the RNTuple Validation Suite are organized into (nested) categories. This is mirrored by the hierarchical directory layout in the repository. For example, the types directory contains tests related to type support in the RNTuple specification. It has subdirectories for tests concerning fundamental types and C++ types, for example std::vector. More tests are planned in the future, please consult the list of issues in the GitHub repository.

Reference Implementation

This repository also contains a reference implementation with ROOT macros. They target the stable API released with ROOT v6.36 and should work on newer versions. Compatibility with ROOT v6.34 can be tested with version v1.0 of the RNTuple Validation Suite. It was the first official version of the RNTuple on-disk binary format, but the API was not yet finalized and all classes were in the ROOT::Experimental namespace.

How to Run

For each test, we implement a write.C and read.C macro in the corresponding subdirectory. The write.C macro produces a .root file with the contents as described in the README of each test subdirectory. The read.C macro produces a .json file with a human-readable representation of the data in the .root file. They can be run individually or all at once with make using the top-level Makefile. The latter is also exercised by a GitHub Actions Workflow: The job also uploads the produced set of .root and .json files, which can be downloaded from the Summary page.

Running the complete Validation Suite with make creates three folders:

• dict: contains the produced dictionaries (.so, .pcm and .cxx files)
• write: contains the produced .root files
• read: contains the produced .json files

Each operation can also be run individually, i.e. make dict, make write and make read.

To store results separately per version, subdirectories can be defined via the dict_dir, write_dir or read_dir arguments. Note that read_dir creates a subdirectory inside the folder named by write_dir within read. For example:

make dict_dir=6.38.00 write_dir=6.38.00 read_dir=6.38.00

produces the following structure:

dict/
├── 6.38.00/
    ├── .so
    ├── .pcm
    └── .cxx
write/
├── 6.38.00/
    └── .root
read/
├── 6.38.00/     <- version that wrote the .root files (write_dir)
    └── 6.38.00/ <- version that read them and produced the .json files (read_dir)
        └── .json

The two-level hierarchy in read reflects the cross-validation between ROOT versions: the outer directory identifies the version whose .root files were used as input, and the inner directory identifies the version that read them and produced the .json output.