Resource Container to Scripture Burrito Conversion Guide

Introduction

This guide provides step-by-step instructions for converting Resource Container repositories to Scripture Burrito format. The conversion is generally feasible but requires careful handling of structural differences and some data transformation.

Conversion Feasibility: ✅ HIGHLY FEASIBLE Complexity Level: Low to Medium Recommended Approach: Automated conversion with validation Key Insight: Scripture Burrito is much more flexible than initially assessed

Enhanced Understanding of Scripture Burrito Flexibility

Key Research Findings

Based on thorough research of the Scripture Burrito specification, Scripture Burrito is significantly more flexible than initially understood:

1. Comprehensive Flavor System

• Scripture flavors: textTranslation, scripturalTextStories
• Gloss flavors: glossary, parascripturalGloss
• Parascriptural flavors: parascripturalWordAlignment, parascripturalTextStories
• Peripheral flavors: peripheralResource, peripheralWordAlignment

2. Flexible Ingredient System

• Supports any MIME type including text/usfm, text/tab-separated-values, text/markdown
• Multiple role types: main, auxiliary, introduction, notes, glossary, guide, crossReference
• Precise scope definitions at book, chapter, verse, or story level
• No structural limitations on content organization

3. Enhanced Metadata Capabilities

• Comprehensive identification system
• Multiple language support
• Extensive relationship modeling
• Custom extension support for additional metadata

4. Better Cross-Reference Support

• Built-in relationship system for dependencies
• Ingredient-level cross-referencing
• Support for complex resource interconnections

Conversion Advantages

Scripture Burrito Actually Improves Upon RC:

• More explicit content typing (mimeType)
• Better scope precision (book/chapter/verse level)
• Enhanced relationship modeling
• Flexible role system for content categorization
• Support for custom extensions when needed

Conversion Overview

What Can Be Converted

Based on research of the Scripture Burrito specification, the format is highly flexible and can accommodate most RC content:

✅ Fully Compatible:

• USFM Bible text files (text/usfm mimeType)
• TSV data files (text/tab-separated-values mimeType)
• Markdown documentation files (text/markdown mimeType)
• Complete metadata (name, language, version, contributors)
• File organization (via ingredients system)
• Resource relationships (via relationships array)
• Content categorization (via ingredient roles and scope)

✅ Enhanced in Scripture Burrito:

• Explicit MIME type specification for all content
• Flexible ingredient role system
• Precise scope definitions (book, chapter, verse level)
• Multiple flavor types for different resource categories
• Better support for multi-content repositories

⚠️ Requires Transformation:

• RC checking information → SB custom extensions or meta.generator
• RC versification → SB scope format
• RC project categories → SB ingredient roles

Key Discovery: Scripture Burrito's ingredient system is more flexible than Resource Container's projects array, making conversion easier than initially thought.

Field Mapping Reference

Direct Field Mappings

Structural Mappings

Complex Mappings

Step-by-Step Conversion Process

Step 1: Prepare for Conversion

Prerequisites:

• Access to source Resource Container repository
• Understanding of target Scripture Burrito requirements
• Validation tools for both formats

Initial Assessment:

• Verify source is valid Resource Container
• Check content types and complexity
• Identify potential conversion challenges

Step 2: Convert Basic Metadata

Create Scripture Burrito Meta Section:

• Set meta.format to "scripture burrito"
• Set meta.version to target SB version (e.g., "0.3.0")
• Add generator information for conversion tool

Convert Identification Information:

• Map dublin_core.title to identification.name
• Map dublin_core.identifier to identification.abbreviation
• Map dublin_core.description to identification.description
• Set identification.version from dublin_core.version

Step 3: Convert Language Information

Create Languages Array:

• Create language object from dublin_core.language
• Set tag from language.identifier
• Set direction from language.direction
• Add name field with human-readable language name

Step 4: Determine Flavor Type

Map RC Subject to SB Flavor Type:

Based on Scripture Burrito flavor specifications, the mapping is more straightforward:

Key Insight: Scripture Burrito has specific flavor types designed for different biblical content, making RC conversion very natural.

Step 5: Convert Projects to Ingredients

For Each Project in RC projects[] Array:

Step 5a: Create Ingredient Key

• Use project path as ingredient key
• Remove "./" prefix if present
• Example: "./01-GEN.usfm" becomes "01-GEN.usfm"

Step 5b: Set Ingredient Metadata:

• Determine mimeType from file extension:
  • .usfm → "text/usfm"
  • .tsv → "text/tab-separated-values"
  • .md → "text/markdown"
  • .json → "application/json"
• Set role based on RC content type and SB flavor:
  • Bible books → "main" (for Scripture flavors)
  • Translation notes → "notes" (for Parascriptural flavors)
  • Translation words → "glossary" (for Gloss flavors)
  • Training materials → "guide" (for Peripheral flavors)
  • Front matter → "introduction"
  • Cross-references → "crossReference"

Step 5c: Create Scope Object:

• For Bible books: {"book": "GEN"}
• For chapters: {"book": "GEN", "chapter": "1"}
• For stories: {"story": "01"}

Step 6: Handle Dependencies

Convert RC Relations:

• Map simple dependencies to SB relationships
• Note complex dependencies that can't be fully represented
• Document dependency limitations in conversion notes

Step 7: Validate Conversion

Check Required SB Fields:

• Verify all required meta fields are present
• Confirm identification section is complete
• Validate languages array
• Check type.flavorType is appropriate

Validate Ingredients:

• Confirm all ingredients have required fields
• Verify mimeType assignments are correct
• Check scope objects are properly formatted

Conversion Examples

Example 1: Bible Text Repository (ULT)

Source RC Manifest (manifest.yaml):

dublin_core:
  identifier: 'ult'
  title: 'unfoldingWord® Literal Text'
  language:
    identifier: 'en'
    direction: 'ltr'
  subject: 'Aligned Bible'
  type: 'bundle'
  version: '86'

projects:
  - identifier: 'gen'
    title: 'Genesis'
    path: './01-GEN.usfm'
    sort: 1
    categories: ['bible-ot']

Converted SB Metadata (metadata.json):

{
  "meta": {
    "format": "scripture burrito",
    "version": "0.3.0",
    "generator": {
      "softwareName": "RC to SB Converter",
      "softwareVersion": "1.0.0"
    }
  },
  "identification": {
    "name": "unfoldingWord® Literal Text",
    "abbreviation": "ULT",
    "version": "86"
  },
  "languages": [
    {
      "tag": "en",
      "direction": "ltr"
    }
  ],
  "type": {
    "flavorType": {
      "name": "textTranslation"
    }
  },
  "ingredients": {
    "01-GEN.usfm": {
      "mimeType": "text/usfm",
      "role": "main",
      "scope": {
        "book": "GEN"
      }
    }
  }
}

Example 2: Translation Notes Repository

Source RC Manifest (manifest.yaml):

dublin_core:
  identifier: 'tn'
  title: 'unfoldingWord® Translation Notes'
  subject: 'Translation Notes'
  type: 'help'

projects:
  - identifier: 'gen'
    path: './tn_GEN.tsv'
    categories: ['bible-ot']

Converted SB Metadata (metadata.json):

{
  "meta": {
    "format": "scripture burrito",
    "version": "0.3.0"
  },
  "identification": {
    "name": "unfoldingWord® Translation Notes",
    "abbreviation": "TN"
  },
  "type": {
    "flavorType": {
      "name": "parascripturalWordAlignment"
    }
  },
  "ingredients": {
    "tn_GEN.tsv": {
      "mimeType": "text/tab-separated-values",
      "role": "auxiliary",
      "scope": {
        "book": "GEN"
      }
    }
  }
}

Implementation Guidelines

How to Build a Conversion Tool

Step 1: Set Up Format Parsers

• Implement RC manifest parser (YAML)
• Implement SB metadata generator (JSON)
• Set up file type detection

Step 2: Create Mapping Engine

• Build field mapping functions
• Implement subject-to-flavor-type mapping
• Create scope conversion logic

Step 3: Handle File Processing

• Copy all content files to new repository
• Generate ingredient entries for each file
• Set appropriate mimeType and role for each file

Step 4: Implement Validation

• Validate converted SB metadata against specification
• Check for required fields and proper structure
• Verify ingredient definitions are complete

Step 5: Handle Edge Cases

• Process repositories with missing fields
• Handle non-standard RC structures
• Manage conversion errors gracefully

Conversion Quality Assurance

Pre-Conversion Checks:

• Verify source RC is valid and complete
• Check for non-standard fields or structures
• Identify potential conversion challenges

Post-Conversion Validation:

• Validate SB metadata against specification
• Verify all content files are properly referenced
• Check that scope objects are correctly formatted
• Test converted repository with SB tools

Enhanced Conversion Capabilities

Minimal Data Loss

RC Fields Easily Preserved in SB:

• checking.checking_level → Custom extension in meta.generator or meta.custom
• checking.checking_entity → agencies[] array with checking role
• project.versification → Enhanced scope objects with versification info
• relation[] dependencies → relationships[] array (full support available)

Simplified Conversion Process

Low Complexity Areas (easier than initially thought):

• Subject to flavor type mapping (clear specification guidelines)
• Relationship conversion (SB has robust relationship support)
• Scope conversion (SB scope is more flexible than RC versification)

Medium Complexity Areas:

• Custom extension handling for RC-specific metadata
• Multi-ingredient resource organization
• Role assignment for complex content types

Significant Benefits of Conversion

Scripture Burrito Advantages Over RC:

• Better Content Typing: Explicit MIME types vs implicit file extension detection
• Enhanced Scope System: Book/chapter/verse precision vs simple versification
• Flexible Relationships: Robust relationship modeling vs simple relation array
• Role-Based Organization: Clear content roles vs category tags
• Custom Extension Support: Ability to preserve RC-specific metadata
• Multi-Content Resources: Better support for repositories with multiple content types
• Standardized Format: Industry-standard specification vs Door43-specific format

Best Practices

1. Conversion Planning

• Analyze source RC thoroughly before conversion
• Plan handling of RC-specific fields
• Prepare for manual review of complex cases

2. Quality Assurance

• Validate both source and target formats
• Test converted repositories with appropriate tools
• Document any data loss or transformation decisions

3. Tool Development

• Build comprehensive mapping tables
• Implement robust error handling
• Create validation and testing frameworks

4. Documentation

• Document conversion decisions and rationale
• Maintain mapping of RC fields to SB equivalents
• Record any custom extensions used

Conclusion

Conversion Verdict: ✅ HIGHLY RECOMMENDED - Scripture Burrito is Superior

Based on thorough research of the Scripture Burrito specification, conversion from Resource Container to Scripture Burrito is not only feasible but actually beneficial. Scripture Burrito provides enhanced capabilities that improve upon Resource Container limitations.

Why Convert to Scripture Burrito:

• Industry Standard: Scripture Burrito is designed for interoperability across Bible translation tools
• Enhanced Precision: Better scope and content typing than RC
• Flexible Organization: Ingredients system is more flexible than RC projects
• Better Relationships: Robust relationship modeling vs simple RC relations
• Future-Proof: Designed for modern Bible translation workflows
• Tool Ecosystem: Growing ecosystem of SB-compatible tools

Conversion Complexity: Low to Medium (much easier than initially assessed)

Recommended For All RC Types:

• ✅ Bible text repositories (UHB, UGNT, ULT, UST)
• ✅ Translation support resources (TN, TQ, TW, TWL, TA)
• ✅ Open Bible Stories resources (OBS, OBS-TN, OBS-TWL)
• ✅ Any RC repository type

Implementation Strategy:

1. Automated Conversion Tool: Build conversion tool using mapping guidelines
2. Validation Pipeline: Implement SB validation for quality assurance
3. Gradual Migration: Convert repositories systematically
4. Tool Integration: Integrate with SB-compatible applications

Key Insight: Scripture Burrito was specifically designed to address limitations in existing formats like Resource Container, making it a natural evolution path for Door43 resources.

This guide is based on analysis of both Resource Container and Scripture Burrito specifications and should be used alongside the main Door43 API Developer Guide.