docs: review the ballots

openapi/components/schemas/ballot.md

@@ -0,0 +1,8 @@
+
+A Ballot holds a single Grade given by a Participant to a Proposal of a Poll.
+
+A Ballot is a single Judgment.
+
+For security purposes, Ballots are journalized and may not be updated or deleted individually.
+If you change your mind, emit a new Ballot.
+It will be the responsibility of the Poll Tallier to only consider the latest ballot when there are multiple.

openapi/components/schemas/ballot.yaml

@@ -1,5 +1,8 @@
 type: object
+description:
+  $ref: ballot.md
 properties:
+  # UUIDv4, here ?
   id:
     type: integer
     description: A unique identifier
@@ -8,7 +11,11 @@ properties:
   grade:
     type: integer
     description: >
-      One grade of the grading defined when creating the poll.
+      Index of a grade of the poll's grading.
       Zero (0) means the worst grade, and it goes upwards from there,
       up to the size of the grading, minus one.
     example: 2
+  pollId:
+    type: string
+  userId:
+    type: string