Wrapper Specification

[Tutorial] [Example]

This page covers the Wrapper format. For the base burrito structure see Scripture Burrito Structure.

A wrapper groups two or more related burritos so that tools can discover and process them as a set. Common uses include bundling a text translation with its audio recording, or bundling a source burrito with derived and supplemental content.

A wrapper is stored as a wrapper.json file. It is distinct from a regular burrito: the format field is "scripture burrito wrapper", not "scripture burrito".

Top-Level Fields

format

MUST be the string "scripture burrito wrapper".

meta

MUST be present. MUST be an object containing:

  • name (REQUIRED): a locale-map object giving a human-readable name for the project (e.g. {"en": "My Project"}).

  • version (REQUIRED): a semantic version string for this wrapper file (e.g. "0.0.1"). This is the version of the wrapper data, not the Scripture Burrito spec version.

  • generator (REQUIRED): an object with:

    • name (REQUIRED): name of the software that created this file

    • version (REQUIRED): version of that software

  • dateCreated (REQUIRED): ISO 8601 date or datetime string.

  • description (OPTIONAL): a locale-map object.

  • abbreviation (OPTIONAL): a locale-map object.

  • defaultLocale (OPTIONAL): BCP-47 tag for the default locale of the localized fields above.

contents

MUST be present. MUST be an object with a "burritos" key whose value is a non-empty array. Each element MUST be an object with:

  • id (REQUIRED): a string that uniquely identifies this burrito within the wrapper. MUST be stable across revisions of the wrapper.

  • path (REQUIRED): path to the burrito directory, relative to the directory containing wrapper.json. The referenced directory MUST contain a metadata.json file.

  • role (REQUIRED): the relationship of this burrito to the others. MUST be one of:

    • "source" — primary, editable content

    • "derived" — content produced from a source burrito

    • "supplemental" — supporting material not itself a Scripture deliverable

    Custom roles MAY be used and MUST be prefixed with "x-".

Constraints

  • The contents.burritos array MUST contain at least one entry.

  • id values MUST be unique within a single wrapper.

  • Each path MUST resolve to a directory containing a valid metadata.json or wrapper.json (nested wrappers are allowed).

  • Circular references through nested wrappers are NOT permitted.