From 5c34b8a96f337c34bece5bfe68de97968f0f96ff Mon Sep 17 00:00:00 2001 From: John Buck Date: Tue, 2 Dec 2025 11:11:35 -0500 Subject: [PATCH 1/2] Revise readme for changes since 2023-06 Updated the readme to reflect functional and non-functional changes, including new properties and breaking changes in various endpoints since 2023-06. --- readme.md | 115 ++++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 107 insertions(+), 8 deletions(-) diff --git a/readme.md b/readme.md index cfbf5802..2cde11d7 100644 --- a/readme.md +++ b/readme.md @@ -28,14 +28,113 @@ This is the draft of some future version of the CCS specification. These are the main changes made since the `2023-06` version: -- Changed type of `penalty_time` in contest endpoint from `integer` to `RELTIME`. -- Changed type of time related properties in scoreboard endpoint from `integer` to `RELTIME`. -- Added `current` to judgements endpoint. -- Added `country_subdivision` and `country_subdivision_flag` to organizations endpoint. -- Added `memory_limit`, `output_limit`, `code_limit` to problems endpoint -- Renamed `team_clar` capability to `post_clar` -- Added `post_comment` capability -- Added `simplified_judgement_type_id` to `judgement` and `judgement_type` endpoints +**Functional Changes** + 1. Add support for **post\_comment** capability (posting commentary) + 2. contests EP + 1. Change **penalty\_time** from integer minutes to **RELTIME** (breaking change) + 3. judgement-types EP + 1. Add property **simplified\_judgement\_type\_id** (ID ?) + 4. problems EP + 1. Add property **memory\_limit** (integer) + 2. Add property **output\_limit** (integer) + 3. Add property **code\_limit** (integer) + 4. Add property **attachments** (array of FILE ?) + 5. organizations EP + 1. Add property **country\_subdivision** (string ?) + 2. Add property **country\_subdivision\_flag** (array of FILE ?) + 6. submissions EP + 1. Add property **account\_id** (ID ?) + 2. Made **team\_id** optional (ID ?) + 7. judgements EP + 1. Add property **current** (boolean ?) + 2. Add property **simplified\_judgement\_type\_id** (ID ?) + 8. clarifications EP + 1. Teams must have the **post\_clar** capability to post a clarification (previously was **team\_clar**) (breaking change) + 2. Rule change about what properties may be specified in a **POST** when the **post\_clar** capability is present. (breaking change) + 3. Remove **to\_team\_id** and replace it with **to\_team\_ids** and **to\_group\_ids** to allow broader targeting of destination team(s). (breaking change) + 9. awards EP + 1. Added new rules for honors, high-honors and highest-honors + 10. commentary EP + 1. Add ability to modify (post) a comment + 11. scoreboard EP + 1. Change **score.total\_time** from **integer** to **RELTIME** (breaking change) + 2. Change **score.time** from **integer** to **RELTIME ?** (breaking change) + 3. Change **problems.time** from **integer** to **RELTIME** (breaking change) + 12. **Note:** Event feed notifications containing the above objects must also be updated as indicated. + +**Non-functional Changes** (documentation) + 1. Entire Document + 1. Change all endpoint URLs to be correctly relative by removing prefix slashes. This applies to all endpoints in the document. + 2. Change [IETF.org](http://IETF.org) RFC references to use current website. + 2. General design principles + 1. Endpoint URLs + 1) Clarify that **baseurl** must end in a slash. + 2) Add examples and reference to RFC + 2. JSON property types + 1) Description of *Identifiers* clarified. + 2) Clarify no meaning is implied by the order of objects in arrays. + 3) Added note to href + 4) Added property **tag** (array of string) to file reference objects (FILE) along with a description of how it may be used. (eg. hints such as light or dark for images) + 3. Capabilities + 1) Changed description of **post\_clar** + 2) Added capability **post\_comment** for posting commentary + 3) Removed TODO about adding capabilities for team view and awards. + 4) Added warning about capabilities being fleeting + 3. Interface specification + 1. Types of endpoints + 1) Wording change (groups-\>types) + 2) Added statement about judgment **current** property may change + 2. Filtering + 1) Specify explicitly that nullable ID’s can be filtered on + 3. Access + 1) Updated examples (already backpatched to 2023-06) + 4. Contests + 1) Clarify wording for **countdown\_pause\_time** and description below + 2) Change type of penalty\_time to **RELTIME** + 3) Change examples to use **RELTIME** for **penalty\_time** + 5. Judgement Types + 1) Added description of new property **simplified\_judgement\_type** + 2) Added example for **simplified\_judgement\_type** + 6. Languages + 1) Change gcc example to include **\-o a.out** + 2) **ERROR** in example for **“id”: “cpp”** \- can not use gcc to build c++ programs \- should be fixed + 7. Problems + 1) Added descriptions for new properties **memory\_limit**, **output\_limit**, **code\_limit, attachments** + 2) Clarify maximum score for problems in **score** type contests. + 3) Clarify that the **rgb** property should not include an alpha channel. + 4) Fixed examples to include newly added properties + 5) Fixed JSON formatting error in example. + 8. Organizations + 1) Added descriptions for new country subdivision properties + 2) Updated examples to include country subdivisions + 9. Teams + 1) Update description of **id** property to no longer include suggestion of using the **id** as the seat number since **label** does that. + 2) Remove specific mention of no implied order ID’s in an array for **team\_ids** and **group\_ids** since it’s covered in the *General Design Principles*. + 3) Allow HLS video (application/vnd.apple.mpegurl) for **video**, **desktop, webcam** and **reaction** properties. + 10. State + 1) Minor wording changes that affect nothing + 11. Submissions + 1) Added text indicating why the **id** should be a small number + 2) Add description of new property **account\_id**. + 3) Clarify what a missing **team\_id** property implies. + 4) Spelling fixes (entrypoint \-\> entry point) + 5) Clarify that the **data** property for the **files** array is a *base64 encoded zip* file + 12. Judgements + 1) Add description of new properties: **current, simplified\_judgement\_type** + 13. Clarifications + 1) Change **team\_clar** capability to **post\_clar** capability + 2) Added description of how the new **to\_team\_ids** and **to\_group\_ids** properties should be used. + 3) Provide more detail on broadcast clarification responses + 4) Consistently use “judges” instead of “jury” in descriptions. + 5) Update rules for **post\_clar** capability (which fields may be specified by what roles, etc). + 14. Awards + 1) Added descriptions of new “Bill” rules awards for honors, high-honors, highest-honors + 15. Commentary + 1) Add description of how to post commentary + 16. Scoreboard + 1) Change types for **score.total\_time**, **score.time**, **problems.time** to **RELTIMEs** + 2) Update examples to use **RELTIME**s in changed properties + ## References From 2124d397a72475923d0c269a28c0be77ee9099f4 Mon Sep 17 00:00:00 2001 From: Jaap Eldering Date: Mon, 8 Dec 2025 23:33:50 +0100 Subject: [PATCH 2/2] Try to shorten the changelog a bit: - Remove items from non-functional changes that can be inferred, like updated examples for added/changed properties. - Moved `tag` property added to `FILE` object to main changes. --- readme.md | 179 ++++++++++++++++++++++-------------------------------- 1 file changed, 74 insertions(+), 105 deletions(-) diff --git a/readme.md b/readme.md index 2cde11d7..1b359218 100644 --- a/readme.md +++ b/readme.md @@ -28,112 +28,81 @@ This is the draft of some future version of the CCS specification. These are the main changes made since the `2023-06` version: -**Functional Changes** - 1. Add support for **post\_comment** capability (posting commentary) - 2. contests EP - 1. Change **penalty\_time** from integer minutes to **RELTIME** (breaking change) - 3. judgement-types EP - 1. Add property **simplified\_judgement\_type\_id** (ID ?) - 4. problems EP - 1. Add property **memory\_limit** (integer) - 2. Add property **output\_limit** (integer) - 3. Add property **code\_limit** (integer) - 4. Add property **attachments** (array of FILE ?) - 5. organizations EP - 1. Add property **country\_subdivision** (string ?) - 2. Add property **country\_subdivision\_flag** (array of FILE ?) - 6. submissions EP - 1. Add property **account\_id** (ID ?) - 2. Made **team\_id** optional (ID ?) - 7. judgements EP - 1. Add property **current** (boolean ?) - 2. Add property **simplified\_judgement\_type\_id** (ID ?) - 8. clarifications EP - 1. Teams must have the **post\_clar** capability to post a clarification (previously was **team\_clar**) (breaking change) - 2. Rule change about what properties may be specified in a **POST** when the **post\_clar** capability is present. (breaking change) - 3. Remove **to\_team\_id** and replace it with **to\_team\_ids** and **to\_group\_ids** to allow broader targeting of destination team(s). (breaking change) - 9. awards EP - 1. Added new rules for honors, high-honors and highest-honors - 10. commentary EP - 1. Add ability to modify (post) a comment - 11. scoreboard EP - 1. Change **score.total\_time** from **integer** to **RELTIME** (breaking change) - 2. Change **score.time** from **integer** to **RELTIME ?** (breaking change) - 3. Change **problems.time** from **integer** to **RELTIME** (breaking change) - 12. **Note:** Event feed notifications containing the above objects must also be updated as indicated. + 1. Add support for **post\_comment** capability (posting commentary) + 2. Add property **tag** (array of string) to file reference objects (FILE) along with a description of how it may be used. (eg. hints such as light or dark for images) + 3. contests endpoint + 1. Change **penalty\_time** from integer minutes to **RELTIME** (breaking change) + 4. judgement-types endpoint + 1. Add property **simplified\_judgement\_type\_id** (ID ?) + 5. problems endpoint + 1. Add property **memory\_limit** (integer) + 2. Add property **output\_limit** (integer) + 3. Add property **code\_limit** (integer) + 4. Add property **attachments** (array of FILE ?) + 6. organizations endpoint + 1. Add property **country\_subdivision** (string ?) + 2. Add property **country\_subdivision\_flag** (array of FILE ?) + 7. submissions endpoint + 1. Add property **account\_id** (ID ?) + 2. Made **team\_id** optional (ID ?) + 8. judgements endpoint + 1. Add property **current** (boolean ?) + 2. Add property **simplified\_judgement\_type\_id** (ID ?) + 9. clarifications endpoint + 1. Teams must have the **post\_clar** capability to post a clarification (previously was **team\_clar**) (breaking change) + 2. Rule change about what properties may be specified in a **POST** when the **post\_clar** capability is present. (breaking change) + 3. Remove **to\_team\_id** and replace it with **to\_team\_ids** and **to\_group\_ids** to allow broader targeting of destination team(s). (breaking change) + 10. awards endpoint + 1. Added new ICPC world finals specific rules for honors, high-honors and highest-honors + 11. commentary endpoint + 1. Add ability to modify (post) a comment + 12. scoreboard endpoint + 1. Change **score.total\_time** from **integer** to **RELTIME** (breaking change) + 2. Change **score.time** from **integer** to **RELTIME ?** (breaking change) + 3. Change **problems.time** from **integer** to **RELTIME** (breaking change) + 13. **Note:** Event feed notifications containing the above objects must also be updated as indicated. -**Non-functional Changes** (documentation) - 1. Entire Document - 1. Change all endpoint URLs to be correctly relative by removing prefix slashes. This applies to all endpoints in the document. - 2. Change [IETF.org](http://IETF.org) RFC references to use current website. - 2. General design principles - 1. Endpoint URLs - 1) Clarify that **baseurl** must end in a slash. - 2) Add examples and reference to RFC - 2. JSON property types - 1) Description of *Identifiers* clarified. - 2) Clarify no meaning is implied by the order of objects in arrays. - 3) Added note to href - 4) Added property **tag** (array of string) to file reference objects (FILE) along with a description of how it may be used. (eg. hints such as light or dark for images) - 3. Capabilities - 1) Changed description of **post\_clar** - 2) Added capability **post\_comment** for posting commentary - 3) Removed TODO about adding capabilities for team view and awards. - 4) Added warning about capabilities being fleeting - 3. Interface specification - 1. Types of endpoints - 1) Wording change (groups-\>types) - 2) Added statement about judgment **current** property may change - 2. Filtering - 1) Specify explicitly that nullable ID’s can be filtered on - 3. Access - 1) Updated examples (already backpatched to 2023-06) - 4. Contests - 1) Clarify wording for **countdown\_pause\_time** and description below - 2) Change type of penalty\_time to **RELTIME** - 3) Change examples to use **RELTIME** for **penalty\_time** - 5. Judgement Types - 1) Added description of new property **simplified\_judgement\_type** - 2) Added example for **simplified\_judgement\_type** - 6. Languages - 1) Change gcc example to include **\-o a.out** - 2) **ERROR** in example for **“id”: “cpp”** \- can not use gcc to build c++ programs \- should be fixed - 7. Problems - 1) Added descriptions for new properties **memory\_limit**, **output\_limit**, **code\_limit, attachments** - 2) Clarify maximum score for problems in **score** type contests. - 3) Clarify that the **rgb** property should not include an alpha channel. - 4) Fixed examples to include newly added properties - 5) Fixed JSON formatting error in example. - 8. Organizations - 1) Added descriptions for new country subdivision properties - 2) Updated examples to include country subdivisions - 9. Teams - 1) Update description of **id** property to no longer include suggestion of using the **id** as the seat number since **label** does that. - 2) Remove specific mention of no implied order ID’s in an array for **team\_ids** and **group\_ids** since it’s covered in the *General Design Principles*. - 3) Allow HLS video (application/vnd.apple.mpegurl) for **video**, **desktop, webcam** and **reaction** properties. - 10. State - 1) Minor wording changes that affect nothing - 11. Submissions - 1) Added text indicating why the **id** should be a small number - 2) Add description of new property **account\_id**. - 3) Clarify what a missing **team\_id** property implies. - 4) Spelling fixes (entrypoint \-\> entry point) - 5) Clarify that the **data** property for the **files** array is a *base64 encoded zip* file - 12. Judgements - 1) Add description of new properties: **current, simplified\_judgement\_type** - 13. Clarifications - 1) Change **team\_clar** capability to **post\_clar** capability - 2) Added description of how the new **to\_team\_ids** and **to\_group\_ids** properties should be used. - 3) Provide more detail on broadcast clarification responses - 4) Consistently use “judges” instead of “jury” in descriptions. - 5) Update rules for **post\_clar** capability (which fields may be specified by what roles, etc). - 14. Awards - 1) Added descriptions of new “Bill” rules awards for honors, high-honors, highest-honors - 15. Commentary - 1) Add description of how to post commentary - 16. Scoreboard - 1) Change types for **score.total\_time**, **score.time**, **problems.time** to **RELTIMEs** - 2) Update examples to use **RELTIME**s in changed properties +Further improvements (no functional changes intended): + + 1. Clarify that **baseurl** must end in a slash. Change all endpoint URLs to be correctly relative by removing prefix slashes. + 2. Change [IETF.org](http://IETF.org) RFC references to use the current website. + 3. General design principles + 1. JSON property types + 1) Description of *Identifiers* clarified. + 2) Clarify no meaning is implied by the order of objects in arrays. + 3) Added note to href + 2. Capabilities + 1) Removed TODO about adding capabilities for team view and awards. + 2) Added warning about capabilities being fleeting + 4. Interface specification + 1. Types of endpoints + 1) Wording change (groups-\>types) + 2. Filtering + 1) Specify explicitly that nullable ID’s can be filtered on + 3. Access + 1) Updated examples (already backpatched to 2023-06) + 4. Contests + 1) Clarify wording for **countdown\_pause\_time** and description below + 5. Languages + 1) Change gcc example to include **\-o a.out** + 2) **ERROR** in example for **“id”: “cpp”** \- can not use gcc to build c++ programs \- should be fixed + 6. Problems + 1) Clarify maximum score for problems in **score** type contests. + 2) Clarify that the **rgb** property should not include an alpha channel. + 3) Fixed JSON formatting error in example. + 7. Teams + 1) Update description of **id** property to no longer include suggestion of using the **id** as the seat number since **label** does that. + 2) Allow HLS video (`application/vnd.apple.mpegurl`) for **video**, **desktop, webcam** and **reaction** properties. + 8. State + 1) Minor wording changes that affect nothing + 9. Submissions + 1) Added text indicating why the **id** should be a small number + 2) Clarify what a missing **team\_id** property implies. + 3) Spelling fixes (entrypoint \-\> entry point) + 4) Clarify that the **data** property for the **files** array is a *base64 encoded zip* file + 10. Clarifications + 1) Provide more detail on broadcast clarification responses + 2) Consistently use “judges” instead of “jury” in descriptions. ## References