Commentaries API v1: endpoint and schema reference

{
  "tags": [
    "tree"
  ],
  "summary": "The catalog of every commentary in the tree",
  "description": "Every commentary this tree holds, with its counts and sizes, and the path template of each of its documents relative to v1/.",
  "operationId": "listCommentaries",
  "responses": {
    "200": {
      "description": "The catalog of every commentary in the tree",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/commentary-catalog"
          }
        }
      }
    },
    "404": {
      "description": "No such document. The tree is static: a path that hashes.json does not list does not exist."
    }
  },
  "parameters": []
}

{
  "tags": [
    "tree"
  ],
  "summary": "How and when the tree was built",
  "description": "The builder and extractor versions, the build time, the module catalog the modules were selected from and the Bible API the references were resolved against.",
  "operationId": "getBuild",
  "responses": {
    "200": {
      "description": "How and when the tree was built",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/build"
          }
        }
      }
    },
    "404": {
      "description": "No such document. The tree is static: a path that hashes.json does not list does not exist."
    }
  },
  "parameters": []
}

{
  "tags": [
    "tree"
  ],
  "summary": "The compilation outcome and module failures",
  "description": "The build status, successfully rebuilt modules, failures with their stage and reason, and previously verified modules retained after a failed rebuild. This snapshot describes compilation; the workflow report also records later publication errors.",
  "operationId": "getBuildReport",
  "responses": {
    "200": {
      "description": "The compilation outcome and module failures",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/build-report"
          }
        }
      }
    },
    "404": {
      "description": "No such document. The tree is static: a path that hashes.json does not list does not exist."
    }
  },
  "parameters": []
}

{
  "tags": [
    "tree"
  ],
  "summary": "The SHA-256 of every other document",
  "description": "The integrity manifest of the tree: a digest for every other document, which is also the complete list of the paths the tree contains.",
  "operationId": "getHashes",
  "responses": {
    "200": {
      "description": "The SHA-256 of every other document",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/hashes"
          }
        }
      }
    },
    "404": {
      "description": "No such document. The tree is static: a path that hashes.json does not list does not exist."
    }
  },
  "parameters": []
}

{
  "tags": [
    "tree"
  ],
  "summary": "This description",
  "description": "The OpenAPI description of the tree, generated with it.",
  "operationId": "getOpenApi",
  "responses": {
    "200": {
      "description": "This description",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "404": {
      "description": "No such document. The tree is static: a path that hashes.json does not list does not exist."
    }
  },
  "parameters": []
}

{
  "tags": [
    "tree"
  ],
  "summary": "The JSON Schema of one document type",
  "description": "The schemas embedded under components, served beside the data.",
  "operationId": "getSchema",
  "parameters": [
    {
      "name": "document",
      "in": "path",
      "required": true,
      "description": "The document type.",
      "schema": {
        "type": "string",
        "enum": [
          "commentary-catalog",
          "commentary-metadata",
          "commentary-books",
          "commentary-chapter",
          "commentary-book",
          "commentary",
          "build",
          "build-report",
          "hashes"
        ]
      }
    }
  ],
  "responses": {
    "200": {
      "description": "The JSON Schema of one document type",
      "content": {
        "application/json": {
          "schema": {
            "type": "object"
          }
        }
      }
    },
    "404": {
      "description": "No such document. The tree is static: a path that hashes.json does not list does not exist."
    }
  }
}

{
  "tags": [
    "commentary"
  ],
  "summary": "One commentary's provenance, licence, counts and sizes",
  "description": "Where the module came from, under which licence, how much it holds, how large its whole-commentary document is, and which Bible its references were resolved against.",
  "operationId": "getCommentaryMetadata",
  "parameters": [
    {
      "name": "commentary",
      "in": "path",
      "required": true,
      "description": "The commentary's id, as commentaries.json lists it.",
      "schema": {
        "type": "string",
        "minLength": 1,
        "enum": [
          "abbott",
          "barnes",
          "burkitt",
          "calvincommentaries",
          "catena",
          "clarke",
          "dtn",
          "dutkant",
          "freaug",
          "frechry",
          "jfb",
          "kd",
          "lightfoot",
          "luther",
          "mak",
          "mhc",
          "mhcc",
          "pnt",
          "quotingpassages",
          "rieger",
          "scofield",
          "sentiment",
          "spurious",
          "tdavid",
          "tfg",
          "tsk",
          "varapp",
          "vulgglossa",
          "wesley"
        ]
      }
    }
  ],
  "responses": {
    "200": {
      "description": "One commentary's provenance, licence, counts and sizes",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/commentary-metadata"
          }
        }
      }
    },
    "404": {
      "description": "No such document. The tree is static: a path that hashes.json does not list does not exist."
    }
  }
}

{
  "tags": [
    "commentary"
  ],
  "summary": "The books and chapters one commentary covers",
  "description": "Every book the commentary comments on, with the chapters it has and the number of entries in each book. Chapter 0 is a book introduction.",
  "operationId": "getCommentaryBooks",
  "parameters": [
    {
      "name": "commentary",
      "in": "path",
      "required": true,
      "description": "The commentary's id, as commentaries.json lists it.",
      "schema": {
        "type": "string",
        "minLength": 1,
        "enum": [
          "abbott",
          "barnes",
          "burkitt",
          "calvincommentaries",
          "catena",
          "clarke",
          "dtn",
          "dutkant",
          "freaug",
          "frechry",
          "jfb",
          "kd",
          "lightfoot",
          "luther",
          "mak",
          "mhc",
          "mhcc",
          "pnt",
          "quotingpassages",
          "rieger",
          "scofield",
          "sentiment",
          "spurious",
          "tdavid",
          "tfg",
          "tsk",
          "varapp",
          "vulgglossa",
          "wesley"
        ]
      }
    }
  ],
  "responses": {
    "200": {
      "description": "The books and chapters one commentary covers",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/commentary-books"
          }
        }
      }
    },
    "404": {
      "description": "No such document. The tree is static: a path that hashes.json does not list does not exist."
    }
  }
}

{
  "tags": [
    "commentary"
  ],
  "summary": "One chapter of one commentary",
  "description": "Every comment on one chapter, each published once and anchored at the lowest verse it covers. Verse 0 is the chapter introduction.",
  "operationId": "getCommentaryChapter",
  "parameters": [
    {
      "name": "commentary",
      "in": "path",
      "required": true,
      "description": "The commentary's id, as commentaries.json lists it.",
      "schema": {
        "type": "string",
        "minLength": 1,
        "enum": [
          "abbott",
          "barnes",
          "burkitt",
          "calvincommentaries",
          "catena",
          "clarke",
          "dtn",
          "dutkant",
          "freaug",
          "frechry",
          "jfb",
          "kd",
          "lightfoot",
          "luther",
          "mak",
          "mhc",
          "mhcc",
          "pnt",
          "quotingpassages",
          "rieger",
          "scofield",
          "sentiment",
          "spurious",
          "tdavid",
          "tfg",
          "tsk",
          "varapp",
          "vulgglossa",
          "wesley"
        ]
      }
    },
    {
      "name": "book",
      "in": "path",
      "required": true,
      "description": "GetBible book number: Genesis is 1, Matthew 40, Revelation 66, and the deuterocanonical books continue to 83. books.json lists the numbers the commentary has.",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 83
      }
    },
    {
      "name": "chapter",
      "in": "path",
      "required": true,
      "description": "Chapter number; 0 is the book introduction. books.json lists the chapters each book has.",
      "schema": {
        "type": "integer",
        "minimum": 0
      }
    }
  ],
  "responses": {
    "200": {
      "description": "One chapter of one commentary",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/commentary-chapter"
          }
        }
      }
    },
    "404": {
      "description": "No such document. The tree is static: a path that hashes.json does not list does not exist."
    }
  }
}

{
  "tags": [
    "commentary"
  ],
  "summary": "Every chapter of one book",
  "description": "The chapter documents of one book, each byte-for-byte the document served at its own path.",
  "operationId": "getCommentaryBook",
  "parameters": [
    {
      "name": "commentary",
      "in": "path",
      "required": true,
      "description": "The commentary's id, as commentaries.json lists it.",
      "schema": {
        "type": "string",
        "minLength": 1,
        "enum": [
          "abbott",
          "barnes",
          "burkitt",
          "calvincommentaries",
          "catena",
          "clarke",
          "dtn",
          "dutkant",
          "freaug",
          "frechry",
          "jfb",
          "kd",
          "lightfoot",
          "luther",
          "mak",
          "mhc",
          "mhcc",
          "pnt",
          "quotingpassages",
          "rieger",
          "scofield",
          "sentiment",
          "spurious",
          "tdavid",
          "tfg",
          "tsk",
          "varapp",
          "vulgglossa",
          "wesley"
        ]
      }
    },
    {
      "name": "book",
      "in": "path",
      "required": true,
      "description": "GetBible book number: Genesis is 1, Matthew 40, Revelation 66, and the deuterocanonical books continue to 83. books.json lists the numbers the commentary has.",
      "schema": {
        "type": "integer",
        "minimum": 1,
        "maximum": 83
      }
    }
  ],
  "responses": {
    "200": {
      "description": "Every chapter of one book",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/commentary-book"
          }
        }
      }
    },
    "404": {
      "description": "No such document. The tree is static: a path that hashes.json does not list does not exist."
    }
  }
}

{
  "tags": [
    "commentary"
  ],
  "summary": "The whole commentary",
  "description": "Every book document of the commentary, each byte-for-byte the document served at its own path. A bulk document: metadata.json states its size.",
  "operationId": "getCommentary",
  "parameters": [
    {
      "name": "commentary",
      "in": "path",
      "required": true,
      "description": "The commentary's id, as commentaries.json lists it.",
      "schema": {
        "type": "string",
        "minLength": 1,
        "enum": [
          "abbott",
          "barnes",
          "burkitt",
          "calvincommentaries",
          "catena",
          "clarke",
          "dtn",
          "dutkant",
          "freaug",
          "frechry",
          "jfb",
          "kd",
          "lightfoot",
          "luther",
          "mak",
          "mhc",
          "mhcc",
          "pnt",
          "quotingpassages",
          "rieger",
          "scofield",
          "sentiment",
          "spurious",
          "tdavid",
          "tfg",
          "tsk",
          "varapp",
          "vulgglossa",
          "wesley"
        ]
      }
    }
  ],
  "responses": {
    "200": {
      "description": "The whole commentary",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/commentary"
          }
        }
      }
    },
    "404": {
      "description": "No such document. The tree is static: a path that hashes.json does not list does not exist."
    }
  }
}

{
  "title": "GetBible Commentary Catalog v1",
  "description": "Every commentary in one v1 tree, with the path template of each of its documents relative to the tree root. The catalog and build.json are the only documents that carry the build time.",
  "type": "object",
  "required": [
    "schema",
    "version",
    "generated_at",
    "base_url",
    "metadata_url_template",
    "books_url_template",
    "commentary_url_template",
    "book_url_template",
    "chapter_url_template",
    "module_count",
    "commentaries"
  ],
  "properties": {
    "schema": {
      "const": "getbible-commentaries-catalog-v1"
    },
    "version": {
      "const": 1
    },
    "generated_at": {
      "type": "string",
      "format": "date-time"
    },
    "base_url": {
      "type": "string",
      "minLength": 1
    },
    "metadata_url_template": {
      "const": "{commentary}/metadata.json"
    },
    "books_url_template": {
      "const": "{commentary}/books.json"
    },
    "commentary_url_template": {
      "const": "{commentary}.json"
    },
    "book_url_template": {
      "const": "{commentary}/{book}.json"
    },
    "chapter_url_template": {
      "const": "{commentary}/{book}/{chapter}.json"
    },
    "module_count": {
      "type": "integer",
      "minimum": 0
    },
    "commentaries": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One commentary: its id is the first path segment of all of its documents, and bytes is the size of its whole-commentary document.",
        "required": [
          "id",
          "name",
          "language",
          "license",
          "book_count",
          "chapter_count",
          "entry_count",
          "bytes"
        ],
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1
          },
          "name": {
            "type": "string",
            "minLength": 1
          },
          "language": {
            "type": "string",
            "minLength": 2
          },
          "license": {
            "type": "string"
          },
          "book_count": {
            "type": "integer",
            "minimum": 0
          },
          "chapter_count": {
            "type": "integer",
            "minimum": 0
          },
          "entry_count": {
            "type": "integer",
            "minimum": 0
          },
          "bytes": {
            "type": "integer",
            "minimum": 0
          }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}

{
  "title": "GetBible Commentary Metadata v1",
  "description": "One commentary's provenance, licence, counts and sizes. bytes is the size of the whole-commentary document; storage is the build's own measurement of the module.",
  "type": "object",
  "required": [
    "schema",
    "id",
    "module",
    "name",
    "language",
    "version",
    "license",
    "driver",
    "source_type",
    "versification",
    "book_count",
    "chapter_count",
    "entry_count",
    "bytes",
    "storage",
    "books_url",
    "book_url_template",
    "chapter_url_template",
    "source",
    "source_module_url",
    "text_source",
    "copyright",
    "copyright_holder",
    "copyright_contact",
    "distribution_notes",
    "about",
    "conversion_note",
    "references"
  ],
  "properties": {
    "schema": {
      "const": "getbible-commentary-metadata-v1"
    },
    "id": {
      "type": "string",
      "minLength": 1
    },
    "module": {
      "type": "string",
      "minLength": 1,
      "description": "The source module's own name."
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "language": {
      "type": "string",
      "minLength": 2
    },
    "version": {
      "type": "string"
    },
    "license": {
      "type": "string"
    },
    "driver": {
      "type": "string"
    },
    "source_type": {
      "type": "string"
    },
    "versification": {
      "type": "string",
      "minLength": 1
    },
    "book_count": {
      "type": "integer",
      "minimum": 0
    },
    "chapter_count": {
      "type": "integer",
      "minimum": 0
    },
    "entry_count": {
      "type": "integer",
      "minimum": 0
    },
    "bytes": {
      "type": "integer",
      "minimum": 0
    },
    "storage": {
      "type": "object",
      "description": "How much text the source repeated across verse ranges and what each level of the output costs on disk.",
      "required": [
        "source_entry_count",
        "source_text_bytes",
        "text_bytes",
        "repetition_ratio",
        "chapter_bytes",
        "book_bytes",
        "commentary_bytes",
        "published_bytes"
      ],
      "properties": {
        "source_entry_count": {
          "type": "integer",
          "minimum": 0
        },
        "source_text_bytes": {
          "type": "integer",
          "minimum": 0
        },
        "text_bytes": {
          "type": "integer",
          "minimum": 0
        },
        "repetition_ratio": {
          "type": "number",
          "minimum": 0
        },
        "chapter_bytes": {
          "type": "integer",
          "minimum": 0
        },
        "book_bytes": {
          "type": "integer",
          "minimum": 0
        },
        "commentary_bytes": {
          "type": "integer",
          "minimum": 0
        },
        "published_bytes": {
          "type": "integer",
          "minimum": 0
        }
      },
      "additionalProperties": false
    },
    "books_url": {
      "const": "books.json"
    },
    "book_url_template": {
      "const": "{book}.json"
    },
    "chapter_url_template": {
      "const": "{book}/{chapter}.json"
    },
    "source": {
      "const": "CrossWire SWORD"
    },
    "source_module_url": {
      "type": "string",
      "minLength": 1,
      "description": "The module's own page at its source."
    },
    "text_source": {
      "type": "string"
    },
    "copyright": {
      "type": "string"
    },
    "copyright_holder": {
      "type": "string"
    },
    "copyright_contact": {
      "type": "object",
      "required": [
        "name",
        "email",
        "address"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "email": {
          "type": "string"
        },
        "address": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "distribution_notes": {
      "type": "string"
    },
    "about": {
      "type": "string"
    },
    "conversion_note": {
      "type": "string",
      "minLength": 1
    },
    "references": {
      "type": "object",
      "description": "Which Bible the module's scripture references were resolved against: the API, the versification, the translations whose shape decided which chapters and verses exist, the translation whose book names ref uses, and the librarian and alias tables that resolved the spellings.",
      "required": [
        "api",
        "versification",
        "translations",
        "names",
        "language",
        "librarian",
        "aliases"
      ],
      "properties": {
        "api": {
          "const": "getbible-v2"
        },
        "versification": {
          "type": "string"
        },
        "translations": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "names": {
          "type": [
            "string",
            "null"
          ]
        },
        "language": {
          "type": "string"
        },
        "librarian": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        },
        "aliases": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          }
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

{
  "title": "GetBible Commentary Books Index v1",
  "description": "Which books and chapters one commentary covers. Chapter 0 is a book introduction.",
  "type": "object",
  "required": [
    "schema",
    "commentary",
    "language",
    "name",
    "book_url_template",
    "chapter_url_template",
    "book_count",
    "books"
  ],
  "properties": {
    "schema": {
      "const": "getbible-commentary-books-v1"
    },
    "commentary": {
      "type": "string",
      "minLength": 1
    },
    "language": {
      "type": "string",
      "minLength": 2
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "book_url_template": {
      "const": "{book}.json"
    },
    "chapter_url_template": {
      "const": "{book}/{chapter}.json"
    },
    "book_count": {
      "type": "integer",
      "minimum": 0
    },
    "books": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "book",
          "name",
          "chapters",
          "entry_count"
        ],
        "properties": {
          "book": {
            "type": "integer",
            "minimum": 1,
            "maximum": 83
          },
          "name": {
            "type": "string",
            "minLength": 1
          },
          "chapters": {
            "type": "array",
            "items": {
              "type": "integer",
              "minimum": 0
            }
          },
          "entry_count": {
            "type": "integer",
            "minimum": 0
          }
        },
        "additionalProperties": false
      }
    }
  },
  "additionalProperties": false
}

{
  "title": "GetBible Commentary Chapter v1",
  "description": "One chapter of one commentary. Chapter 0 carries the book introduction and verse 0 carries a chapter introduction.",
  "type": "object",
  "required": [
    "schema",
    "commentary",
    "language",
    "book",
    "name",
    "chapter",
    "entries"
  ],
  "properties": {
    "schema": {
      "const": "getbible-commentary-chapter-v1"
    },
    "commentary": {
      "type": "string",
      "minLength": 1
    },
    "language": {
      "type": "string",
      "minLength": 2
    },
    "book": {
      "type": "integer",
      "minimum": 1,
      "maximum": 83
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "chapter": {
      "type": "integer",
      "minimum": 0
    },
    "entries": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/commentary-chapter/$defs/entry"
      }
    }
  },
  "additionalProperties": false,
  "$defs": {
    "entry": {
      "type": "object",
      "description": "One comment. A source module attaches a comment to a verse range and repeats it for every verse in that range; it is published once here, anchored at the lowest verse it covers, with `verses` listing every verse it applies to when that is more than one.",
      "required": [
        "book",
        "chapter",
        "verse",
        "text"
      ],
      "properties": {
        "book": {
          "type": "integer",
          "minimum": 1,
          "maximum": 83
        },
        "chapter": {
          "type": "integer",
          "minimum": 0
        },
        "verse": {
          "type": "integer",
          "minimum": 0,
          "description": "The lowest verse this comment covers."
        },
        "verses": {
          "type": "array",
          "description": "Every verse this comment covers, including `verse`. Absent when it covers only `verse`.",
          "items": {
            "type": "integer",
            "minimum": 0
          },
          "minItems": 2,
          "uniqueItems": true
        },
        "osis": {
          "type": "string",
          "minLength": 1,
          "description": "The source module's own key for the anchor verse."
        },
        "text": {
          "type": "string"
        },
        "references": {
          "$ref": "#/components/schemas/commentary-chapter/$defs/references"
        }
      },
      "additionalProperties": false
    },
    "references": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One scripture reference, resolved against the GetBible Bible API. book, chapter, and verse are Bible API coordinates; verses lists every verse covered when there is more than one, and an item without verse covers the whole chapter. ref is the same reference written canonically, in the book name the module's language uses, in the form the Query API accepts. text is present when the citation was located in the entry text: the citation exactly as the text spells it.",
        "required": [
          "ref",
          "osis",
          "book",
          "chapter"
        ],
        "properties": {
          "text": {
            "type": "string",
            "minLength": 1
          },
          "ref": {
            "type": "string",
            "minLength": 1
          },
          "osis": {
            "type": "string",
            "minLength": 1
          },
          "book": {
            "type": "integer",
            "minimum": 1,
            "maximum": 83
          },
          "chapter": {
            "type": "integer",
            "minimum": 0
          },
          "verse": {
            "type": "integer",
            "minimum": 0
          },
          "verses": {
            "type": "array",
            "description": "Every verse this reference covers, including verse. Absent when it covers only verse.",
            "items": {
              "type": "integer",
              "minimum": 0
            },
            "minItems": 2,
            "uniqueItems": true
          }
        },
        "additionalProperties": false
      }
    }
  }
}

{
  "title": "GetBible Commentary Book v1",
  "description": "Every chapter of one book of one commentary. Each member of chapters is byte-for-byte the document served at {commentary}/{book}/{chapter}.json.",
  "type": "object",
  "required": [
    "schema",
    "commentary",
    "language",
    "book",
    "name",
    "chapters"
  ],
  "properties": {
    "schema": {
      "const": "getbible-commentary-book-v1"
    },
    "commentary": {
      "type": "string",
      "minLength": 1
    },
    "language": {
      "type": "string",
      "minLength": 2
    },
    "book": {
      "type": "integer",
      "minimum": 1,
      "maximum": 83
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "chapters": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/commentary-chapter"
      }
    }
  },
  "additionalProperties": false
}

{
  "title": "GetBible Commentary v1",
  "description": "One complete commentary. Each member of books is byte-for-byte the document served at {commentary}/{book}.json. This is a bulk document; metadata.json publishes its size in bytes.",
  "type": "object",
  "required": [
    "schema",
    "commentary",
    "language",
    "name",
    "books"
  ],
  "properties": {
    "schema": {
      "const": "getbible-commentary-v1"
    },
    "commentary": {
      "type": "string",
      "minLength": 1
    },
    "language": {
      "type": "string",
      "minLength": 2
    },
    "name": {
      "type": "string",
      "minLength": 1
    },
    "books": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/commentary-book"
      }
    }
  },
  "additionalProperties": false
}

{
  "title": "GetBible Build v1",
  "description": "How and when one v1 tree was built: the builder and extractor, the catalog the modules were selected from and the Bible API the references were resolved against.",
  "type": "object",
  "required": [
    "schema",
    "builder",
    "builder_version",
    "extractor",
    "extractor_version",
    "extractor_contract",
    "api_version",
    "resource",
    "generated_at",
    "catalog_url",
    "bible_api",
    "module_count"
  ],
  "properties": {
    "schema": {
      "const": "getbible-build-v1"
    },
    "builder": {
      "const": "v1_study_builder"
    },
    "builder_version": {
      "type": "string",
      "minLength": 1
    },
    "extractor": {
      "const": "getbiblesword"
    },
    "extractor_version": {
      "type": "string",
      "minLength": 1
    },
    "extractor_contract": {
      "type": "string",
      "minLength": 1
    },
    "api_version": {
      "const": 1
    },
    "resource": {
      "enum": [
        "commentaries",
        "dictionaries"
      ]
    },
    "generated_at": {
      "type": "string",
      "format": "date-time"
    },
    "catalog_url": {
      "type": "string",
      "minLength": 1
    },
    "bible_api": {
      "type": "string",
      "minLength": 1
    },
    "module_count": {
      "type": "integer",
      "minimum": 0
    }
  },
  "additionalProperties": false
}

{
  "title": "GetBible Build Report v1",
  "description": "Compilation status and actionable diagnostics for one build. A published snapshot is captured before repository publication; the workflow report is updated with later publication errors. Successfully rebuilt modules and retained previous modules are listed separately.",
  "type": "object",
  "required": [
    "schema",
    "status",
    "started_at",
    "completed_at",
    "requested_resource",
    "catalog_url",
    "built",
    "skipped",
    "failed",
    "retained",
    "errors",
    "diagnostics",
    "storage",
    "commits"
  ],
  "properties": {
    "schema": {
      "const": "getbible-build-report-v1"
    },
    "status": {
      "enum": [
        "running",
        "success",
        "partial",
        "failed"
      ],
      "description": "Running is an in-progress checkpoint. Success means all approved modules built; partial means usable output exists with reported failures. Failed means the run could not complete safely. Publication failures are recorded in the workflow report."
    },
    "started_at": {
      "type": "string",
      "format": "date-time"
    },
    "completed_at": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time"
    },
    "requested_resource": {
      "enum": [
        "all",
        "commentaries",
        "dictionaries"
      ]
    },
    "catalog_url": {
      "type": "string",
      "minLength": 1
    },
    "built": {
      "type": "object",
      "required": [
        "commentaries",
        "dictionaries"
      ],
      "properties": {
        "commentaries": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "dictionaries": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "additionalProperties": false
    },
    "skipped": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/build-report/$defs/moduleIssue"
      }
    },
    "failed": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/build-report/$defs/moduleFailure"
      }
    },
    "retained": {
      "type": "array",
      "description": "Failed modules whose prior verified documents remain in the published tree.",
      "items": {
        "$ref": "#/components/schemas/build-report/$defs/moduleIssue"
      }
    },
    "errors": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "stage",
          "error_type",
          "reason"
        ],
        "properties": {
          "stage": {
            "type": "string",
            "minLength": 1
          },
          "error_type": {
            "type": "string",
            "minLength": 1
          },
          "reason": {
            "type": "string"
          },
          "resource": {
            "enum": [
              "commentaries",
              "dictionaries"
            ]
          }
        },
        "additionalProperties": false
      }
    },
    "diagnostics": {
      "type": "object",
      "additionalProperties": {
        "type": "array",
        "items": {
          "type": "object"
        }
      }
    },
    "storage": {
      "type": "object",
      "additionalProperties": {
        "type": "object"
      }
    },
    "commits": {
      "type": "object",
      "additionalProperties": {
        "type": [
          "string",
          "null"
        ]
      }
    }
  },
  "$defs": {
    "moduleIssue": {
      "type": "object",
      "required": [
        "resource",
        "module",
        "reason"
      ],
      "properties": {
        "resource": {
          "enum": [
            "commentaries",
            "dictionaries"
          ]
        },
        "module": {
          "type": "string",
          "minLength": 1
        },
        "reason": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "moduleFailure": {
      "type": "object",
      "required": [
        "resource",
        "module",
        "reason",
        "stage",
        "error_type"
      ],
      "properties": {
        "resource": {
          "enum": [
            "commentaries",
            "dictionaries"
          ]
        },
        "module": {
          "type": "string",
          "minLength": 1
        },
        "reason": {
          "type": "string"
        },
        "stage": {
          "type": "string",
          "minLength": 1
        },
        "error_type": {
          "type": "string",
          "minLength": 1
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}

{
  "title": "GetBible Hashes v1",
  "description": "The SHA-256 of every other document in one v1 tree, keyed by path relative to the tree root; also the complete list of the paths the tree contains.",
  "type": "object",
  "required": [
    "schema",
    "algorithm",
    "files"
  ],
  "properties": {
    "schema": {
      "const": "getbible-hashes-v1"
    },
    "algorithm": {
      "const": "sha256"
    },
    "files": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "pattern": "^[0-9a-f]{64}$"
      }
    }
  },
  "additionalProperties": false
}