open-education-api · EdoBoorsma · Jun 14, 2026 · Jun 15, 2026 · Jun 15, 2026 · Jun 15, 2026
diff --git a/documentation/_media/consumer_versioning_table.png b/documentation/_media/consumer_versioning_table.png
diff --git 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
@@ -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
@@ -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
@@ -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.