openapi: 3.0.0
info:
  title: DHB / api
  description: >
    Documentation of the DHB / hockey API. Please note that the contents is
    currently still under development and returned values are likely to change.
  termsOfService: https://docs.dhb.digital/api/terms-of-service
  contact:
    name: DHB / support
    url: https://get.support.dhb.digital/servicedesk/customer/portal/9
    email: support@dhb.digital
  license:
    name: License agreement
    url: https://docs.dhb.digital/api/license-agreement
  version: 1.0.1
servers:
  - url: https://api.stg.dhb.digital/api/v1/
    description: DHB / api (Staging)
  - url: https://api.hockey.de/api/v1/
    description: DHB / api (Production)
  - url: https://virtserver.swaggerhub.com/dhbhockey/dhb-hockey-api/0.3.0
    description: SwaggerHub API Auto Mocking
tags:
  - name: Organisations
  - name: Leagues
  - name: Clubs
  - name: Locations
  - name: Teams
  - name: Matches
  - name: Players
paths:
  /organisations/:
    get:
      tags:
        - Organisations
      summary: getAllOrganisations
      operationId: getAllOrganisations
      description: Retrieve a list of available organisations
      security:
        - DHBApiKey: []
        #- DHBOAuth2: [organisations_read]
      responses:
        '200':
          description: A list of all available organisations
          content: 
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Organisation'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /organisations/{id}:
    get:
      tags:
        - Organisations
      summary: getOrganisationDetails
      operationId: getOrganisationDetails
      description: Retrieve the details of the organisation.
      security:
        - DHBApiKey: []
        #- DHBOAuth2: [organisations_read]
      parameters:
        - name: id
          in: path
          description: Organisation ID to fetch information for.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Details of the organisation
          content: 
            application/json:
              schema:
                $ref: '#/components/schemas/OrganisationDetails'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /organisations/{id}/leagues:
    get:
      tags:
        - Organisations
      summary: getOrganisationLeagues
      operationId: getOrganisationLeagues
      description: Retrieve a list of available leagues within a given organisation
      security:
        - DHBApiKey: []
        #- DHBOAuth2: [organisations_read, leagues_read]
      parameters:
        - name: id
          in: path
          description: Organisation ID to fetch information for.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of all available leagues within a given organisation
          content: 
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ShortLeague'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /organisations/{id}/clubs:
    get:
      tags:
        - Organisations
      summary: getOrganisationClubs
      operationId: getOrganisationClubs
      description: Retrieve a list of available clubs within a given organisation
      security:
        - DHBApiKey: []
        #- DHBOAuth2: [organisations_read, clubs_read]
      parameters:
        - name: id
          in: path
          description: Organisation ID to fetch information for.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of all available clubs within a given organisation
          content: 
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ShortClub'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /organisations/{id}/umpires:
    get:
      tags:
        - Organisations
      summary: getOrganisationUmpires
      operationId: getOrganisationUmpires
      description: DRAFT ONLY - Retrieve a list of available umpires within a given organisation
      security:
        - DHBApiKey: []
        #- DHBOAuth2: [organisations_read, clubs_read]
      parameters:
        - name: id
          in: path
          description: Organisation ID to fetch information for.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of all available umpires within a given organisation
          content: 
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Umpire'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /organisations/{id}/venues:
    get:
      tags:
        - Organisations
      summary: getOrganisationVenues
      operationId: getOrganisationVenues
      description: Retrieve a list of venues for a given organisation
      security:
        - DHBApiKey: []
        #- DHBOAuth2: [organisations_read, clubs_read]
      parameters:
        - name: id
          in: path
          description: Organisation ID to fetch information for.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of venues within a given organisation
          content: 
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Venue'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /league/{id}:
    get:
      tags:
        - Leagues
      summary: getLeagueDetails
      operationId: getLeagueDetails
      description: Retrieve the details of a league.
      parameters:
        - name: id
          in: path
          description: League ID to fetch information for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: List of teams playing in a league.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/League'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
      security:
        - DHBApiKey: []
  /league/{id}/teams:
    get:
      tags:
        - Leagues
      summary: getTeamsByLeague
      operationId: getTeamsByLeague
      description: Retrieve the teams playing in a league.
      parameters:
        - name: id
          in: path
          description: League ID to fetch information for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: List of teams playing in a league.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ShortTeam'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
      security:
        - DHBApiKey: []
  /league/{id}/matches:
    get:
      tags:
        - Leagues
      summary: getMatchesByLeague
      operationId: getMatchesByLeague
      description: Retrieve the matches of a given league.
      parameters:
        - name: id
          in: path
          description: League ID to fetch information for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: List of matches for a league
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Match'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
      security:
        - DHBApiKey: []
  /league/{id}/standings:
    get:
      tags:
          - Leagues
      summary: getStandingsByLeague
      operationId: getStandingsByLeague
      description: Retrieve the standings for a league.
      security:
        - DHBApiKey: []
      parameters:
        - name: id
          in: path
          description: League ID to fetch information for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Detailed league standings
          content: 
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LeagueStandings'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /league/{id}/top-scorers:
    get:
      tags:
          - Leagues
      summary: getTopScorersByLeague
      operationId: getTopScorersByLeague
      description: Retrieve the table for a league.
      security:
        - DHBApiKey: []
      parameters:
        - name: id
          in: path
          description: League ID to fetch information for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Detailed top scorer table
          content: 
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/TopScorer'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /club/{id}:
    get:
      tags:
          - Clubs
      summary: getClubDetails
      operationId: getClubDetails
      description: Retrieve details of a club.
      security:
        - DHBApiKey: []
      parameters:
        - name: id
          in: path
          description: Club ID to fetch information for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: List of teams playing for a club.
          content: 
            application/json:
              schema:
                $ref: '#/components/schemas/Club'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /club/{id}/teams:
    get:
      tags:
          - Clubs
      summary: getTeamsByClub
      operationId: getTeamsByClub
      description: Retrieve the teams playing for a club.
      security:
        - DHBApiKey: []
      parameters:
        - name: id
          in: path
          description: Club ID to fetch information for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: List of teams playing for a club.
          content: 
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ShortTeam'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /club/{id}/locations:
    get:
      tags:
        - Clubs
      summary: getClubLocations
      operationId: getClubLocations
      description: Retrieve a list of available locations within a club
      security:
        - DHBApiKey: []
        #- DHBOAuth2: [clubs_read, locations_read]
      parameters:
        - name: id
          in: path
          description: Club ID to fetch information for.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: A list of all available locations within a given club
          content: 
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ShortLocation'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /venue/{id}:
    get:
      tags:
        - Venues
      summary: getVenueDetails
      operationId: getVenueDetails
      description: Retrieve the details for a venue.
      security:
        - DHBApiKey: [] 
      parameters:
        - name: id
          in: path
          description: Venue ID to fetch information for.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Detailed information for the venue.
          content: 
            application/json:
              schema:
                $ref: '#/components/schemas/Venue'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /team/{id}:
    get:
      tags:
        - Teams
      summary: getTeamDetails
      description: Retrieve the details for a team.
      operationId: getTeamDetails
      parameters:
        - name: id
          in: path
          description: Team ID to fetch information for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Detailed information for the team.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
      security:
        - DHBApiKey: []
  /match/{id}:
    get:
      tags:
        - Matches
      summary: getMatchDetails
      description: Retrieve a single match's details.
      operationId: getMatchDetails
      parameters:
        - name: id
          in: path
          description: Match ID to fetch information for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Details for a match
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MatchDetail'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
      security:
        - DHBApiKey: []
  /match/{id}/hometeam:
    get:
      tags:
        - Matches
      summary: getHomeTeamMatchDetails
      description: Retrieve a single match's home team's details.
      operationId: getHomeTeamMatchDetails
      parameters:
        - name: id
          in: path
          description: Match ID to fetch information for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Details of the home team for a match
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
      security:
        - DHBApiKey: []
  /match/{id}/awayteam:
    get:
      tags:
        - Matches
      summary: getAwayTeamMatchDetails
      description: Retrieve a single match's away team's details.
      operationId: getAwayTeamMatchDetails
      parameters:
        - name: id
          in: path
          description: Match ID to fetch information for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Details of the away team for a match
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Team'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
      security:
        - DHBApiKey: []
  /match/{id}/live:
    get:
      tags:
        - Matches
      summary: getLiveMatchDetails
      operationId: getLiveMatchDetails
      description: Retrieve a single match's live ticker details and high level status.
      security:
        - DHBApiKey: []
      parameters:
        - name: id
          in: path
          description: Match ID to fetch information for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Live Ticker details for a match
          content: 
            application/json:
              schema:
                  $ref: '#/components/schemas/LiveTicker'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /match/{id}/live/events:
    get:
      tags:
        - Matches
      summary: getLiveMatchEvents
      operationId: getLiveMatchEvents
      description: Provides a play-by-play event timeline for a current live game.
      security:
        - DHBApiKey: []
      parameters:
        - name: id
          in: path
          description: Match ID to fetch information for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Live Ticker details for a match
          content: 
            application/json:
              schema:
                  $ref: '#/components/schemas/LiveTickerEvent'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /match/{id}/live/time:
    get:
      tags:
        - Matches
      summary: getLiveMatchTime
      operationId: getLiveMatchTime
      description: Provides the current times of a match.
      security:
        - DHBApiKey: []
      parameters:
        - name: id
          in: path
          description: Match ID to fetch information for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Live Ticker match time details
          content: 
            application/json:
              schema:
                  $ref: '#/components/schemas/LiveTickerTime'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /match/{id}/livestream:
    get:
      tags:
        - Matches
      summary: getLivestream
      operationId: getLivestream
      description:  Provides key data for score and team for the use of live (TV) streams.
      security:
        - DHBApiKey: []
      parameters:
        - name: id
          in: path
          description: Match ID to fetch information for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Live stream events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/LiveStream'
  /match/{id}/umpires:
    get:
      tags:
        - Matches
      summary: getMatchUmpires
      operationId: getMatchUmpires
      description: Retrieve the umpires for a single match.
      security: 
        - DHBApiKey: []
      parameters: 
        - name: id
          in: path
          description: Match ID to fetch information for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Umpires for a match
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Umpire'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /match/{id}/articles:
    get:
      tags:
        - Matches
      summary: getMatchArticles
      operationId: getMatchArticles
      description: Retrieve news articles for a single match.
      security: 
        - DHBApiKey: []
      parameters: 
        - name: id
          in: path
          description: Match ID to fetch information for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: News articles for a match
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/NewsArticle'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /match/{id}/officials:
    patch:
      tags:
        - Matches
      summary: setMatchOfficials
      operationId: setMatchOffials
      description: DRAFT ONLY - Set the umpires and umpire observers for matches.
      security: 
        - DHBApiKey: []
      parameters:
        - name: id
          in: path
          description: Match ID to fetch information for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      requestBody:
        description: Update customer with properties to be changed
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/MatchOfficial'
      responses:
        '200':
          description: Umpires for a match
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Umpire'
        '400':
          description: Update of match officials failed
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /player/{id}:
    get:
      tags:
        - Players
      summary: getPlayerDetails
      operationId: getPlayerDetails
      description: Retrieve a single player's details.
      parameters:
        - name: id
          in: path
          description: Player ID to fetch information for.
          required: true
          style: simple
          explode: false
          schema:
            type: string
      responses:
        '200':
          description: Details for a player
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Player'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
      security:
        - DHBApiKey: []
  /staff/{id}:
    get:
      tags:
          - Staff
      summary: getStaffDetails
      operationId: getStaffDetails
      description: Retrieve a single staff member's details.
      security:
        - DHBApiKey: []
        #- DHBOAuth2: [players_read]
      parameters:
        - name: id
          in: path
          description: Staff ID to fetch information for.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Details for a staff
          content: 
            application/json:
              schema:
                  $ref: '#/components/schemas/StaffMember'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
  /umpire/{id}:
    get:
      tags:
        - Umpires
      summary: getUmpireDetails
      operationId: getUmpireDetails
      description: Retrieve a single umpire's details.
      security:
        - DHBApiKey: []
        #- DHBOAuth2: [players_read]
      parameters:
        - name: id
          in: path
          description: Umpire ID to fetch information for.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Details for a umpire
          content: 
            application/json:
              schema:
                  $ref: '#/components/schemas/Umpire'
        '401':
          description: Not authenticated
        '403':
          description: Access token does not have the required scope
components:
  schemas:
    Tag:
      type: object
      properties:
        name:
          type: string
          description: The tag itself.
          example: Bundesliga
    Contact:
      type: object
      properties:
        name:
          type: string
          description: The name of a contact person / venue / organisation..
          example: John Doe
        type:
          type: string
          description: The contact type
          example: ASSOCIATION
          enum:
            - DHB
            - ASSOCIATION
            - CLUB
        email:
          type: string
          description: The email address of the contact person / venue / organisation..
          format: email
          example: john.doe@organisation.com
        phone:
          type: string
          description: The phone number of the contact person / venue / organisation.
          format: phone
          example: +49 2161 30772-0
    Address:
      type: object
      properties:
        street:
          type: string
          description: The street address of the club / organisation.
          example: Musterstrasse
        street_number:
          type: string
          description: The street number of the club / organisation.
          example: 1a
        city:
          type: string
          description: The city where the club / organisation is located.
          example: Musterstadt
        state:
          type: string
          description: The state or province of the club / organisation.
          example: Musterbundesland
        postal_code:
          type: string
          description: The postal code or ZIP code of the club / organisation.
          example: '12345'
        country:
          type: string
          description: The country of the club / organisation.
          example: Germany
    Organisation:
      type: object
      properties:
        id:
          type: integer
          description: The ID of an organisation.
          format: int64
          example: 123
        parent_id:
          type: integer
          description: The ID of a parent organisation.
          format: int64
          example: 234
        name:
          type: string
          description: The name of an organisation.
          example: Musterorganisation
    OrganisationDetails:
      type: object
      properties:
        id:
          type: integer
          description: The ID of an organisation.
          format: int64
          example: 123
        parent_id:
          type: integer
          description: The ID of a parent organisation.
          format: int64
          example: 234
        name:
          type: string
          description: The name of an organisation.
          example: Musterorganisation
        address:
          $ref: '#/components/schemas/Address'
    Season:
      type: object
      properties:
        id:
          type: integer
          description: The ID of a season.
          format: int64
          example: 3
        name:
          type: string
          description: The name of a seson.
          example: Feld 2022/2023
        competition_type:
          type: string
          description: The type of the competition.
          example: OUTDOOR
          enum:
            - OUTDOOR
            - INDOOR
      description: Dinfasd
    League:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the league.
          format: int64
          example: 7
        name:
          type: string
          description: The name of the league.
          example: 1. Bundesliga Herren Feld
        abbreviation:
          type: string
          description: The abbreviation of the league.
          example: 1BLH
        age_group:
          type: string
          description: The age group for the league.
        start_date:
          type: string
          description: The start date of the league in ISO 8601.
          format: date
        end_date:
          type: string
          description: The end date of the league in ISO 8601 (UTC).
          format: date
# Next version:
#        umpire_appointment:
#          type: string
#          description: The process by which umpires are appointed.
#          example: ASSOCICATION
#          enum:
#            - ASSOCIATION
#            - MATCHLEVEL
#            - MATCHDAYLEVEL
        umpire_license:
          $ref: '#/components/schemas/UmpireLicenseType'
        umpire_classification:
          $ref: '#/components/schemas/UmpireClassification'
        season:
          type: array
          items:
            $ref: '#/components/schemas/Season'
        stages:
          type: array
          items:
            $ref: '#/components/schemas/LeagueStage'
    ShortLeague:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the league.
          format: int64
          example: 7
        name:
          type: string
          description: The name of the league.
          example: 1. Bundesliga Herren Feld
        abbreviation:
          type: string
          description: The abbreviation of the league.
          example: 1BLH
        age_group:
          type: string
          description: The age group for the league.
          example: 1. Herren
# Next version:
#        umpire_appointment:
#          type: string
#          description: The process by which umpires are appointed.
#          example: ASSOCICATION
#          enum:
#            - ASSOCIATION
#            - MATCHLEVEL
#            - MATCHDAYLEVEL
        umpire_license:
          $ref: '#/components/schemas/UmpireLicenseType'
        start_date:
          type: string
          description: The start date of the league in ISO 8601 (UTC).
          format: date
        end_date:
          type: string
          description: The end date of the league in ISO 8601 (UTC).
          format: date
        season:
          $ref: '#/components/schemas/Season'
    LeagueStage:
      type: object
      properties:
        name:
          type: string
          description: The name of the stage.
          example: Gruppenphase 1
        type:
          type: string
          description: The type of the stage.
          example: GROUP
          enum:
            - GROUP
            - PLAYOFFS
            - PLAYDOWN
    LeagueStandings:
      type: object
      properties:
        phase:
          type: string
          description: The phase of the league.
          example: GROUP
        group_name:
          type: string
          description: The group name for the set of standings.
          example: Staffel A
        table_entries:
          type: array
          items:
            $ref: '#/components/schemas/LeagueStandingsEntry'
    LeagueStandingsEntry:
      type: object
      properties:
        position:
          type: integer
          description: The position in the league table.
          example: 1
        team_name:
          type: string
          description: The name of the team.
          example: Muster HC
        team_logo:
          type: string
          description: The URL or path to the team's logo.
          format: uri
          example: https://magazin.hockey.de/path/to/clublogo.svg
        played_matches:
          type: integer
          description: The number of matches played.
          example: 10
        goals_for:
          type: integer
          description: The number of goals scored by the team.
          example: 52
        goals_against:
          type: integer
          description: The number of goals conceded by the team.
          example: 20
        goal_difference:
          type: integer
          description: The goal difference (goals scored minus goals conceded).
          example: 32
        points:
          type: integer
          description: The total points earned by the team.
          example: 21
        wins:
          type: integer
          description: The number of total wins by the team.
          example: 7
        draws:
          type: integer
          description: The number of total draws by the team.
          example: 7
        losses:
          type: integer
          description: The number of total losses by the team.
          example: 7
        shootout_wins:
          type: integer
          description: The number of total shootout wins by the team.
          example: 1
    TopScorer:
      type: object
      properties:
        position:
          type: string
          description: The position of the top scorer.
          example: 1
        name:
          type: string
          description: The name of the top scorer.
          example: Jane
        surname:
          type: string
          description: The surname of the top scorer.
          example: Doe
        team_name:
          type: string
          description: The name of the team the top scorer belongs to.
          example: Muster HC
        played_matches:
          type: integer
          description: The number of matches played by the top scorer.
          example: 10
        goals:
          type: integer
          description: The number of goals scored by the top scorer.
          example: 32
        player_image:
          type: string
          description: The URL or path to the image of the top scorer.
          format: uri
          example: https://magazin.hockey.de/path/to/playerimage.jpg
    Club:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the club.
          format: int64
          example: 456
        name:
          type: string
          description: The name of the club.
          example: Muster Hockey Club e.V.
        short_name:
          type: string
          description: The short name of the club.
          example: Muster HC
        abbreviation:
          type: string
          description: The abbreviation of the club.
          example: MHC
        organisation:
          $ref: '#/components/schemas/Organisation'
        logo:
          type: string
          description: The URL or path to the logo of the club.
          format: uri
          example: https://magazin.hockey.de/path/to/clublogo.svg
        contact:
          $ref: '#/components/schemas/Contact'
        address:
          $ref: '#/components/schemas/Address'
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
    ShortClub:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the club.
          format: int64
          example: 456
        name:
          type: string
          description: The name of the club.
          example: Muster Hockey Club e.V.
        short_name:
          type: string
          description: The short name of the club.
          example: Muster HC
        abbreviation:
          type: string
          description: The abbreviation of the club.
          example: MHC
        logo:
          type: string
          description: The URL or path to the logo of the club.
          format: uri
          example: https://magazin.hockey.de/path/to/clublogo.svg
    ShortLocation:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the location.
          format: int64
          example: 789
        name:
          type: string
          description: The name of the location.
          example: Sparkassenpark
        image:
          type: string
          description: The URL or path to the image of the location.
          format: uri
          example: https://magazin.hockey.de/path/to/locationimage.jpg
    Venue:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the venue.
          format: int64
          example: 789
        parent_id:
          type: string
          description: The ID of a parent organisation.
          example: 234
        name:
          type: string
          description: The name of the venue.
          example: Sparkassenpark Mönchengladbach
        short_name:
          type: string
          description: The short name of the venue.
          example: Sparkassenpark
        image:
          type: string
          description: The URL or path to the image of the venue.
          format: uri
          example: https://magazin.hockey.de/path/to/venueimage.jpg
        pitches:
          type: array
          items:
            $ref: '#/components/schemas/Pitch'
        address:
          $ref: '#/components/schemas/Address'
        location:
          $ref: '#/components/schemas/MapLocation'
        contacts:
          type: array
          items:
            $ref: '#/components/schemas/Contact'
    MapLocation:
      type: object
      properties:
        url: 
          type: string
          description: The URL to the map location
          example: https://maps.app.goo.gl/nGaZm5uFT99LWpTQ7
    Pitch:
      type: object
      properties:
        name:
          type: string
          description: The name of the pitch.
          example: Pitch 1
    ShortTeam:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the team.
          format: int64
          example: 102
        club_id:
          type: integer
          description: The ID of the club the team belongs to.
          format: int64
          example: 456
        league_id:
          type: integer
          description: The ID of the league the team belongs to.
          format: int64
          example: 7
        name:
          type: string
          description: The name of the team.
          example: 1. Herren Muster HC
        short_name:
          type: string
          description: The short name of the team.
          example: MHC
        age_group:
          type: string
          description: The age group of the team.
          example: Erwachsene
        image:
          type: string
          description: The URL or path to the image of the team.
          format: uri
          example: https://magazin.hockey.de/path/to/teamimage.jpg
        uniform:
          $ref: '#/components/schemas/TeamUniform'
        social_networks:
          type: array
          description: The social networks associated with the team.
          items:
            $ref: '#/components/schemas/SocialNetwork'
    Team:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the team.
          format: int64
          example: 102
        club_id:
          type: integer
          description: The ID of the club the team belongs to.
          format: int64
          example: 456
        leagueId:
          type: integer
          description: The ID of the league the team is associated with.
          format: int64
          example: 7
        name:
          type: string
          description: The name of the team.
          example: 1. Herren Muster HC
        shortName:
          type: string
          description: The short name of the team.
          example: MHC
        ageGroup:
          type: string
          description: The age group of the team.
          example: Erwachsene
        image:
          type: string
          description: The URL or path to the image of the team.
          format: uri
          example: https://magazin.hockey.de/path/to/teamimage.jpg
        socialNetworks:
          type: array
          description: The social networks associated with the team.
          items:
            $ref: '#/components/schemas/SocialNetwork'
        players:
          type: array
          description: The squad of players of the team.
          items:
            $ref: '#/components/schemas/ShortPlayer'
        staff:
          type: array
          description: The staff members associated with the team.
          items:
            $ref: '#/components/schemas/StaffMember'
    TeamUniform:
      type: object
      properties:
        shirt:
          type: string
          description: The color of the shirt.
          example: '#ff9900'
        shorts:
          type: string
          description: The color of the shorts.
          example: '#ff9900'
        socks:
          type: string
          description: The color of the socks.
          example: '#ff9900'
        goalkeeper:
          type: string
          description: The color of the goalkeeper shirt.
          example: '#ff9900'
    SocialNetwork:
      type: object
      properties:
        name:
          type: string
          description: The name of the social network.
          example: Instagram
        url:
          type: string
          description: The URL of the team's profile on the social network.
          format: uri
          example: https://instagram.com/1herrenmusterhc
    Player:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the player.
          format: int64
          example: 231292
        name:
          type: string
          description: The name of the player.
          example: John
        surname:
          type: string
          description: The surname of the player.
          example: Doe
        teams:
          type: array
          items:
            $ref: '#/components/schemas/TeamPlayerDetails'
    ShortPlayer:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the player.
          format: int64
          example: 231292
        name:
          type: string
          description: The name of the player.
          example: John
        surname:
          type: string
          description: The surname of the player.
          example: Doe
        shirt_number:
          type: string
          description: The shirt number of the player.
          example: '5'
        captain:
          type: boolean
          description: Indication if the player is a captain.
          example: true
        goalkeeper:
          type: boolean
          description: Indication if the player is a goalkeeper.
          example: true
        substitute_goalkeeper:
          type: boolean
          description: Indication if the player is a substitute goalkeeper.
          example: true
        passportId:
          type: string
          description: The Passport ID of the player.
          example: 231292
        is_starting_position:
          type: boolean
          description: Whether the player is part of the starting line-up.
          example: true
        position:
          type: string
          description: The position of the player.
          example: Defender
    TeamPlayerDetails:
      type: object
      properties:
        team:
          $ref: '#/components/schemas/ShortTeam'
        shirt_number:
          type: integer
          nullable: true
          description: The shirt number of the player.
          example: '5'
        position:
          type: string
          description: The position of the player.
          example: Defender
        player_image:
          type: string
          description: The URL or path to the image of the top scorer.
          format: uri
          example: https://magazin.hockey.de/path/to/playerimage.jpg
        social_networks:
          type: array
          description: The social networks associated with the team.
          items:
            $ref: '#/components/schemas/SocialNetwork'
    StaffMember:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the staff member.
          format: int64
          example: 823920
        name:
          type: string
          description: The name of the staff member.
          example: Jane
        surname:
          type: string
          description: The surname of the staff member.
          example: Doe
        role_title:
          type: string
          description: The title or role of the staff member.
          example: Trainer*in
    Umpire:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the umpire.
          format: int64
          example: 102032
        legacy_id:
          type: string
          description: "The legacy ID of the umpire. Note: deprecation on the roadmap. Transition to id as soon as possible."
          example: 823920
        name:
          type: string
          description: The name of the umpire.
          example: John
        surname:
          type: string
          description: The surname of the umpire.
          example: Doe
        license:
          type: array
          items:
            $ref: '#/components/schemas/UmpireLicense'
    UmpireLicense:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the umpire license.
          format: int64
          example: 1439
        number:
          type: string
          description: The license number of the umpire.
          example: C123672
        license_type:
          $ref: '#/components/schemas/UmpireLicenseType'
        classification:
          $ref: '#/components/schemas/UmpireClassification'
        valid_from:
          type: string
          description: The valid from date of the passport in ISO 8601.
          format: date
        valid_to:
          type: string
          description: The valid to date of the passport in ISO 8601.
          format: date
    UmpireLicenseType:
      type: object
      properties:
        name:
          type: string
          description: The current license type of an umpire.
          example: DHB E3 – Umpire
    UmpireClassification:
      type: object
      properties:
        name:
          type: string
          description: The current classification of an umpire, only applicable for some licenses.
          example: E3A - Regionalliga
    Match:
      type: object
      properties:
        pushback:
          type: string
          description: The pushback date and time of the match in ISO 8601, in UTC.
          format: date-time
          example: '2023-06-22T14:30:00+00:00'
        id:
          type: integer
          description: The ID of the match.
          format: int64
          example: 12032
        stage:
          type: string
          description: The stage of the match.
          example: PLAYOFFS
          enum:
            - GROUP
            - PLAYOFFS
            - PLAYDOWN
        group_name:
          type: string
          description: The stage of the match.
          example: Hinrunde
          enum:
            - Hinrunde
            - Rückrunde
        status:
          type: string
          description: The status of the match.
          example: WARMUP
          enum:
            - UPCOMING
            - WARMUP
            - INPROGRESS
            - ENDED
            - COMPLETED
            - OFFICIAL
            - CANCELLED
            - ABANDONED
        score_home:
          type: integer
          description: The current live or final home score.
          format: int64
          example: 2
        score_away:
          type: integer
          description: he current live or final away score.
          format: int64
          example: 1
        home_team:
          $ref: '#/components/schemas/ShortTeam'
        away_team:
          $ref: '#/components/schemas/ShortTeam'
        location:
          $ref: '#/components/schemas/ShortLocation'
        pitch:
          $ref: '#/components/schemas/Pitch'
        umpire1:
          $ref: '#/components/schemas/Umpire'
        umpire2:
          $ref: '#/components/schemas/Umpire'
        video_umpire:
          $ref: '#/components/schemas/Umpire'
    MatchPeriodScores:
      type: object
      properties:
        sequence:
          type: integer
          description: >-
            Sequential number of the results to reflect quarters, halftimes or
            additional phases such as shootout.
          format: int64
          example: 4
        type:
          type: string
          description: The type of the period.
          example: regular OR shootout
        home_score:
          type: integer
          description: The home score for the particular period.
          format: int64
          example: 2
        away_score:
          type: integer
          description: The away score for the particular period.
          format: int64
          example: 1
    MatchDetail:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the match.
          format: int64
          example: 12032
        stage:
          type: string
          description: The stage of the match.
          example: PLAYOFFS
          enum:
            - GROUP
            - PLAYOFFS
            - PLAYDOWN
        periods:
          type: integer
          description: The number of periods of the match.
          example: 4
        periods_minutes:
          type: integer
          description: The number of minutes per period.
          example: 15
        status:
          type: string
          description: The status of the match.
          example: WARMUP
          enum:
            - UPCOMING
            - WARMUP
            - INPROGRESS
            - ENDED
            - COMPLETED
            - OFFICIAL
            - CANCELLED
            - ABANDONED
        score_home:
          type: integer
          format: int64
          description: The score of the hometeam.
          example: 3
        score_away:
          type: integer
          format: int64
          description: The score of the awayteam.
          example: 2
        pushback:
          type: string
          description: The pushback date and time of the match in ISO 8601, in UTC.
          format: date-time
          example: '2023-06-22T14:30:00+00:00'
        home_team_id:
          type: integer
          description: The ID of the home team.
          format: int64
          example: 102
        away_team_id:
          type: integer
          description: The ID of the away team.
          format: int64
          example: 102
        location:
          $ref: '#/components/schemas/ShortLocation'
        pitch:
          $ref: '#/components/schemas/Pitch'
        umpire_license:
          $ref: '#/components/schemas/UmpireLicenseType'
        umpire_classification:
          $ref: '#/components/schemas/UmpireClassification'
    MatchOfficial:
      type: object
      properties:
        id:
          type: integer
          description: The ID of the person.
          format: int64
          example: 231292
        role:
          type: string
          description: Role of the official in the match
          example: UMPIRE
          enum:
            - UMPIRE
            - UMPIRE_OBSERVER
            - UMPIRE_VIDEO
            - JUDGE
    NewsArticle:
      type: object
      properties:
        url:
          type: string
          description: The deep link to a news article
          example: https://verband.hockey.de/articles/news-article-slug
        headline:
          type: string
          description: The headline of the news article
          example: "Matchday 12: An Outlook"
        image:
          type: string
          description: The URL or path to the image of the news article.
          format: uri
          example: https://magazin.hockey.de/path/to/news_article_image.png
    LiveStream:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the livestream
          example: 57732
        period:
          oneOf:
            - type: integer
            - type: string
          nullable: true
          description: Current match period
          example: 3
        elapsed_match:
          type: integer
          nullable: true
          description: Elapsed time of the match
          example: 32
        time_left:
          type: integer
          nullable: true
          description: Time left in the match
          example: 28
        elapsed_period:
          type: integer
          nullable: true
          description: Elapsed time in the period
          example: 2
        period_left:
          type: integer
          nullable: true
          description: Time left in the period
          example: 13
        score_home:
          type: integer
          nullable: true
          description: Home team score
          example: 2
        score_away:
          type: integer
          nullable: true
          description: Away team score
          example: 1
        ht_score_home:
          type: integer
          nullable: true
          description: Halftime home team score
          example: 1
        ht_score_away:
          type: integer
          nullable: true
          description: Halftime away team score
          example: 1
        shootout_score_home:
          type: integer
          nullable: true
          description: Shootout home team score
          example: null
        shootout_score_away:
          type: integer
          nullable: true
          description: Shootout away team score
          example: null
    LiveTicker:
      type: object
      properties:
        status:
          type: string
          description: The current status of the live ticker.
          example: In progress
        phase:
          type: string
          description: The current phase of the match live ticker.
          example: Q3
        home_team:
          $ref: '#/components/schemas/ShortTeam'
        away_team:
          $ref: '#/components/schemas/ShortTeam'
        period_scores:
          type: array
          items:
            $ref: '#/components/schemas/MatchPeriodScores'
        umpire1:
          $ref: '#/components/schemas/Umpire'
        umpire2:
          $ref: '#/components/schemas/Umpire'
    LiveTickerEvent:
      type: object
      properties:
        type:
          type: string
          description: The main type of the event
          enum: [Periods, Goals, Cards, Penalty Stroke, Penalty Shootout, Penalty Corner, Shoot, Comment, Strokes]
        subtype:
          type: string
          description: The subtype of the event.
        type_commentary:
          type: string
          description: A live commentary for the event.
        period:
          type: integer
          description: The quarter or period in which the event occurred.
        timestamp:
          type: string
          description: The timestamp of the event in ISO 8601, in UTC.
          format: date-time
          example: '2023-06-22T14:30:00+00:00'
        team:
          $ref: '#/components/schemas/ShortTeam'
        player:
          $ref: '#/components/schemas/ShortPlayer'
        staff:
          $ref: '#/components/schemas/StaffMember'
    LiveTickerTime:
      type: object
      properties:
        elapsed_match:
          type: integer
          description: The elapsed and current minute of the match.
          example: 48
        elapsed_period:
          type: integer
          description: The current minute of the period.
          example: 3
  parameters:
    key:
      name: key
      in: query
      description: The API key parameter
      required: true
      style: form
      explode: true
      schema:
        type: string
    token:
      name: token
      in: query
      description: The token parameter
      required: true
      style: form
      explode: true
      schema:
        type: string
  securitySchemes:
    DHBApiKey:
      type: apiKey
      name: X-API-KEY
      in: header