Extending Scripture Burrito

Identify a Need

“Every good work of software starts by scratching a developer’s personal itch.” Eric Raymond

The first scripture flavors of burrito are based on standards used by the Digital Bible Library. These standards were developed - sometimes in haste! - to meet specific needs. In the case of text, there was a need to make translation projects from Paratext available to a wider publishing community, with digital publishing as a major concern. In the case of audio, there was a desire to be able to “mash up” text and related audio within one application or website, all via the same licensing and distribution model.

All these standards have evolved over time within DBL, and the Scripture Burrito standards which replace them will no doubt continue to evolve, as they are used in new ways and stretched in new directions. This process can appear messy, but it has the advantage of keeping standards rooted in the reality of what people need in practice (rather than what someone things people might need or ought to need in theory). Benevolent and self-aware pragmatism can lead to rapid and efficient solutions to the problems that matter.

The zeroth step is therefore to identify a concrete, unaddressed Bible translation or publication-related challenge that would be easier to solve with standards-based data portability.


“We should be able to share all our data” is not concrete - someone would have to define “all”, which would make for a very long list, and it would probably never be long enough to satisfy everyone.

“We need a way to represent Print on Demand projects that can be generated by a variety of tools, and which can be consumed by major global POD vendors” is much more concrete, and is the basis of the Scripture print flavor.



  • Is there an existing flavor to do what you want, or something close to what you want?
  • Are there elements of a good future flavor that are already in widespread use, and which could be included in the new flavor?
  • Is anyone else trying to come up with a flavor to do what you want? (Consider asking the Scripture Burrito Working Group.)

Making Things Easier

All other things being equal, data portability is always a great idea. In practice, standards have a cost and impose constraints, and these considerations need to be weighted against the promised benefits of standards in any given domain.

Standards often work well

  • in domains that are relatively mature
  • where there are multiple stakeholders
  • where most of the experimentation with data representations has already happened
  • where the standards are at some distance from user interfaces and workflows

Premature attempts to standardize can lock everyone into unsuitable solutions and prevent innovation. Or, less dramatically, such standards are simply ignored. Official Scripture Burrito flavors should formalize consensus that already exists, or is within easy reach. However, the x- mechanism provides one way to experiment with burritos without creating a formal standard.

Consider Conventions

In some cases, an existing flavor may be almost what is needed, except for some niggling details. Conventions provide a mechanism for describing such details, without creating a new flavor, and without relaxing the flavor constraints in the direction of “anything goes”.

The contentResourcesByChapter convention for Scripture audio is a good example of this approach. Much Scripture audio is recorded in one-chapter chunks, and many consumers of Scripture audio have a workflow and/or user interface that relies on this. Not all audio conforms to this pattern, and this audio needs storing too. But including this non-conforming audio with no metadata would tend to break per-chapter tool chains and user interfaces. The contentResourcesByChapter convention can be used to show when the consumer can expect per-chapter audio. Consumers can then choose to treat other audio differently, or not to process it, or something else, but they know what to expect, and, regardless of the answer, they only need to deal with one flavor for Scripture audio.

Conventions should generally be easier to negotiate than new flavors. Also, there is an x- mechanism for conventions to allow informal experimentation.

Pick the Appropriate FlavorType

Scripture Burrito flavors are subdivided into four flavorTypes, on the basis of (roughly) how similar to Scripture they are. The diagram below illustrates the logic behind the four flavorTypes - see also the detailed schema documentation. On a technical level, the more Scripture-like flavorTypes require more metadata, and specific ecosystems, applications and tool chains may only accept certain flavorTypes.


Fork an X-Flavor

The easiest way to assemble valid Scripture Burrito is to start with the example closest to your use case. Assuming the flavorType is correct, almost all the metadata should “just work”. The exception is


which is where flavor-specific information is stored. For experimenting with this part of the specification while keeping everything else valid, set the flavor to something beginning with “x-”. The schema will then allow most well-formed JSON within flavorDetails.

(This task will be much less painful with a schema-aware editor that validates after each keystroke. See the Real Time Editing section of the README for help on this.)

Circulate it, Use it, Refine it

No amount of design work will guarantee that your proposal actually works, for you and for others. X-flavors should be relatively easy for burrito-aware technology to exchange. Share your proposal with others, encourage them to try to use your data and to try encoding their own. Listen to suggestions of other ways of doing things, and see if they can be addressed in your proposal. Ideally, try to get another organization to implement tools that use your proposal, as that’s a great way to find out where the proposal needs to be more precise.

Talk to the Scripture Burrito Working Group

When you’re ready, send a proposal to the Scripture Burrito Working group, including

  • Why the Bible translation and publishing world needs this flavor
  • Who has been involved in discussion and development to detailed
  • What code has been written to use this burrito
  • Outstanding issues
  • Example burritos

The next steps will depend on many factors. The working group may ask for more details, or for you to work with them on those details. Resource-related issues may be directed to the Copenhagen Alliance. All this takes time, but the aim is to end up with robust standards that will serve the Bible translation and publication community for years to come.