From 325935751e4cb26e5ba391e3583bdbc0b71800a9 Mon Sep 17 00:00:00 2001
From: camodotgg <camodotgg@gmail.com>
Date: Mon, 23 Mar 2026 17:13:24 -0700
Subject: [PATCH] description parity with current docs

---
 openapi.yaml | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/openapi.yaml b/openapi.yaml
index a6c2691..01f4c58 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -666,24 +666,29 @@ components:
       properties:
         uuid:
           type: string
-          description: User UUID without dashes.
+          description: User's UUID
         nickname:
           type: string
+          description: User's nickname
         roleType:
           type: integer
+          description: User's role type
         eloRate:
           type:
             - integer
             - 'null'
+          description: "User's Elo rate. It is `null` if the user hasn't finished placement matches."
         eloRank:
           type:
             - integer
             - 'null'
+          description: User's Elo rank
         country:
           type:
             - string
             - 'null'
           pattern: ^[a-z]{2}$
+          description: "User's country code in lowercased [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1) format."
     Achievement:
       type: object
       required:
@@ -696,22 +701,28 @@ components:
       properties:
         id:
           type: string
+          description: Achievement Identifier
         date:
           $ref: '#/components/schemas/Date'
+          description: Timestamp of when the achievement was earned
         data:
           type: array
           items:
             type: string
+          description: Additional data array
         level:
           type: integer
+          description: Level of achievement
         value:
           type:
             - integer
             - 'null'
+          description: "Contains the current player's progression of the achievement. It is `null` if the achievement is not a leveling one."
         goal:
           type:
             - integer
             - 'null'
+          description: "Next level goal of the achievement. It is `null` if the achievement is at max level or not a leveling one."
     MatchSeed:
       type: object
       required:
@@ -725,22 +736,27 @@ components:
           type:
             - string
             - 'null'
+          description: "Seed id if it's a ranked filtered seed. This is not the seed number. It is `null` if the seed is not filtered."
         overworld:
           type:
             - string
             - 'null'
+          description: "Overworld structure type of the seed. It is `null` if the seed is not filtered."
         nether:
           type:
             - string
             - 'null'
+          description: "Bastion remnants type of the seed. It is `null` if the seed is not filtered."
         endTowers:
           type: array
           items:
             type: integer
+          description: "The [zero related tower](./assets/img/endTowers.png) heights of in The End dimension. It is an empty array if the seed is not filtered."
         variations:
           type: array
           items:
             type: string
+          description: Noticeable variations of the seed. It is an empty array if the seed is not filtered.
     WeeklyRaceSeed:
       type: object
       required:
@@ -937,6 +953,7 @@ components:
           type:
             - string
             - 'null'
+          description: "Winner's UUID. It is `null` if the match was a draw."
         time:
           $ref: '#/components/schemas/Time'
     MatchRank:
@@ -949,10 +966,12 @@ components:
           type:
             - integer
             - 'null'
+          description: Record rank of the match's season
         allTime:
           type:
             - integer
             - 'null'
+          description: Record rank of all-time
     MatchChange:
       type: object
       required:
@@ -962,14 +981,17 @@ components:
       properties:
         uuid:
           type: string
+          description: UUID of player
         change:
           type:
             - integer
             - 'null'
+          description: "Amount of changed Elo rate. It is `null` if the match is a placement."
         eloRate:
           type:
             - integer
             - 'null'
+          description: "Elo rate of the player. It is `null` if the match is a placement."
     MatchVod:
       type: object
       required:
@@ -979,10 +1001,13 @@ components:
       properties:
         uuid:
           type: string
+          description: UUID of VOD owner. Only players with public stream activated will be included.
         url:
           type: string
+          description: VOD URL of this match
         startsAt:
           $ref: '#/components/schemas/Date'
+          description: "VOD start date. You can get a timestamp with `{date} - {vod[].startsAt}`"
     CompletionEntry:
       type: object
       required:
@@ -991,8 +1016,10 @@ components:
       properties:
         uuid:
           type: string
+          description: Player uuid of completion
         time:
           $ref: '#/components/schemas/Time'
+          description: Match time of completion
     TimelineEntry:
       type: object
       required:
@@ -1002,10 +1029,13 @@ components:
       properties:
         uuid:
           type: string
+          description: Player uuid of timeline
         time:
           $ref: '#/components/schemas/Time'
+          description: Match time of timeline
         type:
           type: string
+          description: Identifier of timeline
     MatchInfo:
       type: object
       required:
@@ -1033,6 +1063,7 @@ components:
           type:
             - string
             - 'null'
+          description: "Match completions category. Default is `ANY`"
         gameMode:
           type:
             - string
@@ -1048,6 +1079,7 @@ components:
           items:
             $ref: '#/components/schemas/UserProfile'
         seed:
+          description: "Seed ID if it's a ranked filtered seed. This is not the seed number. It is `null` if the seed is not filtered."
           oneOf:
             - $ref: '#/components/schemas/MatchSeed'
             - type: 'null'
@@ -1055,8 +1087,10 @@ components:
           $ref: '#/components/schemas/MatchResult'
         forfeited:
           type: boolean
+          description: Whether the match has no completions
         decayed:
           type: boolean
+          description: Whether the match has decayed
         rank:
           $ref: '#/components/schemas/MatchRank'
         changes:
@@ -1079,10 +1113,13 @@ components:
           type:
             - string
             - 'null'
+          description: Special tag of this match. Used to get matches by tag.
         replayExist:
           type: boolean
+          description: Whether the match replay exists in the server
         beginner:
           type: boolean
+          description: Whether beginner mode is enabled in the match.
         botSource:
           type:
             - string