Skip to content

Allow multiple teams and groups in clarification destinations #193

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 8 commits into
base: master
Choose a base branch
from
Open

Allow multiple teams and groups in clarification destinations #193

Changes from 4 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
8f5da4f
Allow clar reply to multiple teams and/or groups
johnbrvc Jan 10, 2025
8e78f3f
Tried to make description a bit clearer
johnbrvc Jan 10, 2025
83433db
Clarify the meaning of to_team_ids and to_group_ids
johnbrvc Jan 31, 2025
0f7915d
Update Filtering description example
johnbrvc Jan 31, 2025
b79b203
Changed an example for clars
johnbrvc Feb 3, 2025
c11b4a3
Clarify how sending to all teams is determined.
johnbrvc Feb 14, 2025
56eea49
Added to_group_ids to clarifications access restrictions
johnbrvc Feb 14, 2025
b724def
More consistent wording for clarifications
johnbrvc Feb 14, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
42 changes: 21 additions & 21 deletions Contest_API.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This suggests a real change: instead of just requiring filtering on properies with ID type, we would now also require filtering on properties with type array of ID.

That adds a bunch of extra complexity like: if you specify to_team_ids=X,Y, do you want to match entries where to_team_ids is exactly [X,Y], contains either X or Y, has [X,Y] as a subset, or... I don't think we should go there, and simply change this example to something else than clarifications.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "OR" of all the to_team_ids (or to_group_ds) makes the most sense. eg. "Any of these teams"

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't think we should go there, and simply change this example to something else than clarifications.

I agree, we should not add the requirement that you allow filtering on any property of type array of ID.

On a related note, when we say "any property with type ID" do we mean to include properties of type ID ?. We should clarify.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Discussed at meeting. We will not introduce filter on arrays as part of this change, but might later.

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
Expand Down Expand Up @@ -1797,19 +1797,19 @@ 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.
| Name | Type | Description
| :------------- | :--------------- | :----------
| 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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| 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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As specified right now, nulls in one (but not both) of to_team_ids and to_group_ids is either illegal (because it must be null iff reply to all), (or it requires the non-null value to actually specify all teams), or it could be interpreted as the union of something and all, i.e. all. I don't think either of those are what we want.

It should be allowed to specify only to_team_ids (i.e. having to_group_ids as null) and that should mean that only the teams listed will get the message. Similar for only to_group_ids,

| 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.
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

Expand All @@ -1832,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`.
Expand All @@ -1849,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.

Expand All @@ -1867,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"}
]
```
Expand All @@ -1879,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,
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would be good to have an example where there are multiple team IDs and/or a group ID.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree. Will update.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Updated an example to include 3 team ids and a group id in a response.

"text":"Yes you may!","time":"2017-06-25T11:59:47.543+01","contest_time":"1:59:47.543"}
]
```
Expand All @@ -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_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"}
]
```

Expand Down