Skip to content

SDDL - Simple Data Description Language

SDDL is a domain-specific language for describing binary file formats. It enables you to formally specify the structure of binary data so it can be efficiently processed by compression algorithms, transformation tools, and other downstream systems.

⚠️ Important Notice

This documentation describes SDDL version 0.6 - the target specification. This represents the design goals and intended features of SDDL, serving as a "North Star" for the project's development.

The current implementation may not yet support all features described here. For information about the current implementation status, ongoing development, and roadmap, please refer to the project's GitHub repository and community discussions.

What is SDDL?

SDDL provides a clear, readable way to describe complex binary formats while maintaining strict guarantees about parsing performance. It's designed to bridge the gap between human-readable format specifications and high-performance binary processing.

Key Features

  • Explicit and Unambiguous: No hidden defaults or implicit behaviors
  • Performance Visibility: Clear distinction between instant-parse and scan-required layouts
  • Type Safety: Rich type system with explicit endianness
  • Validation: Built-in support for format constraints and data validation
  • Flexible Layouts: Support for fixed-size, variable-size, and delimiter-based data

Quick Example

Record Header() = {
  magic: Bytes(4),
  version: Int16LE,
  flags: Int16LE
}

header: Header
expect header.magic == "DPKT"
expect header.version >= 1 and header.version <= 3

Using SDDL with AI/LLM Assistants

Want help writing SDDL specifications? We provide a specialized teaching document designed for AI assistants:

→ SDDL for LLM (v0.6) - Complete technical specification optimized for LLMs

You can provide this document to your AI assistant (ChatGPT, Claude, etc.) and ask it to help you create SDDL descriptions for your binary formats. The document contains the complete language specification in a format that LLMs can easily understand and apply.

Example prompt:

"I'm attaching the SDDL specification. Can you help me write an SDDL description for [your format name]? The format has [describe your format structure]."

This approach is particularly effective for learning SDDL syntax quickly through interactive examples, getting help with complex format descriptions that would be tedious to work through manually, validating your SDDL code against the specification, and converting existing format documentation into structured SDDL descriptions.

Getting Started

New to SDDL? Start with the Introduction & Motivation to understand why SDDL exists and how it can help you. Then follow the Getting Started guide to create your first SDDL file.

Documentation Structure

  1. Introduction & Motivation - Understanding SDDL's purpose and benefits
  2. Getting Started - Your first SDDL file
  3. Core Concepts - Types, records, and validation
  4. Understanding Instant-Parse - Performance and layout determinism
  5. Arrays and Collections - Working with repeated data
  6. Advanced Layout Control - Alignment, padding, and memory optimization
  7. Conditional & Variant Data - Handling dynamic structures
  8. Variables and Expressions - Computing derived values
  9. Real-World Formats - Complete examples
  10. Best Practices - Guidelines for effective SDDL
  11. Quick Reference - Quick lookup guide

Community and Support

  • GitHub: facebook/openzl
  • Issues: Report bugs or request features on GitHub

Version

This documentation describes SDDL version 0.6.