diff --git a/openapi/components/schemas/mention.yaml b/openapi/components/schemas/mention.yaml
index bee9229..7e6afa3 100644
--- a/openapi/components/schemas/mention.yaml
+++ b/openapi/components/schemas/mention.yaml
@@ -9,3 +9,7 @@ properties:
     type: string
     description: Unique but short name of the mention, like "Excellent" or "To reject".
     example: Excellent
+  description:
+    type: string
+    description: An optional description of the mention
+    example: In this poll, the mention "To reject" disqualifies the proposal.
diff --git a/openapi/components/schemas/participant.yaml b/openapi/components/schemas/participant.yaml
index ef6eadf..5ed65e3 100644
--- a/openapi/components/schemas/participant.yaml
+++ b/openapi/components/schemas/participant.yaml
@@ -5,6 +5,10 @@ properties:
     description: A unique identifier
     example: JtRm05yjMAuFCI2uwnFp
     readOnly: true
+  description:
+    type: string
+    description: An optional description of the participant
+    example: John Doe
   has-participed:
     type: boolean
     description: True if the participant already participed to the poll, False otherwise
@@ -12,7 +16,7 @@ properties:
   poll-id:
     type: string
     description: The identifier of the poll that the participant participates on.
-    example: '1jDe1e5eF_IkaYPuoIYX'
+    example: 1jDe1e5eF_IkaYPuoIYX
   mail:
     type: object
     description: The mail that will eventually created at the creation of the participant (not kept in memory).
diff --git a/openapi/components/schemas/poll.yaml b/openapi/components/schemas/poll.yaml
index 1a5b805..ae663cc 100644
--- a/openapi/components/schemas/poll.yaml
+++ b/openapi/components/schemas/poll.yaml
@@ -2,13 +2,17 @@ type: object
 properties:
   id:
     type: string
-    description: 'A unique identifier'
-    example: '1jDe1e5eF_IkaYPuoIYX'
+    description: A unique identifier
+    example: 1jDe1e5eF_IkaYPuoIYX
     readOnly: true
   title:
     type: string
-    example: 'What project should our neighbourhood invest in for the next year?'
-    description: 'The title of the poll'
+    example: What project should our neighbourhood invest in for the next year?
+    description: The title of the poll
+  description:
+    type: string
+    description: A description of the poll
+    example: 
   proposals:
     type: array
     description: The proposals being voted in a poll.
diff --git a/openapi/components/schemas/proposal.yaml b/openapi/components/schemas/proposal.yaml
index 65fb4a5..a6d7124 100644
--- a/openapi/components/schemas/proposal.yaml
+++ b/openapi/components/schemas/proposal.yaml
@@ -14,3 +14,7 @@ properties:
     description: The ballots received by this proposal.
     items:
       $ref: ./ballot.yaml
+  description:
+    type: string
+    description: An optional description of the proposal
+    example: This school would welcome 500 pupils.