Recipe Format

A recipe is a JSON file with the .remap extension that captures every byte-level change between an original and a modified ECU binary. It is the central data structure of the entire OpenRemap pipeline — produced by openremap cook, consumed by every validate and patch command.

Recipes are fully portable between the CLI and the API. A recipe cooked on the command line can be applied through the API and vice versa.

Format Version

The current format version is 4.3, recorded in schema_version at the top level.

The version is checked during validation and patching. A recipe with an unrecognised format version will be rejected before any instructions are read.

Version history:

Parsers MUST ignore unknown top-level fields. New fields may be added in minor versions without breaking existing consumers.

Top-level Structure

{
  "type": "recipe",
  "schema_version": "4.3",
  "source": "full_cook" | "tune_export",
  "application": "openremap-core" | "openremap-studio",
  "creator": { },
  "fingerprint": "",
  "metadata": { },
  "ecu": { },
  "statistics": { },
  "instructions": [ ]
}

creator

Human author identity. No tool fields — tool provenance is carried by application and schema_version.

"creator": {
  "name": "pinx",
  "handle": "pinx",
  "id": "",
  "created_at": "2026-06-02T14:30:00Z",
  "signature": null,
  "trust_level": "COMMUNITY"
}

fingerprint

SHA-256 hash of (offset, ob, mb) tuples sorted by offset. Used for deduplication and corruption detection — same tune produces the same fingerprint regardless of metadata. Not tamper protection on its own; will be combined with creator.signature for cryptographic verification in the future.

"fingerprint": "sha256:00f727e8abf62d384acc4420b08fe8e5477f9d004c8d3a697bbaaa08fe2149f5"

metadata

Information about the files the recipe was built from.

"metadata": {
  "name": "Stage 1 — ME7.5",
  "description": "Increased idle timing, raised rev limiter",
  "tags": ["stage1", "rev-limiter"],
  "instruction_count": 42,
  "original_file": "stock.bin",
  "modified_file": "stage1_tune.bin",
  "original_size": 524288,
  "modified_size": 524288,
  "tune_id": null
}

ecu

The identity of the ECU the recipe was built for. Every validation and patch operation checks this block against the target binary before touching a single byte.

All string fields are null when the identifier could not be extracted from the binary. New extractors added in future library versions will populate fields that were previously null without a schema change.

"ecu": {
  "manufacturer": "Bosch",
  "match_key": "me7.5__0261208592__367276",
  "ecu_family": "ME7.5",
  "ecu_variant": null,
  "software_version": "0261208592",
  "hardware_number": "0261208592",
  "calibration_id": "367276",
  "oem_part_number": "06A906032HJ",
  "platform": "VAG",
  "calibration_version": "0003",
  "serial_number": null,
  "dataset_number": null,
  "file_size": 524288,
  "sha256": "3a7bd3e2360a3f5c8d4e1b9f0a2c6d7e8b3f1a4e5c9d2b6f0e7a1c3d5e9b2f4",
  "cook_warnings": []
}

The match_key

match_key is the primary compatibility gate. It is a compound string in the form FAMILY::VERSION and is compared against the target binary's own match_key before any validation or patching begins.

How it is built depends on the ECU architecture:

If the target binary's match_key does not match the recipe's match_key, the operation is rejected immediately with a clear mismatch message. A null match_key in the recipe disables this check and falls through to byte-level validation.

cook_warnings

Non-fatal issues detected during cooking (full_cook only; always empty for tune_export):

• Identity mismatches between original and modified binaries
• Non-unique context anchors (when Force Save bypasses the uniqueness guard)
• Low-entropy context regions

These are surfaced in the UI so the user can review them before applying the recipe.

statistics

A summary of the diff. Informational only — not used during patching.

"statistics": {
  "total_changes": 42,
  "total_bytes_changed": 168,
  "percentage_changed": 0.032,
  "single_byte_changes": 10,
  "multi_byte_changes": 32,
  "largest_change_size": 8,
  "smallest_change_size": 1,
  "min_context_size": 32,
  "max_context_size": 512
}

instructions

An array of patch instructions. Each instruction describes one contiguous block of bytes that differs between the original and modified binary.

"instructions": [
  {
    "offset": 6699,
    "offset_hex": "1A2B",
    "size": 4,
    "ob": "AABBCCDD",
    "mb": "11223344",
    "ctx": "DEADBEEF112233445566778899AABBCCDDEEFF00112233445566778899AABBCC",
    "context_after": "CAFEBABE112233445566778899AABBCCDDEEFF00112233445566778899AABBCC",
    "context_size": 32,
    "ctx_entropy": 5.2,
    "ctx_unique": true,
    "ctx_expanded": false,
    "description": "Idle timing base offset",
    "flags": []
  }
]

Instruction fields

Instruction flags

Each flag is an object with:

ob and mb

All byte strings are uppercase hex with no separators. A 4-byte value is represented as 8 hex characters: "AABBCCDD".

ob (original bytes) is what the strict validator checks before patching. If the bytes at offset do not match ob exactly, the instruction fails validation and the patch is rejected.

mb (modified bytes) is what the patcher writes. The post-patch validator checks that mb is present at offset after the patch is applied.

ctx — the anchor

ctx is a window of bytes immediately preceding the changed block in the original binary. The default minimum size is 32 bytes (min_context_size), but the cook pipeline uses entropy-gated geometric expansion to ensure each anchor is both high-entropy and unique within the original binary:

1. Start with min_context_size bytes (default 32).
2. Compute Shannon entropy of the candidate context.
3. Search the entire original binary for ctx + ob.
4. If entropy < 2.5 bits/byte OR the pattern appears more than once, double the context size (64 → 128 → 256 → 512).
5. Repeat until both conditions are met, or max_context_size is reached.
6. If max_context_size is reached and the anchor is still non-unique: when require_unique=True (default), raise a hard error listing the failed instructions. When require_unique=False (Force Save), record the non-unique anchors as cook_warnings and proceed.

Quality metadata (ctx_entropy, ctx_unique, ctx_expanded) is stored per-instruction for downstream tooling.

context_after

context_after is the same-size window of bytes immediately after the changed block. During patching, it is appended to the search anchor — the patcher searches for ctx + ob + context_after (not just ctx + ob). This doubles the effective anchor length at zero cost.

The anchor search works as follows:

1. Read ob bytes at the exact offset recorded in the instruction.
2. If they match — apply the patch immediately.
3. If they do not match — search the region [offset - 2048, offset + 2048] for the pattern ctx + ob + context_after.
4. If found at a new offset — apply the patch at the shifted position.
5. If not found — the instruction fails with a diagnostic message.

source — full_cook vs tune_export

Safety Properties

• No blind writes. The patcher never writes mb without first confirming ob is present — either at the recorded offset or at a shifted position found via the anchor search.
• All-or-nothing validation. The strict validator checks every instruction before the patcher writes a single byte. A single failure aborts the entire operation.
• Identity gate. match_key and file_size are verified against the target binary before any instruction is read.
• Portable. Recipes contain no absolute paths, no machine-specific data, and no binary blobs. They are plain JSON and can be stored, versioned, shared, and diffed.

See also

• Cook command — how to create a recipe from two binaries
• Tune command — one-shot validate → apply → verify
• Validate command — individual validation steps
• About OpenRemap — project overview and use cases

← Back to documentation