From efed66a31eb72a04b541a5b7fa158dfd49be6f3b Mon Sep 17 00:00:00 2001 From: domi41 Date: Thu, 24 Sep 2020 12:43:51 +0200 Subject: [PATCH] feat: decouple poll properties This will probably be handy with path responses, since some have requirements and others don't --- .../components/schemas/poll-properties.yaml | 77 +++++++++++++++++ openapi/components/schemas/poll.yaml | 84 +------------------ 2 files changed, 81 insertions(+), 80 deletions(-) create mode 100644 openapi/components/schemas/poll-properties.yaml diff --git a/openapi/components/schemas/poll-properties.yaml b/openapi/components/schemas/poll-properties.yaml new file mode 100644 index 0000000..5aa484e --- /dev/null +++ b/openapi/components/schemas/poll-properties.yaml @@ -0,0 +1,77 @@ +id: + readOnly: true + type: string + description: | + A unique identifier for the poll. + That identifier has a fixed length of 20 alphanumerical characters, + including some special characters like `_`. + pattern: '[0-9a-fA-F_]{20}' + example: 1jDe1e5eF_IkaYPuoIYX +# uuid: +# readOnly: true +# type: string +# format: uuid +# # pattern is defined for implementations that don't understand format: uuid +# pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}' +# description: > +# A Universally Unique IDentifier for the poll. (version 4) +# example: bb788552-727d-470b-827e-d7796248d293 +subject: + type: string + description: The subject of the poll. + example: What project should our neighbourhood invest in for the next year? +description: + type: string + description: > + A lengthy description of the poll. + In here should be stated the constitutive details of the poll, + whether it is informative or imperative for example. + example: > + This poll will help decide which projects get the most attention and budget + so you should consider the proposals carefully and with gumption. +proposals: + type: array + description: > + The proposals being judged by the participants of the poll. + It makes no sense to have less than two proposals in a poll. + minItems: 2 + maxItems: 20 + items: + $ref: ./proposal.yaml +grades: + type: array + description: | + The grades that participants may give to each proposal. + The grades should be **non-ambiguously ordinal**, + ie. their ranking should be obvious to everyone. + + #### Good examples + - DISAPPROVED, APPROVED + - TO REJECT, POOR, PASSABLE, GOOD, VERY GOOD, EXCELLENT + - BORING, ENTERTAINING, FUN, AMAZING (to be discussed) + + #### Bad examples + - LOUSY, MEDIOCRE, OKAY, GOOD, FINE, PEACHY + - BORING, BEAUTIFUL, FUN, MAGNIFICIENT + minItems: 2 + maxItems: 10 + items: + $ref: ./grade.yaml +participants: + type: array + description: | + The participants that are allowed to participate in the poll. + That property is ignored if `restrict_participants` is `false`. + + --- + + Or should this be the list of the participants of the poll? + items: + $ref: ./participant.yaml +user-id: + type: string + description: Organizer id. If not given, a dummy user is created. +restrict-participants: + type: boolean + description: True if anyone can participate in this poll, False otherwise. + example: false diff --git a/openapi/components/schemas/poll.yaml b/openapi/components/schemas/poll.yaml index a3d59a9..ba52f3f 100644 --- a/openapi/components/schemas/poll.yaml +++ b/openapi/components/schemas/poll.yaml @@ -2,83 +2,7 @@ type: object description: $ref: 'poll.md' properties: - id: - readOnly: true - type: string - description: | - A unique identifier for the poll. - That identifier has a fixed length of 20 alphanumerical characters, - including some special characters like `_`. - pattern: '[0-9a-fA-F_]{20}' - example: 1jDe1e5eF_IkaYPuoIYX -# uuid: -# readOnly: true -# type: string -# format: uuid -# # pattern is defined for implementations that don't understand format: uuid -# pattern: '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}' -# description: > -# A Universally Unique IDentifier for the poll. (version 4) -# example: bb788552-727d-470b-827e-d7796248d293 - subject: - type: string - description: The subject of the poll. - example: What project should our neighbourhood invest in for the next year? - description: - type: string - description: > - A lengthy description of the poll. - In here should be stated the constitutive details of the poll, - whether it is informative or imperative for example. - example: > - This poll will help decide which projects get the most attention and budget - so you should consider the proposals carefully and with gumption. - proposals: - type: array - description: > - The proposals being judged by the participants of the poll. - It makes no sense to have less than two proposals in a poll. - minItems: 2 - maxItems: 20 - items: - $ref: ./proposal.yaml - grades: - type: array - description: | - The grades that participants may give to each proposal. - The grades should be **non-ambiguously ordinal**, - ie. their ranking should be obvious to everyone. - - #### Good examples - - DISAPPROVED, APPROVED - - TO REJECT, POOR, PASSABLE, GOOD, VERY GOOD, EXCELLENT - - BORING, ENTERTAINING, FUN, AMAZING (to be discussed) - - #### Bad examples - - LOUSY, MEDIOCRE, OKAY, GOOD, FINE, PEACHY - - BORING, BEAUTIFUL, FUN, MAGNIFICIENT - minItems: 2 - maxItems: 10 - items: - $ref: ./grade.yaml - participants: - type: array - description: | - The participants that are allowed to participate in the poll. - That property is ignored if `restrict_participants` is `false`. - - --- - - Or should this be the list of the participants of the poll? - items: - $ref: ./participant.yaml - user-id: - type: string - description: Organizer id. If not given, a dummy user is created. - restrict-participants: - type: boolean - description: True if anyone can participate in this poll, False otherwise. - example: false -# required: -# - title -# - proposals + $ref: 'poll-properties.yaml' +required: + - title + - proposals