libre-bible-data/docs/resource-manifest.md

Resource Manifest

Each sources/*.json file describes one upstream resource. The first resource is a Bible translation, but the same manifest discipline should also cover study notes, commentaries, maps, lexicons, dictionaries, timelines, cross-references, and other Bible-study resources.

Required fields:

• id: Stable package id used by apps.
• resource_type: Type of resource, such as translation, study_notes, commentary, map, lexicon, dictionary, cross_reference, or timeline.
• title: Human-readable title.
• short_title: Short human title when different from title.
• abbreviation: Short label.
• alternate_ids: Upstream or ecosystem ids for the same resource.
• language: Object with language code, name, and dialect when relevant.
• script: Script code when useful.
• canon: Scope and notes for biblical canon coverage.
• translation: Translation-specific metadata, including translation year, edition year, source text basis, tradition, and public description.
• contributors: Names and roles for translators, maintainers, publishers, source providers, or package providers.
• features: Structured feature list, not just strings.
• attachments: Included and future-supported attachment metadata.
• source.provider: Upstream publisher or repository.
• source.url: Human-facing upstream page.
• source.download_url: Machine download URL used by importers.
• source.format: Upstream source format, such as usfm-zip.
• source.upstream_id: Upstream resource id.
• source.upstream_last_updated: Upstream last-updated date when known.
• license.name: License or rights label.
• license.redistribution: Whether this repo may redistribute normalized outputs.
• license.jurisdiction_notes: Practical rights notes.
• license.attribution: Attribution text when needed.
• checks.expected_sha256: Last accepted source archive checksum.
• checks.last_checked_at: Last automated check timestamp.
• importer.name: Script/importer id.
• importer.version: Importer version.
• packages: Generated package paths.
• catalog_display: Human-facing summary and primary feature labels.

Attachment metadata should record:

• resource_type: Attachment type, such as concordance_links, study_notes, commentary, map, morphology, lexicon, or timeline.
• relationship: How the attachment connects, such as word-to-strongs, verse-to-note, range-to-commentary, or place-to-map.
• anchor_types: The target surfaces it can attach to: translation, book, chapter, verse, verse range, word/token, Strong's number, lemma, topic, place, or timeline event.
• languages: Original or target languages involved, including Hebrew, Greek, and Aramaic when applicable.
• systems: Concordance or tagging systems involved, such as Strong's or morphology codes.
• package: Generated package path when the attachment is packaged.

Update flow:

1. Download the upstream artifact to cache/<resource-id>/.
2. Calculate SHA-256.
3. Compare against checks.expected_sha256.
4. If unchanged, update checks.last_checked_at only when intentionally accepting that metadata churn.
5. If changed, inspect upstream release notes/license, regenerate packages, verify counts/checksums, then update the manifest in the same commit.