Study: Evaluate Configuration Format Options for VFD Stack Configuration

## Problem

HDF5 Virtual File Drivers (VFDs) currently require programmatic configuration through C API calls (e.g., `H5Pset_fapl_sec2()`, `H5Pset_fapl_split()`). This approach has limitations:

- No declarative configuration via files or environment variables
- VFD-specific APIs hinder portability across different VFD stacks
- Complex to configure layered VFDs (e.g., page_buffer → encryption → sec2)
- Difficult to automate in containerized/cloud environments

A text-based configuration language would enable VFD-agnostic configuration, improve usability, and address potential safety and security concerns.

## Objective

Conduct a systematic evaluation of configuration format options to determine:

1. **Should HDF5 adopt a standard configuration format?** (vs. leaving it to individual VFD developers)
2. **If yes, which format best meets HDF5's requirements?**
3. **What is the implementation strategy?** (parser, tooling, migration path)

## Top Formats to Evaluate

1. **S-Expressions** (LISP-style nested parentheses)
2. **JSON** (JavaScript Object Notation)
3. **TOON** (Token-Oriented Object Notation - https://github.com/toon-format/toon)
4. **TOML** (Tom's Obvious Minimal Language)
5. **YAML** (YAML Ain't Markup Language)
6. **XML** (Extensible Markup Language)
7. **Custom DSL** (purpose-built syntax for VFD configuration)
8. **Environment Variables** (12-factor app pattern)
9. Others

## Evaluation Criteria

Each format will be scored on weighted criteria (1-5 scale):

### Technical Feasibility (40%)
- Parser complexity (ease of implementing in C)
- Memory safety (buffer overflows, injection risks)
- Type safety (int/float/string/bool/binary distinction)
- Nested structure support (arbitrary VFD stack depth)
- Binary data handling (encryption keys, blobs)
- Schema must also be applicable with VOLs, so backward compatibility needs to be of concern.

### Usability (30%)
- Human readability (ease of hand-editing)
- Learning curve (time to learn, familiarity)
- Error messages (quality of parser diagnostics)
- Tooling support (validators, formatters, IDE support)
- Documentation quality (spec completeness, examples)

### Ecosystem & Maintenance (20%)
- Multi-language support (C, Python, Java, Fortran, R)
- Standardization (formal spec vs. ad-hoc)
- Community adoption (usage in HPC/scientific computing)
- Long-term viability (maintained 10+ years from now)
- AI readiness and LLM friendliness

### Performance (10%)
- Parse speed (µs per config)
- Token/byte efficiency (file size)
- Memory overhead (runtime parsing memory)
- Startup latency (impact on H5Fopen() time)

## Test Cases

All formats must be evaluated using these representative configurations:

1. **Simple VFD**: SEC2 with no parameters
2. **Two-level stack**: page_buffer → sec2
3. **Three-level stack**: page_buffer → encryption → sec2 (with encryption keys)
4. **Complex parameters**: subfiling VFD with 20+ configuration parameters
5. **Binary data**: encryption keys, initialization vectors
6. **Environment variable interpolation**: `${ENV:VAR_NAME}` references
7. **Error handling**: missing fields, wrong types, validation

## Decision Framework

> [!NOTE]
A forum post is required to gather diverse opinions on the matter before a final decision is made.

After evaluation, recommend one of:

### Option A: Adopt Single Standard Format
- Choose one format as official HDF5 VFD configuration standard
- Provide reference implementation in HDF5 library
- Document migration path from existing APIs

### Option B: Support Multiple Formats
- Support 2 formats (e.g., one for humans, one for machines)
- Provide parsers for both
- Auto-detect format or use explicit flag

### Option C: Recommend Without Mandating
- Recommend a format in documentation
- VFD developers free to implement their own
- Provide example parser but no official library support

### Option D: No Standardization
- Leave configuration entirely to VFD developers
- Provide best practices guidance only
- Each VFD uses its own approach

## Deliverables

1. **Evaluation Report**
- Scoring matrix with justifications for each format
- Benchmark results (parse speed, token counts, memory)
- Security assessment (known vulnerabilities, fuzzing results)
- User research summary (surveys, usability tests)

2. **Prototype Parsers**
- Working C implementations for top 2-3 formats
- Benchmark harness
- Test suite covering all test cases

3. **Recommendation**
- Clear choice of Option A/B/C/D with rationale
- Implementation roadmap (if adopting a standard)
- Migration strategy from existing APIs

## Success Criteria

- [ ] All relavent formats evaluated against defined criteria
- [ ] Benchmark data collected for all formats
- [ ] Feedback gathered from ≥10 HDF5 users
- [ ] Working parsers implemented for top 3 formats
- [ ] Security assessment completed
- [ ] Clear recommendation with evidence-based justification
- [ ] Consensus achieved from stakeholders

## Resources Needed

- Senior architect familiar with HDF5 VFD layer
- Developer for parser prototypes and benchmarks
- UX researcher for user surveys/testing
- Security reviewer for vulnerability assessment

## Related Work

- RFC: A Plugin Interface for HDF5 Virtual File Drivers (J. Smith, J. Henderson)
- RFC: VFD Configuration Language (J. Mainzer, Lifeboat LLC)

---