diff --git a/documentation/_media/consumer_versioning_table.png b/documentation/_media/consumer_versioning_table.png deleted file mode 100644 index 2bf50e1..0000000 Binary files a/documentation/_media/consumer_versioning_table.png and /dev/null differ diff --git a/documentation/_sidebar.md b/documentation/_sidebar.md index e2586c5..32c7cc4 100644 --- a/documentation/_sidebar.md +++ b/documentation/_sidebar.md @@ -43,7 +43,11 @@ * [Major changes since last version](technical/major-changes.md#start) * [Changelog](https://markdownpreview.github.io/?https://raw.githubusercontent.com/open-education-api/specification/v6.0/CHANGELOG.md) * [Security](technical/security.md#start) - * [versioning](technical/versioning.md#start) + * [Versioning](technical/versioning.md) + * [OEAPI versioning](technical/versioning.md#oeapi-versioning) + * [Profile versioning](technical/versioning.md#profile-versioning) + * [Consumer versioning](technical/versioning.md#consumer-versioning) + * [Header based versioning model](technical/versioning.md#header-based-versioning-model) * [About identifiers](technical/identifiers.md#start) * [Enumerations](technical/enumerations.md#start) * [Formatting text](technical/formatting-text.md#start) diff --git a/documentation/technical/consumers-and-profiles/README.md b/documentation/technical/consumers-and-profiles/README.md index 35ec475..9cd4c42 100644 --- a/documentation/technical/consumers-and-profiles/README.md +++ b/documentation/technical/consumers-and-profiles/README.md @@ -37,9 +37,9 @@ Consumers operate inside the API response — they enrich data for a specific re A profile is a formal document that defines a subset of OEAPI tailored for a specific use case or ecosystem. It specifies: -* Which endpoints are required to be implemented -* Which fields must be populated -* What validation rules apply +- Which endpoints are required to be implemented +- Which fields must be populated +- What validation rules apply Profiles live outside the API itself — they operate at the specification level and are used for conformance checking and validation. Tools like the eduhub-validator use profiles to test whether an OEAPI endpoint meets the requirements for a particular context (e.g., the RIO profile or the eduXchange profile). @@ -118,50 +118,108 @@ requester, you are responsible for the maintenance of the consumer. ## Consumer versioning -Consumers that are part of the standard are kept in sync with the versioning -scheme of OEAPI. This is required to communicate with which OEAPI versions a -consumer is compatible and can be used. The basic rule is that the major -version number of the OEAPI standard must always be adopted by the consumer -specification: - -1. A new major version of OEAPI is released. All consumers must be reviewed - and, if required, adjusted. This always results in a new consumer version - (with or without changes) following the major version number of the OEAPI - standard. - -In addition to this basic rule regarding a major OEAPI release, three other -situations can occur regarding OEAPI minor releases (1a and 1b) and new -consumer releases (2): - -1. A new OEAPI minor version is released. Consumers can be: - a. Compatible with the new release and require no change. - The consumer version will not change to indicate backwards (and - forwards) compatibility. - b. Not compatible with the new OEAPI release. Any impact on the consumer - must be reviewed and resolved. A new consumer release will take place. - The consumer version number of this new release will change and will - use the lowest (or current) minor version of the OEAPI specification to - which it is backwards compatible. This could be the current minor - version, but also one or multiple earlier minor releases. If this - conflicts with an earlier consumer version number, a patch number is - introduced or increased. - -2. A new consumer version is released without a new OEAPI release. - The consumer version number will use the patch version number, - introducing or increasing the patch version number following the lowest - minor release of OEAPI with which this release is compatible. - -An example of the versioning of consumers based on these rules is shown in -the following table: - -![Consumer versioning overview](../../_media/consumer_versioning_table.png) - -## Profiles - -In addition to the `consumer` query parameter and the `consumer` object, it -may be necessary for a specific application or use case to specify which -requests must be implemented for it to function. Applications may also -require attributes that are not required in the base specification. To -specify such requirements, we recognise "profiles". Since there is currently -no specific format defined to specify such a profile, profiles are described -using text and lists. +Consumer definitions use semantic versioning with a major and minor version +number: + +```text +vMAJOR.MINOR +``` + +A new major version is created when the consumer definition contains breaking +changes. + +A change is considered breaking when an existing implementation of the +consumer may no longer work without modification. Examples include: + +- Removing a consumer attribute +- Renaming a consumer attribute +- Changing the meaning of a consumer attribute +- Changing the type or structure of a consumer attribute +- Adding a new mandatory consumer attribute + +A new minor version is created for non-breaking changes. + +A change is considered non-breaking when existing implementations can continue +to operate without modification. Examples include: + +- Adding optional consumer attributes +- Adding optional enum values +- Extending descriptions, examples, or documentation +- Clarifying existing behaviour without changing its meaning + +Minor versions are therefore backwards compatible within the same major +version. + +See also: [Consumer versioning](technical/versioning.md#consumer-versioning) + +### Consumer compatibility + +Each consumer version defines the minimum OEAPI version it requires. + +A new OEAPI release does not automatically require a new consumer version. +Consumers only need a new version when changes to the consumer definition are +required. + +When a new OEAPI major version is released, existing consumers must be +reviewed to determine whether a new consumer version is required. + +When a new OEAPI minor version is released, an existing consumer version +remains valid unless changes to the consumer definition are needed. If changes +are required, a new consumer version is released indicating the minimum OEAPI +version with which it is compatible. + +## Profile versioning + +Profile definitions use semantic versioning with a major and minor version +number: + +```text +vMAJOR.MINOR +``` + +A new major version is created when the profile definition contains breaking +changes. + +A change is considered breaking when an existing implementation of the profile +may no longer work without modification. Examples include: + +- Removing a profile attribute +- Renaming a profile attribute +- Changing the meaning of a profile attribute +- Changing the type or structure of a profile attribute +- Adding a new mandatory profile attribute + +A new minor version is created for non-breaking changes. + +A change is considered non-breaking when existing implementations can continue +to operate without modification. Examples include: + +- Adding optional profile attributes +- Adding optional enum values +- Extending descriptions, examples, or documentation +- Clarifying existing behaviour without changing its meaning + +Minor versions are therefore backwards compatible within the same major +version. + +See also: [Profile versioning](technical/versioning.md#profile-versioning) + +### Profile compatibility + +Each profile version defines the minimum OEAPI version it requires. + +A new OEAPI release does not automatically require a new profile version. +Profiles only need a new version when changes to the profile definition are +required. + +When a new OEAPI major version is released, existing profiles must be reviewed +to determine whether a new profile version is required. + +When a new OEAPI minor version is released, an existing profile version +remains valid unless changes to the profile definition are needed. If changes +are required, a new profile version is released indicating the minimum OEAPI +version with which it is compatible. + +Profiles describe additional functional or implementation requirements on top +of the base OEAPI specification. They may define required endpoints, +constraints, or additional optional attributes for a particular use case. diff --git a/documentation/technical/versioning.md b/documentation/technical/versioning.md index e7d35d8..95d4211 100644 --- a/documentation/technical/versioning.md +++ b/documentation/technical/versioning.md @@ -1,4 +1,189 @@ -# Versioning: how it works +# Versioning + +## OEAPI Versioning + +OEAPI uses semantic versioning with a major and minor version number: + +```text +vMAJOR.MINOR +``` + +Examples: + +```text +v5.0 +v6.0 +v6.1 +``` + +Patch versions are not used. + +### Major versions + +A new major version is created when the specification contains breaking changes. + +A change is considered breaking when an existing implementation may no longer +work without modification. Examples include: + +- Removing an endpoint, object, attribute, or enum value +- Renaming an endpoint, object, attribute, or enum value +- Changing the meaning of an existing attribute +- Changing the type or structure of an existing attribute +- Adding a new mandatory attribute to an existing request or response +- Changing validation rules in a way that rejects previously valid data + +### Minor versions + +A new minor version is created for non-breaking changes. + +A change is considered non-breaking when existing implementations that support +the previous minor version can continue to operate without modification. +Examples include: + +- Adding optional attributes +- Adding optional enum values +- Adding new endpoints +- Extending descriptions, examples, or documentation +- Clarifying existing behaviour without changing its meaning + +Minor versions are therefore backwards and forwards compatible within the same +major version. + +### Compatibility + +Implementations that support a specific minor version within a major version +should also support later minor versions of the same major version, provided +they ignore unknown optional fields. + +For example, an implementation supporting `v6.0` should also be able to process +responses from `v6.1`. + +Implementations must not assume that future minor versions contain exactly the +same set of attributes. Additional optional data may be introduced in any minor +version. + +## Profile versioning + +Profile definitions use semantic versioning with a major and minor version +number: + +```text +vMAJOR.MINOR +``` + +A new major version is created when the profile definition contains breaking +changes. + +A change is considered breaking when an existing implementation of the profile +may no longer work without modification. Examples include: + +- Removing a profile attribute +- Renaming a profile attribute +- Changing the meaning of a profile attribute +- Changing the type or structure of a profile attribute +- Adding a new mandatory profile attribute + +A new minor version is created for non-breaking changes. + +A change is considered non-breaking when existing implementations can continue +to operate without modification. Examples include: + +- Adding optional profile attributes +- Adding optional enum values +- Extending descriptions, examples, or documentation +- Clarifying existing behaviour without changing its meaning + +Minor versions are therefore backwards compatible within the same major +version. + +### Profile compatibility examples + +Each profile version defines the minimum OEAPI version it requires. + +| Profile version | Minimum OEAPI version(s) | +|-----------------|--------------------------| +| v2.0 | v5.0, v6.1 | +| v2.1 | v6.1 | +| v3.0 | v6.1 | +| v3.1 | v6.4 | +| v4.0 | v6.6, v7.0 | + +In this example: + +- Profile version `v2.0` works with OEAPI versions `v5.0` and `v6.1` (profiles + can be compatible with multiple major OEAPI versions). +- Profile version `v2.1` is a non-breaking update of `v2.0` and therefore + continues to require OEAPI `v6.1`. +- Profile version `v3.0` introduces breaking changes and still requires OEAPI + `v6.1`. +- Profile version `v3.1` is a non-breaking update of `v3.0` but requires at + least OEAPI `v6.4`. +- Profile version `v4.0` introduces breaking changes and requires minimum OEAPI + `v6.6` or `v7.0` +- A profile based on version `v3.1` cannot be used with an OEAPI + implementation that only supports `v6.1` through `v6.3`. + +## Consumer versioning + +Consumer definitions use semantic versioning with a major and minor version +number: + +```text +vMAJOR.MINOR +``` + +A new major version is created when the consumer definition contains breaking +changes. + +A change is considered breaking when an existing implementation of the consumer +may no longer work without modification. Examples include: + +- Removing a consumer attribute +- Renaming a consumer attribute +- Changing the meaning of a consumer attribute +- Changing the type or structure of a consumer attribute +- Adding a new mandatory consumer attribute + +A new minor version is created for non-breaking changes. + +A change is considered non-breaking when existing implementations can continue +to operate without modification. Examples include: + +- Adding optional consumer attributes +- Adding optional enum values +- Extending descriptions, examples, or documentation +- Clarifying existing behaviour without changing its meaning + +Minor versions are therefore backwards compatible within the same major version. + +### Consumer compatibility examples + +Each consumer version defines the minimum OEAPI version it requires. + +| Consumer version | Minimum OEAPI version(s) | +|------------------|--------------------------| +| v2.0 | v5.0, v6.1 | +| v2.1 | v6.1 | +| v3.0 | v6.1 | +| v3.1 | v6.4 | +| v4.0 | v6.6, v7.0 | + +In this example: + +- Consumer version `v2.0` works with OEAPI versions `v5.0` and `v6.1` (consumers + can be compatible with multiple major OEAPI versions). +- Consumer version `v2.1` is a non-breaking update of `v2.0` and therefore + continues to require OEAPI `v6.1`. +- Consumer version `v3.0` introduces breaking changes and still requires OEAPI + `v6.1`. +- Consumer version `v3.1` is a non-breaking update of `v3.0` but requires at + least OEAPI `v6.4`. +- Consumer version `v4.0` introduces breaking changes and requires OEAPI + `v6.6` and is compatible with `v7.0`. +- A request using consumer version `v3.1` cannot be served by an OEAPI + implementation that only supports `v6.1` through `v6.3`. + +## Header based versioning model OEAPI uses a header-based, explicit, single-choice versioning model. @@ -42,9 +227,9 @@ In short: the client chooses, the server validates. There is no negotiation. --- -## Versioning: examples +### Versioning: examples -### Example 1: successful request (exact version match) +#### Example 1: successful request (exact version match) Client: @@ -65,7 +250,7 @@ The server returns exactly the same versions as requested. --- -### Example 2: minor version fallback (higher or lower) +#### Example 2: minor version fallback (higher or lower) Client: @@ -87,7 +272,7 @@ used. --- -### Example 3: unsupported OEAPI version +#### Example 3: unsupported OEAPI version Client: @@ -121,7 +306,7 @@ Fallback is not permitted and the request is rejected. --- -### Example 4: unsupported consumer version +#### Example 4: unsupported consumer version Client: diff --git a/lychee.toml b/lychee.toml index a7c5fae..515c806 100644 --- a/lychee.toml +++ b/lychee.toml @@ -1,5 +1,5 @@ # Equivalent of: --include-fragments -include_fragments = true +include_fragments = "full" # Equivalent of: -v (choose log level) verbose = "error" # Possible values: "error", "warn", "info", "debug", "trace"