Language reference

Overview

Kaitai Struct is a DSL (domain-specific language), designed to describe binary data structures in human- and machine-readable way. Description of certain structure ("format") can be written once and then translated using a compiler into a source code for supported programming languages — and then used from any program in that language.

.ksy files

Kaitai Struct data structure (format) descriptions are written as simple YAML files and are usually saved using .ksy extension to differentiate them from the rest of .yaml files.

Every .ksy file MUST be a map of strings (keys) to some values. File has only one unique key on top level, in all other respects "file" on the top level represents a class, a thus can use all the keys available for class definition.

meta

meta key is a map of string to objects that defines various meta-information about the current file, assigns some default and processing directives.

Example:

meta:
  id: foo_arc
  file_extension:
    - fooarc
    - fooarcz
  endian: le
  application: Foo Archiver v1.23  

id

• Contents: a string that follows rules for all identifiers
• Purpose: identifier for a primary structure described in top-level map
• Influences: it would be converted to suit general formatting rules of a language and used as the name of class
• Mandatory: yes

file_extension

• Contents: a string or an array of strings
• Purpose: roughly identify which files can be parsed with this format by filename extension
• Influences: may be used for navigation purposes by browsing applications
• Mandatory: no

endian

• Contents: le or be
• Purpose: sets a default endianness for this file
• Influences: if set, primitive types like u4 would be treated as aliases to u4le / u4be (depending on the setting); if not set, attempt to use abbreviated types like u4 (i.e. without full endianness qualifier) will yield compile-time error.
• Mandatory: no

application

• Contents: a string
• Purpose: free-form text string that describes application that's associated with this particular format, if it's a format used by single application
• Influences: nothing
• Mandatory: no