# Schemas

## 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. 

```typescript
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.

```typescript
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`.

```typescript
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`.

```typescript
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`.

```typescript
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`.

```typescript
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`.

```typescript
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`.

```typescript
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`.

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.debate.land/schemas.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.