WCIF v1.1 & Versioning Policy

README.md

@@ -2,10 +2,14 @@
 
 The official specification of the [WCA Competition Interchange Format](./specification.md).
 
+## Versioning
+
+This document is for v1.1, the current `latest` version of WCIF. See [WCIF Versioning Policy](https://github.com/thewca/wcif/blob/master/versioning-policy.md) for more information.
+
 ## Implementation notes
 
 Currently the WCA website implements most of the specification.
-The WCIF data for the given competition can be obtained via the following endpoints:
+The WCIF data for the given competition can be obtained via the following endpoints[^1]:
 
 ###### Public endpoint
 
@@ -19,6 +23,8 @@ Publicly available (with the confidential attributes stripped out). *Note: the d
 
 Restricted to competition managers. Additionally, a `PATCH` request allows for saving the data (currently a significant subset of it).
 
+[^1] These will always return the latest stable version - see [WCIF Versioning Policy](https://github.com/thewca/wcif/blob/master/versioning-policy.md) to request a specific version.
+
 ## Note on WCA Live
 
 In order to get up-to-date live results in the WCIF data, make sure you *Synchronize* on WCA Live.

specification.md

@@ -1,10 +1,27 @@
 # WCIF
 
-*Version: 1.0*
+WCIF stands for WCA Competition Interchange Format and is a specification of competition data in JSON format.
+It's designed as a way for many applications to exchange data in a standardized manner.
+
+## Version
+- Number: 1.1
+- Status: Stable
+- Next Status: Deprecated
+- Status Advancement Date: N/A
 
 WCIF stands for WCA Competition Interchange Format and is a specification of competition data in JSON format.
 It's designed as a way for many applications to exchange data in a standardized manner.
 
+If you intend to read/write WCIF from the WCA website in your application, please:
+- Familiarize yourself with the [WCIF Versioning Policy](https://github.com/thewca/wcif/blob/master/versioning-policy.md)
+- [Sign up](https://www.worldcubeassociation.org/profile/edit?section=preferences) in your profile preferences to our developer mailing list to receive updates about new versions and deprecations.
+- Optionally, configure your apllication to monitor the `next_status` and `status_advancement_date` properties and alert you when these values change
+
+## Changelog from v1.0
+
+Changes from v1.0 are as follows:
+- Added value `5` to `round.format` enum - `5` corresponds to a Best of 5 format as described in the [2026 Regulation Changes](https://github.com/thewca/wca-regulations-january-2026/pull/48).
+
 ## Objects
 
 The specification defines the following types:
@@ -328,7 +345,7 @@ Represents data of an event held at the competition.
 
 | Attribute | Type | Description |
 | --- | --- | --- |
-| `id` | `String` | The WCA event identifier. Look [here](https://github.com/thewca/worldcubeassociation.org/blob/master/WcaOnRails/db/seeds/events.seeds.rb) for the list of all the WCA events. |
+| `id` | `String` | The WCA event identifier. Look [here](https://github.com/thewca/worldcubeassociation.org/blob/main/lib/static_data/events.json) for the list of all the WCA events. |
 | `rounds` | [`[Round]`](#round) | List of rounds of the event held at the competition. |
 | `competitorLimit` | `Integer\|null` | The maximal number of competitors that can register for the event. |
 | `qualification` | [`Qualification`](#qualification)\|`null` | The requirement that a person must meet in order to register for the event. |
@@ -353,7 +370,7 @@ Represents data of a round held at the competition.
 | Attribute | Type | Description |
 | --- | --- | --- |
 | `id` | `String` | The round identifier of the form `{eventId}-r{roundNumber}`. *Note: this is a valid [`ActivityCode`](#activitycode).* |
-| `format` | `"1"\|"2"\|"3"\|"a"\|"m"` | The round format. Look [here](https://github.com/thewca/worldcubeassociation.org/blob/master/WcaOnRails/db/seeds/formats.seeds.rb) for the list of all the WCA formats. |
+| `format` | `"1"\|"2"\|"3"\|"5"\|"a"\|"m"` | The round format. Look [here](https://github.com/thewca/worldcubeassociation.org/blob/main/lib/static_data/formats.json) for the list of all the WCA formats. |
 | `timeLimit` | [`TimeLimit`](#timelimit)\|`null` | The time limit in this round. For events with unchangeable time limit (3x3x3 MBLD, 3x3x3 FM) the value is `null`. |
 | `cutoff` | [`Cutoff`](#cutoff)\|`null` | The cutoff in this round. |
 | `advancementCondition` | [`AdvancementCondition`](#advancementcondition)\|`null` | The condition specifying which competitors advance to the next round. |

versioning-policy.md

@@ -0,0 +1,34 @@
+## Version Numbering
+
+We will follow [SemVer](https://semver.org/)’s Major.Minor.Patch format, defined as follows: 
+- **Major**: increments upon _breaking changes_ - ie, changes that would cause errors in implementations relying on the current latest version
+    - Removing or renaming a field
+    - Changing a field’s type, or removing previously-available enum values
+    - Major changes in business logic - such as the addition of a new round format or advancement type.[^1]
+- **Minor**: increments upon the addition of new functionality that maintains _forward compatibility_ - ie, existing implementations can continue without error
+    - Adding a new field, adding values to an existing enum
+- **Patch**: a change which does not meaningfully alter API output - for example, bugfixes that alter incorrect behaviour to align with documented behaviour
+
+[^1] Sometimes these changes may "just" take the form of a new enum value, which would usually be handled by a Minor version increment. In certain cases, however, the change to business logic is significant enough to mandate a Major version change, to ensure that backwards-compatibility doesn't allow third-party tools to create undesireable outcomes (such as incorrectly determining round advancement from a new round advancement criterion). 
+
+## Version Lifecycle
+
+There are several stages of a version lifecycle, specified by `version_status` field in WCIF. A nullable `status_advancement_date` field will indicate when the `version_status` will progress to the next stage of the lifecycle.
+- **Beta**: Early release of a new version - made available to developers for testing, or early access to newly-supported features. Spec may be subject to change
+- **Latest**: Latest WCIF version, made available to developers for feedback and early migration. Spec is considered final.
+    - When a `latest` version is released, a `status_advancement_date` will be given to the current `stable` version
+- **Stable**: The WCIF version served by default
+- **Deprecated**: Backwards compatibility will be maintained where possible, but clients should updated their version to either `latest` (ideally) or `stable` (at minimum) by the `status_advancement_date` to maintain functionality
+- **Removed**: No longer supported, not possible to access via API endpoints
+
+## Requesting Specific Versions
+The existing WCIF endpoints will remain, and always serve the `stable` version of WCIF.
+
+The following endpoints are not yet available, but will be implemented when we increment to v2.0 - this is expected in Q1 2026.
+- `api/v0/competitions/{competition-id}/wcif/{lifecycle-name}` to request the latest, or beta versions
+- `api/v0/competitions/{competition-id}/wcif/version/{version-number}` to request a specific version number
+
+## Backwards Compatibility  
+- In general, we aim to align with Google's [API-180](https://google.aip.dev/180) - feel free to raise concerns with us by opening a Github issue if you feel we deviate from this
+- We guarantee that new version releases within the same major version number (v2.1 -> v2.2) will maintain backwards compatibility.
+- In some cases, features will be introduced which require a major version increment, and for which backwards compatibility is not possible. When competitions use these features, we will return a `403: Forbidden` error for both GET and PATCH requests against an unsupported version of WCIF.