Datasets

export interface AvailableDatasets {
    /**
     * The list of datasets.
     */
    datasets: Dataset[];
}

export interface Dataset {
    /**
     * The ID of the dataset.
     */
    id: string;

    /**
     * The name of the dataset.
     */
    name: string;

    /**
     * The website for the dataset.
     */
    website: string;

    /**
     * The URL that the license for the dataset can be found.
     */
    licenseUrl: string;

    /**
     * The english name for the dataset.
     */
    englishName: string;

    /**
     * The ISO 639 3-letter language tag that the dataset is primarily in.
     */
    language: string;

    /**
     * The direction that the language is written in.
     * "ltr" indicates that the text is written from the left side of the page to the right.
     * "rtl" indicates that the text is written from the right side of the page to the left.
     */
    textDirection: 'ltr' | 'rtl';

    /**
     * The API link for the list of available books for this dataset.
     */
    listOfBooksApiLink: string;

    /**
     * The available list of formats.
     */
    availableFormats: ('json' | 'usfm')[];

    /**
     * The number of books that are contained in this dataset.
     */
    numberOfBooks: number;

    /**
     * The total number of chapters that are contained in this dataset.
     */
    totalNumberOfChapters: number;

    /**
     * The total number of verses that are contained in this dataset.
     */
    totalNumberOfVerses: number;

    /**
     * The total number of cross references that are contained in this dataset.
     * 0 for datasets that don't contain cross references.
     */
    totalNumberOfReferences: number;

    /**
     * The total number of interlinear words that are contained in this dataset.
     * Omitted if the dataset doesn't contain interlinear words.
     */
    totalNumberOfWords?: number;

    /**
     * Gets the name of the language that the dataset is in.
     * Null or undefined if the name of the language is not known.
     */
    languageName?: string;

    /**
     * Gets the name of the language in English.
     * Null or undefined if the language doesn't have an english name.
     */
    languageEnglishName?: string;

    /**
     * The API links for the lists of entities in the dataset.
     * Omitted if the dataset doesn't contain the corresponding entities.
     */
    listOfPeopleApiLink?: string;
    listOfPlacesApiLink?: string;
    listOfEventsApiLink?: string;
    listOfPeopleGroupsApiLink?: string;

    /**
     * The total number of entities that are contained in the dataset.
     * Omitted if the dataset doesn't contain the corresponding entities.
     */
    totalNumberOfPeople?: number;
    totalNumberOfPlaces?: number;
    totalNumberOfEvents?: number;
    totalNumberOfPeopleGroups?: number;

    /**
     * The API link for the list of lexicon entries in the dataset.
     * Omitted if the dataset doesn't contain lexicon entries.
     */
    listOfLexiconApiLink?: string;

    /**
     * The total number of lexicon entries that are contained in the dataset.
     * Omitted if the dataset doesn't contain lexicon entries.
     */
    totalNumberOfLexicon?: number;
}

export interface DatasetBooks {
    /**
     * The dataset information for the books.
     */
    dataset: Dataset;

    /**
     * The list of books that are available for the dataset.
     */
    books: DatasetBook[];
}

interface DatasetBook {
    /**
     * The ID of the book.
     * Matches the ID of the corresponding book in the Bible (GEN, EXO, etc.).
     */
    id: string;

    /**
     * The order of the book in the Bible.
     */
    order: number;

    /**
     * The number of the first chapter in the book.
     */
    firstChapterNumber: number;

    /**
     * The link to the first chapter of the book.
     */
    firstChapterApiLink: string | null;

    /**
     * The number of the last chapter in the book.
     */
    lastChapterNumber: number | null;

    /**
     * The link to the last chapter of the book.
     */
    lastChapterApiLink: string | null;

    /**
     * The number of chapters that the book contains.
     */
    numberOfChapters: number;

    /**
     * The number of verses that the book contains.
     */
    totalNumberOfVerses: number;

    /**
     * The total number of cross references that this book contains.
     */
    totalNumberOfReferences: number;
}

export interface DatasetBookChapter {
    /**
     * The dataset information for the book chapter.
     */
    dataset: Dataset;

    /**
     * The book information for the book chapter.
     */
    book: DatasetBook;

    /**
     * The link to this chapter.
     */
    thisChapterLink: string;

    /**
     * The link to the next chapter.
     * Null if this is the last chapter in the dataset.
     */
    nextChapterApiLink: string | null;

    /**
     * The link to the previous chapter.
     * Null if this is the first chapter in the dataset.
     */
    previousChapterApiLink: string | null;

    /**
     * The number of verses that the chapter contains.
     */
    numberOfVerses: number;

    /**
     * The information for the chapter.
     */
    chapter: DatasetChapterData;
}

interface DatasetChapterData {
    /**
     * The number of the chapter.
     */
    number: number;

    /**
     * The content of the chapter.
     */
    content: DatasetVerse[];
}

/**
 * A verse carries either `references` (cross reference datasets) or `words` (interlinear datasets).
 * Check which one is present with `'words' in verse`.
 */
type DatasetVerse = DatasetReferencesVerse | DatasetWordsVerse;

interface DatasetReferencesVerse {
    /**
     * The number of the verse.
     */
    verse: number;

    /**
     * The cross-references for the verse.
     *
     * Sorted by score, descending.
     */
    references: DatasetReference[];
}

interface DatasetWordsVerse {
    /**
     * The number of the verse.
     */
    verse: number;

    /**
     * The original-language words of the verse, in original-text order.
     * See "Interlinear Datasets" below.
     */
    words: InterlinearWord[];
}

interface DatasetReference {
    /**
     * The ID of the book that is being referenced.
     */
    book: string;

    /**
     * The chapter number.
     */
    chapter: number;

    /**
     * The verse number.
     * If `endVerse` is present, then this is the verse that the reference starts at.
     */
    verse: number;

    /**
     * The verse that the reference ends at.
     */
    endVerse?: number;

    /**
     * The relevence score for the reference.
     */
    score?: number;
}

// See "Interlinear Datasets" below for the structure of InterlinearWord.

export interface DatasetEntityRef {
    /**
     * The ID of the entity that is being referenced.
     */
    id: string;

    /**
     * The type of the entity that is being referenced.
     * Matches the collection segment of the entity's API link,
     * so the link can be constructed as `/api/d/{dataset}/{type}/{id}.json`.
     */
    type: 'people' | 'places' | 'events' | 'groups';

    /**
     * The name of the entity that is being referenced.
     */
    name?: string;

    /**
     * The API link for the entity that is being referenced.
     */
    apiLink?: string;
}

export interface VerseRef {
    /**
     * The ID of the book (GEN, EXO, etc.).
     */
    book: string;

    /**
     * The chapter number that the reference starts at.
     */
    chapter: number;

    /**
     * The verse number that the reference starts at.
     */
    verse: number;

    /**
     * The verse that the reference ends at.
     * Consecutive verses in the same chapter are collapsed into a single reference.
     */
    endVerse?: number;
}

export interface DatasetEntityBookChapter {
    /**
     * The dataset information for the book chapter.
     */
    dataset: Dataset;

    /**
     * The book information for the book chapter.
     */
    book: DatasetBook;

    /**
     * The entity data for the chapter.
     */
    chapter: DatasetEntityChapterData;

    /**
     * The link to this chapter.
     */
    thisChapterLink: string;

    /**
     * The link to the next chapter.
     * Null if this is the last chapter in the dataset.
     */
    nextChapterApiLink: string | null;

    /**
     * The link to the previous chapter.
     * Null if this is the first chapter in the dataset.
     */
    previousChapterApiLink: string | null;

    /**
     * The number of people, places, and events that appear in the chapter.
     */
    numberOfPeople: number;
    numberOfPlaces: number;
    numberOfEvents: number;
}

interface DatasetEntityChapterData {
    /**
     * The number of the chapter.
     */
    number: number;

    /**
     * The people that appear in the chapter.
     * Sorted by the first verse that they appear in.
     */
    people: ChapterPerson[];

    /**
     * The places that appear in the chapter.
     * Sorted by the first verse that they appear in.
     */
    places: ChapterPlace[];

    /**
     * The events that appear in the chapter.
     * Sorted by the first verse that they appear in.
     */
    events: ChapterEvent[];
}

interface ChapterPerson {
    /**
     * The ID of the person.
     */
    id: string;

    /**
     * The name of the person.
     */
    name: string;

    /**
     * Whether the name of the person is a proper name.
     */
    isProperName?: boolean;

    /**
     * The gender of the person.
     */
    gender?: string;

    /**
     * The year that the person was born and the year they died.
     * Negative numbers are years BC. Positive numbers are years AD.
     */
    birthYear?: number;
    deathYear?: number;

    /**
     * The API link for the person.
     */
    apiLink: string;

    /**
     * The numbers of the verses in the chapter that mention the person.
     * Sorted in ascending order.
     */
    verses: number[];
}

interface ChapterPlace {
    /**
     * The ID of the place.
     */
    id: string;

    /**
     * The name of the place.
     */
    name: string;

    /**
     * The type of geographical feature that the place is.
     */
    featureType?: string;

    /**
     * The latitude and longitude of the place.
     */
    latitude?: number;
    longitude?: number;

    /**
     * The API link for the place.
     */
    apiLink: string;

    /**
     * The numbers of the verses in the chapter that mention the place.
     * Sorted in ascending order.
     */
    verses: number[];
}

interface ChapterEvent {
    /**
     * The ID of the event.
     */
    id: string;

    /**
     * The name of the event.
     */
    name: string;

    /**
     * The date that the event started at.
     */
    startDate?: string;

    /**
     * The API link for the event.
     */
    apiLink: string;

    /**
     * The numbers of the verses in the chapter that describe the event.
     * Sorted in ascending order.
     */
    verses: number[];
}

export interface DatasetPeople {
    /**
     * The dataset information for the people.
     */
    dataset: Dataset;

    /**
     * The list of people that are available for the dataset.
     */
    people: DatasetPersonSummary[];
}

interface DatasetPersonSummary {
    /**
     * The ID of the person.
     */
    id: string;

    /**
     * The name of the person.
     */
    name: string;

    /**
     * Whether the name of the person is a proper name.
     */
    isProperName?: boolean;

    /**
     * The gender of the person.
     */
    gender?: string;

    /**
     * The number of Bible references that mention the person.
     */
    numberOfReferences: number;

    /**
     * The API link for the person.
     */
    thisPersonApiLink: string;
}

export interface DatasetPersonResponse {
    /**
     * The dataset information for the person.
     */
    dataset: Dataset;

    /**
     * The information about the person.
     */
    person: DatasetPerson;

    /**
     * The API link for this person.
     */
    thisPersonApiLink: string;
}

interface DatasetPerson {
    /**
     * The ID of the person.
     */
    id: string;

    /**
     * The name of the person.
     */
    name: string;

    /**
     * Other names that the person is called by.
     */
    alsoCalled?: string[];

    /**
     * Whether the name of the person is a proper name.
     */
    isProperName?: boolean;

    /**
     * The gender of the person.
     */
    gender?: string;

    /**
     * The description of the person. Each string is a paragraph.
     */
    description?: string[];

    /**
     * The year that the person was born and the year they died.
     * Negative numbers are years BC. Positive numbers are years AD.
     */
    birthYear?: number;
    deathYear?: number;

    /**
     * The earliest and latest years that the person is mentioned in.
     */
    minYear?: number;
    maxYear?: number;

    /**
     * The place that the person was born and died in.
     */
    birthPlace?: DatasetEntityRef;
    deathPlace?: DatasetEntityRef;

    /**
     * The family relationships of the person.
     */
    father?: DatasetEntityRef[];
    mother?: DatasetEntityRef[];
    partners?: DatasetEntityRef[];
    children?: DatasetEntityRef[];
    siblings?: DatasetEntityRef[];
    halfSiblingsSameMother?: DatasetEntityRef[];
    halfSiblingsSameFather?: DatasetEntityRef[];

    /**
     * The people groups that the person is a member of.
     */
    memberOf?: DatasetEntityRef[];

    /**
     * The events that the person participated in.
     */
    events?: DatasetEntityRef[];

    /**
     * The list of Bible references that mention the person.
     * Sorted by book order, chapter, and verse.
     */
    references: VerseRef[];
}

export interface DatasetPlaces {
    /**
     * The dataset information for the places.
     */
    dataset: Dataset;

    /**
     * The list of places that are available for the dataset.
     */
    places: DatasetPlaceSummary[];
}

interface DatasetPlaceSummary {
    /**
     * The ID of the place.
     */
    id: string;

    /**
     * The name of the place.
     */
    name: string;

    /**
     * The type of geographical feature that the place is.
     * For example, "City", "Region", "Mountain", "Water", etc.
     */
    featureType?: string;

    /**
     * The latitude and longitude of the place.
     */
    latitude?: number;
    longitude?: number;

    /**
     * The number of Bible references that mention the place.
     */
    numberOfReferences: number;

    /**
     * The API link for the place.
     */
    thisPlaceApiLink: string;
}

export interface DatasetPlaceResponse {
    /**
     * The dataset information for the place.
     */
    dataset: Dataset;

    /**
     * The information about the place.
     */
    place: DatasetPlace;

    /**
     * The API link for this place.
     */
    thisPlaceApiLink: string;
}

interface DatasetPlace {
    /**
     * The ID of the place.
     */
    id: string;

    /**
     * The name of the place.
     */
    name: string;

    /**
     * The name of the place as it appears in the King James Version
     * and the English Standard Version.
     */
    kjvName?: string;
    esvName?: string;

    /**
     * Other names that the place is called by.
     */
    aliases?: string[];

    /**
     * The type of geographical feature that the place is.
     */
    featureType?: string;
    featureSubType?: string;

    /**
     * The latitude and longitude of the place, and how precise they are.
     */
    latitude?: number;
    longitude?: number;
    precision?: string;

    /**
     * The description of the place. Each string is a paragraph.
     */
    description?: string[];

    /**
     * The comment on the place from the dataset authors.
     */
    comment?: string;

    /**
     * The root place for this place.
     * Different names for the same geographical location share the same root place.
     */
    rootPlace?: DatasetEntityRef;

    /**
     * The place that this place is a duplicate of.
     */
    duplicateOf?: DatasetEntityRef;

    /**
     * The people that have been at, were born at, or died at the place.
     */
    people?: DatasetEntityRef[];
    peopleBorn?: DatasetEntityRef[];
    peopleDied?: DatasetEntityRef[];

    /**
     * The events that happened at the place.
     */
    events?: DatasetEntityRef[];

    /**
     * The list of Bible references that mention the place.
     * Sorted by book order, chapter, and verse.
     */
    references: VerseRef[];
}

export interface DatasetEvents {
    /**
     * The dataset information for the events.
     */
    dataset: Dataset;

    /**
     * The list of events that are available for the dataset.
     */
    events: DatasetEventSummary[];
}

interface DatasetEventSummary {
    /**
     * The ID of the event.
     */
    id: string;

    /**
     * The name of the event.
     */
    name: string;

    /**
     * The date that the event started at.
     * Negative numbers are years BC. Positive numbers are years AD.
     * More specific dates use the `YYYY-MM-DD` format.
     */
    startDate?: string;

    /**
     * The number of Bible references that describe the event.
     */
    numberOfReferences: number;

    /**
     * The API link for the event.
     */
    thisEventApiLink: string;
}

export interface DatasetEventResponse {
    /**
     * The dataset information for the event.
     */
    dataset: Dataset;

    /**
     * The information about the event.
     */
    event: DatasetEvent;

    /**
     * The API link for this event.
     */
    thisEventApiLink: string;
}

interface DatasetEvent {
    /**
     * The ID of the event.
     */
    id: string;

    /**
     * The name of the event.
     */
    name: string;

    /**
     * The date that the event started at.
     */
    startDate?: string;

    /**
     * The duration of the event.
     * For example, "1D" is one day and "40Y" is fourty years.
     */
    duration?: string;

    /**
     * The people that participated in the event.
     */
    participants?: DatasetEntityRef[];

    /**
     * The places that the event happened at.
     */
    locations?: DatasetEntityRef[];

    /**
     * The people groups that participated in the event.
     */
    groups?: DatasetEntityRef[];

    /**
     * The event that this event is a part of.
     */
    partOf?: DatasetEntityRef;

    /**
     * The event that happened before this event.
     */
    predecessor?: DatasetEntityRef;

    /**
     * The list of Bible references that describe the event.
     * Sorted by book order, chapter, and verse.
     */
    references: VerseRef[];
}

export interface DatasetPeopleGroups {
    /**
     * The dataset information for the people groups.
     */
    dataset: Dataset;

    /**
     * The list of people groups that are available for the dataset.
     */
    groups: DatasetPeopleGroupSummary[];
}

interface DatasetPeopleGroupSummary {
    /**
     * The ID of the people group.
     */
    id: string;

    /**
     * The name of the people group.
     */
    name: string;

    /**
     * The number of people that are members of the people group.
     */
    numberOfMembers: number;

    /**
     * The API link for the people group.
     */
    thisPeopleGroupApiLink: string;
}

export interface DatasetPeopleGroupResponse {
    /**
     * The dataset information for the people group.
     */
    dataset: Dataset;

    /**
     * The information about the people group.
     */
    group: DatasetPeopleGroup;

    /**
     * The API link for this people group.
     */
    thisPeopleGroupApiLink: string;
}

interface DatasetPeopleGroup {
    /**
     * The ID of the people group.
     */
    id: string;

    /**
     * The name of the people group.
     */
    name: string;

    /**
     * The people that are members of the people group.
     */
    members?: DatasetEntityRef[];

    /**
     * The events that the people group participated in.
     */
    events?: DatasetEntityRef[];

    /**
     * The list of Bible references that mention the people group.
     * Sorted by book order, chapter, and verse.
     */
    references: VerseRef[];
}

interface InterlinearWord {
    /**
     * The 1-based rank of the word in the original text's order.
     * Words are listed in this order.
     */
    pos: number;

    /**
     * The 1-based rank of the word in the Berean Standard Bible's English order.
     */
    bsbPos: number;

    /**
     * The language of the word.
     */
    language: 'hebrew' | 'aramaic' | 'greek';

    /**
     * The word in the original script. NFC-normalized.
     */
    text: string;

    /**
     * The transliteration of the word.
     */
    transliteration: string | null;

    /**
     * The short grammatical parsing code of the word. e.g. "N-mp" or "V-Qal-Perf-3ms".
     */
    parsing: string | null;

    /**
     * The spelled-out grammatical parsing of the word.
     */
    parsingFull: string | null;

    /**
     * The zero-padded Strong's number of the word. e.g. "H0430" or "G3056".
     * Zero-padded, which matches the KJV's `.words.json` values.
     * Other translations' values may need zero-padding and suffix stripping before joining.
     * Null when the source gives the word no Strong's number
     * (this is the case for some words that are suffixes, such as pronoun suffixes).
     */
    strongs: string | null;

    /**
     * The Berean Standard Bible's English phrase for the word.
     * Null when the BSB leaves the word untranslated (such as the Hebrew direct object marker).
     */
    gloss: string | null;
}

export interface DatasetLexicon {
    /**
     * The dataset information for the lexicon.
     */
    dataset: Dataset;

    /**
     * The list of lexicon entries that are available for the dataset.
     */
    lexicon: DatasetLexiconEntrySummary[];
}

export interface DatasetLexiconEntrySummary {
    /**
     * The zero-padded Strong's number of the lexicon entry. e.g. "H0430".
     */
    id: string;

    /**
     * The language of the lexicon entry.
     */
    language: 'hebrew' | 'aramaic' | 'greek';

    /**
     * The name of the lexicon entry.
     * This is the lemma of the entry's first sense.
     */
    name: string;

    /**
     * The API link for the lexicon entry.
     */
    apiLink: string;
}

export interface DatasetLexiconEntry {
    /**
     * The dataset information for the lexicon entry.
     */
    dataset: Dataset;

    /**
     * The lexicon entry.
     */
    entry: DatasetLexiconEntryContent;

    /**
     * The API link for this lexicon entry.
     */
    thisLexiconEntryApiLink: string;
}

export interface DatasetLexiconEntryContent {
    /**
     * The zero-padded Strong's number of the entry. e.g. "H0430".
     */
    id: string;

    /**
     * The language of the entry.
     * This is the language of the entry's first sense.
     */
    language: 'hebrew' | 'aramaic' | 'greek';

    /**
     * The senses of the entry, in ID order.
     */
    senses: DatasetLexiconSense[];
}

export interface DatasetLexiconSense {
    /**
     * The extended ID of the sense. e.g. "H0001G".
     * Equal to the base Strong's number when the number has a single sense.
     */
    id: string;

    /**
     * The language of the sense.
     */
    language: 'hebrew' | 'aramaic' | 'greek';

    /**
     * The lemma of the sense in the original script.
     */
    lemma: string;

    /**
     * The transliteration of the lemma.
     */
    transliteration: string | null;

    /**
     * The part of speech (morphology) code of the sense.
     */
    partOfSpeech: string | null;

    /**
     * The short English gloss of the sense.
     */
    gloss: string | null;

    /**
     * The definition of the sense as plain text.
     * Paragraphs are separated by blank lines. Markup in the source is removed.
     */
    definition: string;
}