diff --git a/doc/specs/schemas/Flair.yaml b/doc/specs/schemas/Flair.yaml
new file mode 100644
index 0000000..130545f
--- /dev/null
+++ b/doc/specs/schemas/Flair.yaml
@@ -0,0 +1,3 @@
+type: string
+
+description: See [available flair list and images](https://github.com/lichess-org/lila/tree/master/public/flair)
diff --git a/doc/specs/schemas/PuzzleAndGame.yaml b/doc/specs/schemas/PuzzleAndGame.yaml
index 9600641..ef6fcd2 100644
--- a/doc/specs/schemas/PuzzleAndGame.yaml
+++ b/doc/specs/schemas/PuzzleAndGame.yaml
@@ -28,7 +28,7 @@ properties:
             color:
               type: string
             flair:
-              type: string
+              $ref: './Flair.yaml'
             id:
               type: string
             name:
diff --git a/doc/specs/schemas/Team.yaml b/doc/specs/schemas/Team.yaml
index 5a7b83f..0ecdae0 100644
--- a/doc/specs/schemas/Team.yaml
+++ b/doc/specs/schemas/Team.yaml
@@ -1,21 +1,55 @@
 type: object
+
 properties:
   id:
     type: string
-    example: coders
   name:
     type: string
-    example: Coders
   description:
     type: string
-    example: "There are 10 kinds of people in the world: those who understand binary, and the others.\r\n\r\nIf you want to join the team, prove (briefly) that you can code in the request message!"
-  open:
-    type: boolean
-    example: false
+  leader:
+    $ref: './LightUser.yaml'
+  flair:
+    $ref: './Flair.yaml'
   leaders:
     type: array
     items:
       $ref: './LightUser.yaml'
   nbMembers:
     type: integer
-    example: 3129
+  open:
+    type: boolean
+  joined:
+    type: boolean
+  requested:
+    type: boolean
+
+required:
+  - id
+  - name
+
+example:
+  {
+    "id": "lichess-swiss",
+    "name": "Lichess Swiss",
+    "description": "The official Lichess Swiss team. We organize regular swiss tournaments for all to join.",
+    "flair": "food-drink.cheese-wedge",
+    "leader": {
+        "flair": "activity.lichess",
+        "id": "lichess",
+        "name": "Lichess",
+        "patron": true
+    },
+    "leaders": [
+        {
+            "flair": "activity.lichess",
+            "id": "lichess",
+            "name": "Lichess",
+            "patron": true
+        }
+    ],
+    "nbMembers": 487629,
+    "open": true,
+    "joined": false,
+    "requested": false
+  }
diff --git a/doc/specs/schemas/User.yaml b/doc/specs/schemas/User.yaml
index 7b75770..978237d 100644
--- a/doc/specs/schemas/User.yaml
+++ b/doc/specs/schemas/User.yaml
@@ -10,8 +10,7 @@ properties:
   perfs:
     $ref: './Perfs.yaml'
   flair:
-    type: string
-    example: nature.water-wave
+    $ref: './Flair.yaml'
   createdAt:
     type: integer
     format: int64