# TipSharks Shared API Contract

This directory contains the shared OpenAPI 3.0.3 specification that defines
the unified domain models and API contract for all three TipSharks services.

## File

| File | Purpose |
|------|---------|
| `openapi.yml` | OpenAPI 3.0.3 specification with all shared schemas and endpoints |

## How Services Should Use This Contract

### 1. Source of Truth — Do Not Duplicate

The schemas in `openapi.yml` are the **canonical definitions** for all shared types
(`Meeting`, `Race`, `Runner`, `Dividend`, `Rating`, `Prediction`, `Tip`, `TipReason`).
Individual services **should not redefine these types from scratch**. Instead:

- **Generate code from the spec** using your language's OpenAPI generator
  (e.g. `openapi-generator-cli`, `openapi-typescript`, `datamodel-code-generator`).
- Or **import and reference this file** from service-level specs via `$ref`.

### 2. Extend, Don't Override

If a service needs additional properties on a shared model, extend the schema
from `openapi.yml` rather than duplicating it:

```yaml
# In a service-specific OpenAPI spec
MyExtendedRace:
  allOf:
    - $ref: "../shared/openapi.yml#/components/schemas/Race"
    - type: object
      properties:
        myServiceSpecificField:
          type: string
```

### 3. Validation

When receiving or sending data that conforms to these schemas, services should
validate payloads against the OpenAPI contract (e.g. via middleware or at the
API gateway level).

### 4. Versioning

This spec is versioned via the `info.version` field (`1.0.0`). Breaking changes
to shared models should increment this version. Services consuming old versions
should be migrated before the new version is deployed.

### 5. Paths Are Informative, Not Prescriptive

The API paths defined here (`/v1/meetings`, `/v1/races`, etc.) describe the
intended shape of the unified API. Individual services may expose subsets of
these paths or implement them under different base URLs. The paths serve as a
**routing reference** for the API gateway and client consumption.

### 6. Conventions

- All dates use format `date` (ISO 8601: `YYYY-MM-DD`).
- All datetimes use format `date-time` (ISO 8601: `YYYY-MM-DDTHH:mm:ssZ`).
- Probabilities are floats in the range `[0, 1]`.
- Required fields are enforced at the schema level.