From 8f5da4fd26c94b107eb47ae3c56f176712196e4f Mon Sep 17 00:00:00 2001 From: John Buck Date: Fri, 10 Jan 2025 09:11:42 -0500 Subject: [PATCH 01/11] Allow clar reply to multiple teams and/or groups Instead of allowing only a single team or all teams to receive the reply to clarification (or an announcement from the admin or judges), allow multiple teams and/or groups to receive the reply/announcement. There are several use cases for this: 1) teams that are located in a specific area of the floor or a different room. Q:"Where are our printouts?" Reply: "There is a problem with the printer in your area, and it will be fixed shortly" 2) a group in a specific region: Q:"Why arent we getting balloons?" Reply to group: "The balloon printer in your region is out of paper and it is being fixed" --- Contest_API.md | 28 +++++++++++++++------------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/Contest_API.md b/Contest_API.md index 123a0a37..e50b58c0 100644 --- a/Contest_API.md +++ b/Contest_API.md @@ -1797,19 +1797,21 @@ The following endpoints are associated with clarification messages: Properties of clarification message objects: -| Name | Type | Description -| :------------- | :------ | :---------- -| id | ID | Identifier of the clarification. -| from\_team\_id | ID ? | Identifier of [team](#teams) sending this clarification request, `null` iff a clarification sent by jury. -| to\_team\_id | ID ? | Identifier of the [team](#teams) receiving this reply, `null` iff a reply to all teams or a request sent by a team. -| reply\_to\_id | ID ? | Identifier of clarification this is in response to, otherwise `null`. -| problem\_id | ID ? | Identifier of associated [problem](#problems), `null` iff not associated to a problem. -| text | string | Question or reply text. -| time | TIME | Time of the question/reply. -| contest\_time | RELTIME | Contest time of the question/reply. - -Note that at least one of `from_team_id` and `to_team_id` has to be -`null`. That is, teams cannot send messages to other teams. +| Name | Type | Description +| :------------- | :--------------- | :---------- +| id | ID | Identifier of the clarification. +| from\_team\_id | ID ? | Identifier of [team](#teams) sending this clarification request, `null` iff a clarification sent by jury. +| to\_team\_ids | array of ID ? | Identifiers of the [team(s)](#teams) receiving this reply, `null` iff a reply to all teams or a request sent by a team. +| to\_group\_ids | array of ID ? | Identifiers of the [ group(s)](#groups) receiving this reply, `null` iff a reply to all teams or a request sent by a team. +| reply\_to\_id | ID ? | Identifier of clarification this is in response to, otherwise `null`. +| problem\_id | ID ? | Identifier of associated [problem](#problems), `null` iff not associated to a problem. +| text | string | Question or reply text. +| time | TIME | Time of the question/reply. +| contest\_time | RELTIME | Contest time of the question/reply. + +Note that at least one of `from_team_id` and `to_team_ids` or `to_group_ids` has to be +`null`. That is, teams cannot send messages to other teams or groups. In order to send a reply +to all teams, both `to_team_ids` and `to_group_ids` must be `null`. #### Modifying clarifications From 8e78f3f484e5225e8ac06388ab9a6970138c4752 Mon Sep 17 00:00:00 2001 From: John Buck Date: Fri, 10 Jan 2025 09:34:21 -0500 Subject: [PATCH 02/11] Tried to make description a bit clearer The description of the restrictions on from_team_id and to_team_ids and to_groups_ids was (is still?) ambiguous. Maybe still need better wording. --- Contest_API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Contest_API.md b/Contest_API.md index e50b58c0..debbf475 100644 --- a/Contest_API.md +++ b/Contest_API.md @@ -1809,7 +1809,7 @@ Properties of clarification message objects: | time | TIME | Time of the question/reply. | contest\_time | RELTIME | Contest time of the question/reply. -Note that at least one of `from_team_id` and `to_team_ids` or `to_group_ids` has to be +Note that at least one of `from_team_id` and (`to_team_ids` or `to_group_ids`) has to be `null`. That is, teams cannot send messages to other teams or groups. In order to send a reply to all teams, both `to_team_ids` and `to_group_ids` must be `null`. From 83433db71d03cc1cec387c489f87ac742bf0e93a Mon Sep 17 00:00:00 2001 From: John Buck Date: Fri, 31 Jan 2025 08:38:26 -0500 Subject: [PATCH 03/11] Clarify the meaning of to_team_ids and to_group_ids Indicate that the recipient list is the UNION of the to_team_ids and to_group_ids. Fix examples to use new properties. Fix up some awkward wording. --- Contest_API.md | 20 +++++++++----------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/Contest_API.md b/Contest_API.md index debbf475..ae222829 100644 --- a/Contest_API.md +++ b/Contest_API.md @@ -1800,7 +1800,7 @@ Properties of clarification message objects: | Name | Type | Description | :------------- | :--------------- | :---------- | id | ID | Identifier of the clarification. -| from\_team\_id | ID ? | Identifier of [team](#teams) sending this clarification request, `null` iff a clarification sent by jury. +| from\_team\_id | ID ? | Identifier of the [team](#teams) sending this clarification request, `null` iff a clarification is sent by the jury. | to\_team\_ids | array of ID ? | Identifiers of the [team(s)](#teams) receiving this reply, `null` iff a reply to all teams or a request sent by a team. | to\_group\_ids | array of ID ? | Identifiers of the [ group(s)](#groups) receiving this reply, `null` iff a reply to all teams or a request sent by a team. | reply\_to\_id | ID ? | Identifier of clarification this is in response to, otherwise `null`. @@ -1809,9 +1809,7 @@ Properties of clarification message objects: | time | TIME | Time of the question/reply. | contest\_time | RELTIME | Contest time of the question/reply. -Note that at least one of `from_team_id` and (`to_team_ids` or `to_group_ids`) has to be -`null`. That is, teams cannot send messages to other teams or groups. In order to send a reply -to all teams, both `to_team_ids` and `to_group_ids` must be `null`. +The recipients of a clarification are the union of `to_team_ids` and `to_group_ids`. If `from_team_id` and both `to_team_ids` and `to_group_ids` are `null`, then the clarification is sent to all teams. Note that if `from_team_id` is not `null`, then both `to_team_ids` and `to_group_ids` must be `null`. That is, teams cannot send messages to other teams or groups. #### Modifying clarifications @@ -1834,12 +1832,12 @@ exceptions: choose to include or exclude the `problem_id`. - The `post_clar` capability only has access to `POST`. `id`, `time`, and `contest_time` must not be provided. When submitting from a - team account, `to_team_id` must not be provided; `from_team_id` may be + team account, `to_team_ids` and `to_group_ids` must not be provided; `from_team_id` may be provided but then must match the ID of the team associated with the request. When submitting from a judge account, `from_team_id` must not be provided. In either case the server will determine an `id` and the current `time` and `contest_time`. -- The `proxy_clar` capability only has access to `POST`. `id`, `to_team_id`, +- The `proxy_clar` capability only has access to `POST`. `id`, `to_team_ids`, `to_group_ids`, `time`, and `contest_time` must not be provided. `from_team_id` must be provided. The server will determine an `id` and the current `time` and `contest_time`. @@ -1851,7 +1849,7 @@ The request must fail with a 4xx error code if any of the following happens: - A required property is missing. - A property that must not be provided is provided. -- The supplied problem, from\_team, to\_team, or reply\_to cannot be found or are +- The supplied problem, `from_team`, `to_team_ids`, `to_group_ids`, or `reply_to` cannot be found or are not visible to the client that's submitting. - The provided `id` already exists or is otherwise not acceptable. @@ -1869,7 +1867,7 @@ Request: Returned data: ```json -[{"id":"wf2017-1","from_team_id":null,"to_team_id":null,"reply_to_id":null,"problem_id":null, +[{"id":"wf2017-1","from_team_id":null,"to_team_ids":null,"to_group_ids":null,"reply_to_id":null,"problem_id":null, "text":"Do not touch anything before the contest starts!","time":"2014-06-25T11:59:27.543+01","contest_time":"-0:15:32.457"} ] ``` @@ -1881,9 +1879,9 @@ Request: Returned data: ```json -[{"id":"1","from_team_id":"34","to_team_id":null,"reply_to_id":null,"problem_id":null, +[{"id":"1","from_team_id":"34","to_team_ids":null,"to_group_ids":null,"reply_to_id":null,"problem_id":null, "text":"May I ask a question?","time":"2017-06-25T11:59:27.543+01","contest_time":"1:59:27.543"}, - {"id":"2","from_team_id":null,"to_team_id":"34","reply_to_id":"1","problem_id":null, + {"id":"2","from_team_id":null,"to_team_ids":["34"],"reply_to_id":"1","problem_id":null, "text":"Yes you may!","time":"2017-06-25T11:59:47.543+01","contest_time":"1:59:47.543"} ] ``` @@ -1896,7 +1894,7 @@ Returned data: ```json [{"id":"1","from_team_id":"34","text":"May I ask a question?","time":"2017-06-25T11:59:27.543+01","contest_time":"1:59:27.543"}, - {"id":"2","to_team_id":"34","reply_to_id":"1","text":"Yes you may!","time":"2017-06-25T11:59:47.543+01","contest_time":"1:59:47.543"} + {"id":"2","to_team_ids":["34"],"reply_to_id":"1","text":"Yes you may!","time":"2017-06-25T11:59:47.543+01","contest_time":"1:59:47.543"} ] ``` From 0f7915d9578731e5d6ef746a3a770235a0878dd8 Mon Sep 17 00:00:00 2001 From: John Buck Date: Fri, 31 Jan 2025 08:43:22 -0500 Subject: [PATCH 04/11] Update Filtering description example The filtering example happened to use to_team_id for clarifications as an example. This has to change to to_team_ids. Also changed the example to include multiple teams --- Contest_API.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Contest_API.md b/Contest_API.md index ae222829..0ced6a47 100644 --- a/Contest_API.md +++ b/Contest_API.md @@ -594,8 +594,8 @@ Note that all results returned from endpoints: Endpoints that return a JSON array must allow filtering on any property with type ID (except the `id` property) by passing it as a query argument. For example, clarifications can be filtered on the -recipient by passing `to_team_id=X`. To filter on a `null` value, -pass an empty string, i.e. `to_team_id=`. It must be possible to +recipient by passing `to_team_ids=X,Y`. To filter on a `null` value, +pass an empty string, i.e. `to_team_ids=`. It must be possible to filter on multiple different properties simultaneously, with the meaning that all conditions must be met (they are logically `AND`ed). Note that filtering on any other property, including property with the type From b79b203f95b4e84ce5005c7912089175d3f16d08 Mon Sep 17 00:00:00 2001 From: John Buck Date: Mon, 3 Feb 2025 13:19:27 -0500 Subject: [PATCH 05/11] Changed an example for clars Removed extra space (cosmetic). Added a couple of team ID's and a Group ID to one of the clarification examples. --- Contest_API.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Contest_API.md b/Contest_API.md index 0ced6a47..0b40ed29 100644 --- a/Contest_API.md +++ b/Contest_API.md @@ -1802,7 +1802,7 @@ Properties of clarification message objects: | id | ID | Identifier of the clarification. | from\_team\_id | ID ? | Identifier of the [team](#teams) sending this clarification request, `null` iff a clarification is sent by the jury. | to\_team\_ids | array of ID ? | Identifiers of the [team(s)](#teams) receiving this reply, `null` iff a reply to all teams or a request sent by a team. -| to\_group\_ids | array of ID ? | Identifiers of the [ group(s)](#groups) receiving this reply, `null` iff a reply to all teams or a request sent by a team. +| to\_group\_ids | array of ID ? | Identifiers of the [group(s)](#groups) receiving this reply, `null` iff a reply to all teams or a request sent by a team. | reply\_to\_id | ID ? | Identifier of clarification this is in response to, otherwise `null`. | problem\_id | ID ? | Identifier of associated [problem](#problems), `null` iff not associated to a problem. | text | string | Question or reply text. @@ -1894,7 +1894,7 @@ Returned data: ```json [{"id":"1","from_team_id":"34","text":"May I ask a question?","time":"2017-06-25T11:59:27.543+01","contest_time":"1:59:27.543"}, - {"id":"2","to_team_ids":["34"],"reply_to_id":"1","text":"Yes you may!","time":"2017-06-25T11:59:47.543+01","contest_time":"1:59:47.543"} + {"id":"2","to_team_ids":["34","57","69"],"to_group_ids":["1336"], "reply_to_id":"1","text":"Yes you may!","time":"2017-06-25T11:59:47.543+01","contest_time":"1:59:47.543"} ] ``` From c11b4a3baf0cb0336a61afba94ed526242d7e726 Mon Sep 17 00:00:00 2001 From: John Buck Date: Fri, 14 Feb 2025 15:16:09 -0500 Subject: [PATCH 06/11] Clarify how sending to all teams is determined. Made it clear, that from_team_id, to_team_ids AND to_group_ids must be null (or empty) to send to all teams. I think that makes it clear that if either to_team_ids or to_group_ids is non-null(empty), then the message is not sent to all teams, rather, only those teams --- Contest_API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Contest_API.md b/Contest_API.md index 0b40ed29..45c1a617 100644 --- a/Contest_API.md +++ b/Contest_API.md @@ -1809,7 +1809,7 @@ Properties of clarification message objects: | time | TIME | Time of the question/reply. | contest\_time | RELTIME | Contest time of the question/reply. -The recipients of a clarification are the union of `to_team_ids` and `to_group_ids`. If `from_team_id` and both `to_team_ids` and `to_group_ids` are `null`, then the clarification is sent to all teams. Note that if `from_team_id` is not `null`, then both `to_team_ids` and `to_group_ids` must be `null`. That is, teams cannot send messages to other teams or groups. +The recipients of a clarification are the union of `to_team_ids` and `to_group_ids`. A clarification is sent to all teams if `from_team_id` is null and the union of `to_team_ids` and `to_group_ids` is empty. Note that if `from_team_id` is not `null`, then both `to_team_ids` and `to_group_ids` must be `null`. That is, teams cannot send messages to other teams or groups. #### Modifying clarifications From 56eea495c9fae709b25ac9a59e258ecdba4d5f60 Mon Sep 17 00:00:00 2001 From: John Buck Date: Fri, 14 Feb 2025 15:25:31 -0500 Subject: [PATCH 07/11] Added to_group_ids to clarifications access restrictions Change to_team_id to to_team_ids and add to_group_ids --- Contest_Control_System_Requirements.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Contest_Control_System_Requirements.md b/Contest_Control_System_Requirements.md index 3fd210bc..5265de21 100644 --- a/Contest_Control_System_Requirements.md +++ b/Contest_Control_System_Requirements.md @@ -1007,7 +1007,7 @@ The following access restrictions must apply to GETs on the API endpoints: thawed. - For clients with the `public` role the `/clarifications` endpoint must only contain replies from the jury to all teams, that is, messages where both - `from_team_id` and `to_team_id` are `null`. For clients with the `team` role + `from_team_id`, `to_team_ids` and `to_group_ids` are `null`. For clients with the `team` role the `/clarifications` endpoint must only contain their own clarifications (sent or received) and public clarifications. - For clients with the `public` role the `/awards` and `/scoreboard` endpoints From b724def3f72b4d00c4f128fd6620defa4cabea75 Mon Sep 17 00:00:00 2001 From: John Buck Date: Fri, 14 Feb 2025 15:29:13 -0500 Subject: [PATCH 08/11] More consistent wording for clarifications --- Contest_API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Contest_API.md b/Contest_API.md index 45c1a617..8904beda 100644 --- a/Contest_API.md +++ b/Contest_API.md @@ -1809,7 +1809,7 @@ Properties of clarification message objects: | time | TIME | Time of the question/reply. | contest\_time | RELTIME | Contest time of the question/reply. -The recipients of a clarification are the union of `to_team_ids` and `to_group_ids`. A clarification is sent to all teams if `from_team_id` is null and the union of `to_team_ids` and `to_group_ids` is empty. Note that if `from_team_id` is not `null`, then both `to_team_ids` and `to_group_ids` must be `null`. That is, teams cannot send messages to other teams or groups. +The recipients of a clarification are the union of `to_team_ids` and `to_group_ids`. A clarification is sent to all teams if `from_team_id`, `to_team_ids` and `to_group_ids` are null. Note that if `from_team_id` is not `null`, then both `to_team_ids` and `to_group_ids` must be `null`. That is, teams cannot send messages to other teams or groups. #### Modifying clarifications From d8c5e9b8b0b948c65cbeebd2d81197c10480f9ee Mon Sep 17 00:00:00 2001 From: John Buck Date: Mon, 14 Jul 2025 07:36:30 -0400 Subject: [PATCH 09/11] Change filtering example to use non-array of ID The Filtering example was changed to use a non-array of ID to simplify implementation. A statement was added to clarify the handling of properties of type ID ? (that is, you can not filter on a property of type ID if it is not present). --- Contest_API.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Contest_API.md b/Contest_API.md index 8904beda..eb181901 100644 --- a/Contest_API.md +++ b/Contest_API.md @@ -593,9 +593,10 @@ Note that all results returned from endpoints: Endpoints that return a JSON array must allow filtering on any property with type ID (except the `id` property) by passing it as a -query argument. For example, clarifications can be filtered on the -recipient by passing `to_team_ids=X,Y`. To filter on a `null` value, -pass an empty string, i.e. `to_team_ids=`. It must be possible to +query argument. For example, clarifications can be filtered on the sender +by passing `from_team_id=X`. To filter on a `null` value, +pass an empty string, i.e. `from_team_id=`. Properties of type ID ? can only +be filtered on if the property is present. It must be possible to filter on multiple different properties simultaneously, with the meaning that all conditions must be met (they are logically `AND`ed). Note that filtering on any other property, including property with the type @@ -686,7 +687,7 @@ The set of properties listed must always support [referential integrity](#referential-integrity), i.e. if a property with a ID value referring to some type of object is present the endpoint representing that type of object (and its ID property) must also be present. E.g. if -`group_ids` is listed among the properties in the `team` endpoint object, that +`groups` is listed among the properties in the `team` endpoint object, that means that there must be an endpoint object with type `groups` containing at least `ID` in its properties. From d5bdadbd840af5261be4086f76929b3078d18631 Mon Sep 17 00:00:00 2001 From: John Buck Date: Mon, 14 Jul 2025 14:51:50 -0400 Subject: [PATCH 10/11] Remove statement of ID ? in filtering. To be added with new issue and PR. --- Contest_API.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Contest_API.md b/Contest_API.md index eb181901..df175802 100644 --- a/Contest_API.md +++ b/Contest_API.md @@ -595,8 +595,7 @@ Endpoints that return a JSON array must allow filtering on any property with type ID (except the `id` property) by passing it as a query argument. For example, clarifications can be filtered on the sender by passing `from_team_id=X`. To filter on a `null` value, -pass an empty string, i.e. `from_team_id=`. Properties of type ID ? can only -be filtered on if the property is present. It must be possible to +pass an empty string, i.e. `from_team_id=`. It must be possible to filter on multiple different properties simultaneously, with the meaning that all conditions must be met (they are logically `AND`ed). Note that filtering on any other property, including property with the type From fdd6d20fdd9076d1c62a185f45c52fe0627c5c5e Mon Sep 17 00:00:00 2001 From: John Buck Date: Mon, 14 Jul 2025 16:28:07 -0400 Subject: [PATCH 11/11] Revert unintentional change Revert change: groups should be group_ids. It inadvertently got changed in a previous commit. --- Contest_API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Contest_API.md b/Contest_API.md index df175802..655141ec 100644 --- a/Contest_API.md +++ b/Contest_API.md @@ -686,7 +686,7 @@ The set of properties listed must always support [referential integrity](#referential-integrity), i.e. if a property with a ID value referring to some type of object is present the endpoint representing that type of object (and its ID property) must also be present. E.g. if -`groups` is listed among the properties in the `team` endpoint object, that +`group_ids` is listed among the properties in the `team` endpoint object, that means that there must be an endpoint object with type `groups` containing at least `ID` in its properties.