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/contact.md b/documentation/contact.md index c5eeee6..ba240bb 100644 --- a/documentation/contact.md +++ b/documentation/contact.md @@ -2,12 +2,11 @@ ## Mailing list -The members of the Technical Working Group are subscribed to the mailing list, -which is intended for members of the Technical Working Group to communicate with -each other, but this mailing list is not exclusive for Technical Working Group -members. Interested community members can subscribe through: -[https://list.surf.nl/postorius/lists/openonderwijsapi.list.surf.nl](https://list.surf.nl/postorius/lists/openonderwijsapi.list.surf.nl). +There is an OEAPI mailing list to which all interested in the developments +regarding OEAPI are shared and can be exchanged with all community members. +Interested community members can subscribe through: +[https://list.surf.nl/postorius/lists/oeapi.list.surf.nl](https://list.surf.nl/postorius/lists/oeapi.list.surf.nl). Only the members of this mailing list may send email to this list. Send an email -to [openonderwijsapi@list.surf.nl](mailto:openonderwijsapi@list.surf.nl) to +to [oeapi@list.surf.nl](mailto:oeapi@list.surf.nl) to contact the members of this mailing list. If you need support, contact: -[info@openonderwijsapi.nl](mailto:info@openonderwijsapi.nl) +[info@oeapi.eu](mailto:info@oeapi.eu) diff --git a/documentation/governance/README.md b/documentation/governance/README.md index 463ccef..f92119e 100644 --- a/documentation/governance/README.md +++ b/documentation/governance/README.md @@ -17,7 +17,7 @@ OEAPI management is the final decision-making body of the OEAPI, where the educa The three Dutch education sectors each have their own representation in OEAPI management, alongside the chair of the OEPI technical working group. OEAPI management consists of: * MBO (vocational education): Gertjan Flinterman (Deltion College) -* HBO (higher professional education): Rene Schenk (Avans University of Applied Sciences) +* HBO (higher professional education): Froukje Meirink (NHL Stenden Hogeschool) * WO (university education): Jan-Willem Brock (Leiden University); chair of the OEAPI management * Chair of the OEAPI technical working group: Patrick vd Veer (SURF) 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/documentation/use-cases/README.md b/documentation/use-cases/README.md index ddef909..1d2b2b8 100644 --- a/documentation/use-cases/README.md +++ b/documentation/use-cases/README.md @@ -22,7 +22,7 @@ institution’s data into a format that RIO can process, ensuring a streamlined and consistent data flow between educational institutions and the national registry, and making sure the data is always up to date and synchronised. More information about the RIO functionality with OEAPI can be found in the -[RIO functionality documentation](https://wiki.surfnet.nl/display/SURFeduhub/RIO+Functionality). +[RIO functionality documentation](https://servicedesk.surf.nl/wiki/spaces/WIKI/pages/198967389/RIO+Functionality). ### EduXchange @@ -66,6 +66,6 @@ universities and cross-sectoral. An example of the latter is a tool implemented for the acceleration [zone flexible education](https://www.versnellingsplan.nl/en/making-education-more-flexible/index.html). Another example of such cross-sectoral implementations is the current -development of the RIO adapter and the SURFeduhub. +development of the RIO adapter and SURFeduhub. -![OEAPI gateway](../_media/surfeduhub-architectuur-v5_0.png) +![SURFeduhub](../_media/surfeduhub-architectuur-v5_0.png) 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"