Schemas

In progress, API not available for public use.

Querying the API

Any models can be accessed via their respective endpoints. To filter them, you can use a request query parameter with the key name and your filter. The filter should be accepted by MongoDB, our back-end database.

Constants

Here are the constant types used in our API.

type TabroomAsset = string;
type School = string
type Circuit = string

type ElimRoundName =
    "Finals" |
    "Semifinals" |
    "Quarterfinals" |
    "Octafinals" |
    "Double Octafinals" |
    "Triple Octafinals" |
    "Quadruple Octafinals"

type Bid =
    "full" |
    "partial"

type Event =
    "Public Forum" |
    "Lincoln Douglas" |
    "Policy"

type RoundType =
    "prelim" |
    "elim"

type Side =
    "Pro" |
    "Con" |
    "Aff" |
    "Neg"

type Result =
    "Win" |
    "Loss" |
    "Bye"

Document Fragments

These are the "building blocks" for our main schemas. Unlike the main schemas, they do not have their own collection in our database, but are instead incorporated into parent documents.

interface Statistics {
    _id: string;
    prelim_record: [number, number];
    elim_record: [number, number];
    break_pct: number;
    avg_op_wpm: number;
    otr_score: number;
    rank: {
        circuit: {
            season: number;
            all_time: number;
        },
        event: {
            season: number;
            all_time: number;
        }
    },
    speaking_results: {
        [key: ref<Competitor>]: SpeakingResult;
    };
    bids: {
        full: number;
        partial: number;
        ghost_full: number;
        ghost_partial: number;
    }
}

interface SpeakingResult {
    _id: string;
    raw_avg: number;
    adj_avg: number;
}

Models

These 7 models are our main schemas and can be interacted with through their respective endpoints.

If the ref<T> generic type is used, it means that the field can be populated to its respective model via the expand query parameter. For performance reasons, this should only be done if the data is actually needed.

Judge

A judge has at least one JudgeRecord. This model should be used for performant judge searching by name. It is available at /judges.

interface Judge {
    _id: string;
    name: string;

    // TODO: Judge statistics (v3)
}

Judge Record

A judge record is detailed information about a single round they judged. It is available at /judge-record.

interface JudgeRecord {
    _id: string;
    decision: Side;
    avg_speaker_points: number;
    round: ref<Round>;
    judge_url: TabroomAsset;
    judge: ref<Judge>;
    type: RoundType;
    event: Event;
    circuit: Circuit;
    tournament: ref<Tournament>;
    timestamp: number;
}

Entry

An entry is comprised of one or more competitors. They are restricted to one event, but their tournament information can span multiple seasons and circuits. Consequently, we recommend filtering down to specific seasons and/or circuits via the request's query parameters. It is available at /entries.

interface Entry {
    // Metadata
    _id: string;
    codes: string[];
    competitors: ref<Competitor>[];
    schools: School[];
    statistics?: Statistics; // Computed, Expandable

    // Can be used as filter options
    event: Event;
    circuits: Circuit[];
    seasons: number[];

    // Results
    tournaments: ref<TournamentResult>[];
}

Tournament Result

A tournament result is an entry's performance data at a given Tournament. It is available at /tournament-results.

interface TournamentResult {
    _id: string;
    tournament: ref<Tournament>;
    code: string;
    competitors: ref<Competitor>[];
    prelim_rank: [number, number];
    prelim_record: [number, number];
    elim_record: [number, number];
    entry_id: number;
    entry_page: TabroomAsset;
    school: School;
    speaking_results: {
        [key: ref<Competitor>]: SpeakingResult;
    };
    bid: Bid;
    is_ghost_bid: boolean;
    op_wpm: number;
    prelim_rounds: ref<Round>[];
    elim_rounds: ref<Round>[];
}

Round

A round is the result of a specific matchup at a Tournament. It is available at /rounds.

interface Round {
    _id: string;
    name: string;
    name_std: string;
    result: Result;
    decision: [number, number];
    judges: ref<JudgeRecord>[];
    side: Side;
    opponent: ref<Entry>;
    op_wpm: number;
    speaking_results: {
        [key: ref<Competitor>]: SpeakingResult;
    };
}

Tournament

A tournament is a competition within a specific debate event, circuit, and season. It is available at /tournamnets.

interface Tournament {
    _id: string;
    name: string;
    start_date: number;
    end_date: number;
    location: string;
    url: TabroomAsset;
    event: Event;
    event_url: TabroomAsset;
    prelim_url: TabroomAsset;
    tourn_id: string;
    circuit: Circuit;
    season: number;
    is_toc_qualifier: boolean;
    bid_level: ElimRoundName;
}

Competitor

A competitor is an individual. They have at least 1 associated Entry, but can have multiple (including across various events). This model should be used for performant debater searching by name, or to find out all activity of a specific debater. It is available at /competitors.

interface Competitor {
    _id: string;
    name: string;
}