JSON Schema Reference

A schema is a UTF-8 JSON file that describes the structure of a binary file format. Load it via File → Open Schema.

Top-Level Fields

{
  "version": 1,
  "endian": "little",
  "script": "parser.py",
  "tags": [ ... ],
  "definitions": { ... }
}
Field Type Required Description
version integer yes Schema format version. Must be 1.
endian string no Default byte order for the whole schema. "little" (default) or "big".
script string no Path to a Python script for additional parsing. Relative to the schema file.
tags array yes Ordered list of tag definitions to evaluate.
definitions object no Named template groups reused by array and ref tags.

Tag Fields

Each element in tags (and in each definitions array) is an object with the following fields.

name

string — Display name shown in the tag panel.

type

string — Determines how bytes are interpreted. Accepted values:

Value Description
uint8_t 1-byte unsigned integer
uint16_t 2-byte unsigned integer
uint32_t 4-byte unsigned integer
uint64_t 8-byte unsigned integer
magic Fixed byte pattern; optionally searched backward
string Fixed-length sequence of bytes decoded as text
stringz Null-terminated string; length is auto-detected
blob Raw byte range with no interpretation
array Repeating structure; requires template and count
ref Inline expansion of a definition; does not advance the cursor
eval Computes an expression and saves it as an alias; reads no bytes

length

integer or string — Number of bytes occupied by this tag.

  • Literal: "length": 4
  • Alias reference: "length": "fnLen"
  • Expression: "length": "fnLen+2" or "length": "size-8"

Operators: +, -, *, /. Left-to-right, single operation only.

Required for all types except stringz (auto-detected), array, ref, and eval.

start_offset

integer or string — Override the tag's start position in the file.

  • Literal byte offset: "start_offset": 0
  • Alias reference: "start_offset": "cdOffset"
  • Expression: "start_offset": "base+16"

When omitted, the tag begins immediately after the previous tag ends.

alias

string — Name under which the tag's value is stored for use by later tags.

Integer types (up to 8 bytes) store their numeric value. String types store their decoded text.

{ "name": "Filename length", "alias": "fnLen", "length": 2, "type": "uint16_t" }

condition

string — Skip this tag unless the condition is true. Format: alias operator value.

{ "condition": "flags & 4" }
{ "condition": "type == 1" }
{ "condition": "size > 0" }
{ "condition": "name != '.'" }

For string comparisons, wrap the value in single quotes: "name != '.'".

Supported operators:

Operator Meaning
== equal
!= not equal
> greater than
< less than
>= greater or equal
<= less or equal
& bit is set (alias & mask != 0)
!& bit is not set (alias & mask == 0)

format

string — Display format for the value in the tag panel.

Value Description
"hex" Hexadecimal
"oct" Decimal (despite the name, this is decimal display)

When omitted, the default display is used.

endian

string — Byte order for this tag. Overrides the schema-level default.

  • "little" — least significant byte first
  • "big" — most significant byte first

color

string — Highlight color as a six-digit RGB hex string (no #).

{ "color": "ff0000" }

value

string — For magic tags: expected byte sequence as a continuous hex string.

{ "type": "magic", "value": "504b0304" }

For eval tags: arithmetic expression to compute (see below).

search

string — When set to "backward", the engine scans from the end of the file toward the beginning to find the magic byte sequence. Used for structures located at variable positions near the end of a file (e.g., ZIP EOCD).

Array-Specific Fields

template

string — Name of a definition group (from definitions) to expand for each array element.

count

integer or string — Number of times to expand the template. Can be a literal integer or an alias name.

max_offset

string — Stop array iteration when the file cursor reaches or exceeds this offset. Accepts an arithmetic expression.

lookup

object — After each iteration, collect alias values into a named lookup table.

"lookup": {
  "name": "sections",
  "fields": ["sh_offset", "sh_size"]
}

The table can then be queried by subsequent tags:

  • Index: sections[idx].sh_offset
  • Range: sections[value @ sh_offset : sh_size].sh_type

Eval Tag Fields

value (eval)

string — Arithmetic expression evaluated left-to-right. Result is saved to alias. Reads no bytes.

Supported operators: +, -, *, /, &.

{ "type": "eval", "alias": "dataEnd", "value": "dataOffset+dataSize" }

Definitions

The definitions object maps names to arrays of tag definitions. These are not evaluated directly; they serve as templates for array and ref tags.

"definitions": {
  "local_file": [
    { "name": "Signature", "type": "magic", "value": "504b0304", "length": 4 },
    { "name": "Filename length", "alias": "fnLen", "length": 2, "type": "uint16_t" },
    { "name": "Filename", "length": "fnLen", "type": "string" }
  ]
}

Minimal Example

{
  "version": 1,
  "tags": [
    { "name": "Signature", "start_offset": 0, "length": 4, "type": "magic", "value": "89504e47", "format": "hex" },
    { "name": "Width",     "length": 4, "type": "uint32_t", "alias": "width",  "endian": "big" },
    { "name": "Height",    "length": 4, "type": "uint32_t", "alias": "height", "endian": "big" }
  ]
}

Full Example — gzip Member

{
  "version": 1,
  "tags": [
    { "name": "members", "type": "array", "count": 1, "template": "member" }
  ],
  "definitions": {
    "member": [
      { "name": "Signature",    "start_offset": 0, "length": 2, "type": "magic",   "value": "1f8b", "format": "hex" },
      { "name": "Method",       "length": 1, "type": "uint8_t" },
      { "name": "Flags",        "length": 1, "type": "uint8_t", "alias": "flags", "format": "hex" },
      { "name": "Timestamp",    "length": 4, "type": "uint32_t" },
      { "name": "Extra length", "length": 2, "type": "uint16_t", "alias": "xlen", "condition": "flags & 4", "color": "00aa00" },
      { "name": "Extra field",  "length": "xlen", "type": "blob", "condition": "flags & 4", "color": "00aa00" },
      { "name": "Filename",     "type": "stringz", "condition": "flags & 8",  "color": "0000aa" },
      { "name": "CRC-32",       "length": 4, "type": "uint32_t", "format": "hex", "color": "ff0000" }
    ]
  }
}
Did this page help you?