diff --git a/openapi/components/schemas/poll.md b/openapi/components/schemas/poll.md
new file mode 100644
index 0000000..bba9cf7
--- /dev/null
+++ b/openapi/components/schemas/poll.md
@@ -0,0 +1,2 @@
+A `Poll` is the core model of the application.
+A `Poll` exposes a list of `Proposal`s, and `Participant`s may individually give each `Proposal` a `Grade`. (in a `Ballot`)
diff --git a/openapi/components/schemas/poll.yaml b/openapi/components/schemas/poll.yaml
index 5583138..18566fe 100644
--- a/openapi/components/schemas/poll.yaml
+++ b/openapi/components/schemas/poll.yaml
@@ -1,5 +1,6 @@
 type: object
-
+description:
+  $ref: 'poll.md'
 properties:
   id:
     type: string
@@ -30,7 +31,9 @@ properties:
       so you should consider the proposals carefully and with gumption.
   proposals:
     type: array
-    description: The proposals being voted in a poll.
+    description: >
+      The proposals being judged by the participants in a poll.
+      It makes no sense to have less than two proposals in a poll.
     minItems: 2
     maxItems: 20
     items: