ICM lifecycle and API compatibility governance - for review - #545
ICM lifecycle and API compatibility governance - for review#545tanjadegroot wants to merge 26 commits into
Conversation
* docs: draft ICM lifecycle and API compatibility governance Draft response to the ICM WG request to Release Management (ICM#324, ICM#340, RM#351/#459) defining governance for ICM version evolution and its dependencies with CAMARA API versions. Built on a three-contract model (API Consumer ↔ API, API Consumer ↔ AS, ICM ↔ API), semver discipline at ICM 1.0.0, per-major lifecycle tiers (Preferred/Supported/Deprecated/Retired), a flat x-camara-min-icm-version declaration in API specs, a derived compatibility matrix, and explicit recognition of aggregators as ecosystem normalizers. * docs: simplify concepts and tighten floor rule per review Collapse to one defined ICM-compatibility concept (API spec relative to ICM version), use 'state' instead of 'tier' for ICM major lifecycle, require lowest Supported ICM version as the publication-time floor, and distinguish technical compatibility from CAMARA compliance. * docs: V2 working merge — two-aspect ICM-compatibility, fold in review - §3 restructured around two distinct aspects of ICM-compatibility: API version (design-time, CAMARA-governed via Commonalities) and deployment (runtime, API-Provider-governed). Explicit ICM → Commonalities → API definitions path captured in §3.4. - §6.1 state model recast as a four-column table (state × ICM version × API version × API deployment). States apply per ICM version with major as the primary grain. Revoked added as a terminal exceptional state. Preferred kept as a label (deployment recommendation only). - API spec field is `x-camara-min-icm` (no `-version` suffix). §7.2 rule includes a third operand: the ICM floor required by the declared Commonalities version. - §10 cascade section dropped — its consequences are now captured by the four-column state table; remaining unique point on API-lifecycle independence moved to §6.1 as a note. §7.3 (multi-major declaration field) also dropped; cross-major compatibility is handled solely by §4 governance assessment. - §6.4 introduces breaking-change tables (design info and deployment info) as ICM release-note stubs. - §14 open items reworked: added cross-major assessment process and timing, Provider deployment timeline after Preferred designation, and ICM ↔ Commonalities coupling. - Glossary aligned with WG review; SemVer capitalization consistent throughout; MUSTs scope-clarified for CAMARA-governance reach. * docs: drop Preferred label per WG discussion Tanja's reply on PR #497 confirms dropping the Preferred concept entirely. Migration timing on the deployment side is governed by the lifecycle state transitions (Supported → Deprecated → Retired window), decoupled from meta-release cadence. Changes: - Remove the Preferred glossary entry and the Preferred paragraph in §6.1. - §6.2: reword the row labels and notes so timing triggers off the publication of a newer Supported major rather than off a Preferred-label transition; reword the concurrent-support requirement accordingly. - §8 item 1: API Providers MUST implement the latest published Supported major ICM version (instead of 'the version holding the Preferred label'). - §14: drop the now-redundant open item on Provider deployment timeline after Preferred designation; covered by item 1 (exact durations). * Update documentation/SupportingDocuments/icm-lifecycle-and-compatibility.md Co-authored-by: Tanja de Groot <87864067+tanjadegroot@users.noreply.github.com> * docs: apply round-A review feedback (terminology + per-row content) Wording polish from Tanja's 2026-05-18 review: standardise on 'API version ICM-compatibility' / 'API deployment ICM-compatibility' throughout; rename headings (§3.3, §5, §7.2, §7.3, §8, §10, §11.1-§11.3); reorder §5 SemVer bullets major → minor → patch; update lifecycle-state table rows; drop §10.3 (folded into §10.1/10.2); reword §6.2 governance parameters; add 'documented by Release Management' intro to §13. Structural changes (merge §4 → §7, §6 transitions subsection split, §12 lifecycle column) and pushback items left in 23 open threads. * docs: merge §4 into §6.1 + renumber sections §4 (Minimum ICM version) folded into §6.1 of the renamed §6 (API version ICM-compatibility - details). Floor declaration, three bullets, cross-major governance assessment, and example consolidated into a single subsection. Sections §5..§14 renumber down to §4..§13; all cross-refs updated. * docs: collapse §5.4 + §5.5 into §5.4 Release notes Current §5.4 (Publication of state) and §5.5 (release-note change tables) combined under a single §5.4 "ICM version - Release notes" parent with §5.4.1 (Publication of lifecycle state) and §5.4.2 (ICM version change tables) as sub-subsections. §13 item 10 cross-ref updated to §5.4.2. * docs: substantive corrections + drop §8 Aggregator + drop Appendix B - §5.1 Revoked row: broaden 'a later minor or patch version' to 'another (earlier or later) minor or patch version' to allow rollback. - §7.1 item 3: remove the 'info.description template mandated by Commonalities' clause from the Provider discovery channels (the template does not advertise the deployed ICM version). - §4 trailer ('transition to 1.0.0 should coincide with a scope-baseline review...') folded into §12 item 2 (Transition to ICM 1.0.0). - §5.3 governance-parameters trailer: annotated with HTML comment marker for removal when WG agrees. - §8 Aggregator role removed — no normative content. §9..§13 renumbered to §8..§12; all cross-refs updated. - Appendix B removed. * docs: editorial cleanup pass - §6.2 floor formula commentary: drop 'latest' and 'major' qualifiers on 'always raises its x-camara-min-icm to a Supported ICM version'. Remove Tanja's TBC meta-marker. - §5.4.1 machine-readable schema: tighten 'may be defined later' to 'must be available' (the §6.3 validation rule depends on it). - §6.3 validation: add explicit dependency note pointing at §5.4.1. - §9.1 ICM-compatibility formula: add () around the AND triple; fix unmatched ')' typo. - §11 line 317: 'ICM-compatibility changes' → 'ICM-compatibility authorizations' (matches glossary §2). - §5.1 Revoked row note and §7.1 provider-compliance line: drop redundant 'major' qualifier (applies to any ICM version). * docs: §2 glossary + §3 polish from Tanja's earlier-round review - §2 glossary: - ICM deployment info: broaden scope to include design time, not only runtime, since Providers and Consumers design their implementations against the target ICM version. - API version ICM-compatibility: tie the property to the x-camara-min-icm field where the floor is declared. - 'Deployment ICM-compatibility' → 'API deployment ICM-compatibility' to match the prefix used throughout the body. - ICM-compatibility umbrella: name the two members explicitly (API version + API deployment ICM-compatibility) instead of the abstract 'aspects' shorthand. - §3 heading: drop the '— two aspects, two responsibilities' subtitle. - §3 intro paragraph: name ICM design info and ICM deployment info upfront, hooking into the §3.1 / §3.2 subsections. - §3.1 'Owned and governed by CAMARA' bullet: keep 'codified by'; add trailing clarifier '… by following these guidelines.' - §3.1 second bullet: 'Signaled by x-camara-min-icm declared in' → 'Declared via x-camara-min-icm in'. * TdG comment upto section 5.4 I could not commit to a new branch and do a PR: error message: 'There was an error committing your changes: File could not be edited' * TdG updates to section 6 * TdG section 7 updates * TdG updates sections 8 and 9 Updated sections on ICM version release cadence and compatibility matrix for clarity and precision. * tdg comments sections 10 and 11 inverted order of old sections 10 and 11 * TdG comments sections 12 and Appendix A * TdG - few miscellaneous updates * docs: typo + inconsistency fixes * docs: two more typo fixes * Apply final round of suggestions from code review as agreed in RM call Co-authored-by: Herbert Damker <herbert.damker@telekom.de> --------- Co-authored-by: Tanja de Groot <87864067+tanjadegroot@users.noreply.github.com>
tanjadegroot
changed the title
|
Hi ICM team, @camaraproject/identity-and-consent-management_codeowners , @camaraproject/identity-and-consent-management_maintainers, please review this PR and provide your comments / questions. On the section "Open Issues" you can also add your thoughts in the Wiki here: ICM lifecycle - open issues (WIP) |
sebdewet
left a comment
sebdewet
left a comment
There was a problem hiding this comment.
Nice documentation, few minors comments
partially addressed, some are addressed in the Wiki first
|
Hi @tanjadegroot, Thank you for putting together this excellent document. Apologies for the late comment. I have a quick question to clarify my understanding regarding the "exact durations", specifically this statement: I assume this does not mean that an operator / API provider is forced to upgrade all of their implemented APIs within 2.5 years. Is that correct? My understanding is that even if an operator implemented an API 2.5 years ago, as long as that older version of the API supports the latest ICM version, it can continue to be used. The ICM compatibility matrix would manage this kind of API-to-ICM version support. I hope my understanding is correct, as forcing an upgrade of all implemented APIs within a 2.5-year timeframe would be too short for most operators. Thanks. |
thanks :-) and thanks for your question, never to late !
Correct: no one can force an operator to upgrade. However, operators are expected to upgrade to a Supported ICM version before their current ICM version is Retired. Else they will loose the "CAMARA ICM-compatible" label of their API deployment (but no impact on actual functioning of their current deployment). Please be aware that the durations currently specified (18 months for Supported and 12 months for Deprecated) are proposals only, and are up for discussion. So your comment is very timely :-)
Yes, if that API version supports the latest ICM version and that ICM version is implemented by the operator, then their API deployment is ICM-compatible per the compatibility matrix. However, the compatibility matrix does not contain Retired ICM versions, unless decided by an explicit exception. We can consider 2 cases:
It sounds like you would want the Deprecated period to be longer than 12 months.
I hope this helps, but please don't hesitate if you have more questions/comments. @hdamker in case you want to comment |
|
Hi @tanjadegroot , @hdamker , all, Since there are no other comments on the duration topic so far, I would like to share further feedback based on our internal discussions (as I originally initiated this topic). Apologies for the delayed comment. I hope commenting here (rather than directly editing the Wiki page) is the correct way. After discussing this with our API business team, KDDI does not have a strict requirement for the exact duration. We understand the benefit of implementing and launching newer versions as early as possible. However, from an operational perspective, having an API live in production for less than 3 years seems a bit short. Let me illustrate our concern with a typical scenario starting from 2027, based on the current proposal (18 months Supported + 12 months Deprecated = 30 months Total): A Typical Scenario (Current 30-month rule):
Our Observations on this scenario: Our Proposal: A 6-month extension to the Supported period
Benefits of this Proposal: I would appreciate it if the community could consider this 36-month lifecycle. |
|
@camaraproject/release-management_maintainers How can we conclude this topic in @tanjadegroot absence? Is the Release Management WG going to take up the matter? From the ICM's perspective, we were expecting to review and approve the agreed updates in PR #545 (https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/880934924/2026-06-17+ICM+Minutes). This was in preparation for the first publication of the document following ICM approval. |
|
@jpengar Hi Jesus & team, apologies for the interrupt. I am now able to reconnect again and will progress the issue as we have discussed. I am targetting the next ICM meeting if OK for you. |
Hi Toshi, Thank you much for this great input. It looks very reasonable to me. I propose we take the decision on your proposal at the next ICM meeting, so others can still react before that. If you allow me I will use your above text to create an example in the document under review. Thanks ! |
Updated governance parameters for ICM lifecycle states, changing the duration of the Supported state from 18 months to 24 months. Added an example of ICM lifecycle state evolution and API deployment across meta-releases.
Clarify language regarding ICM releases and state transitions.
There was a problem hiding this comment.
@jpengar Hi Jesus & team, apologies for the interrupt. I am now able to reconnect again and will progress the issue as we have discussed. I am targetting the next ICM meeting if OK for you.
Perfect — thank you so much, @tanjadegroot !. Sorry for the late response, but I've been out of the office the last couple of weeks. The next ICM meeting is next week, so there's plenty of time.
I think the agreed pending actions on the document are summarised well here:
https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/880934924/2026-06-17+ICM+Minutes.
The minutes from the last meeting that you didn't manage to attend can be found here:
https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/913571872/2026-07-01+ICM+Minutes
If those pending actions are implemented in the PR, I think we will be in a position to review the changes and approve the PR from the ICM's perspective at next week's ICM meeting. At least I would provide my approval, as I'm already more than OK with it.
|
@jpengar Hi Jesus, working on both today. |
Updated the tables following Jesus' Wiki proposal.
To address Seb's question on versioning of ICM deployment and design info [here](https://github.com/camaraproject/ReleaseManagement/pull/545/changes#r3354451449)
Added lifecycle state table for ICM release notes Track of ICM releases sofar Example of ICM version override
Added a table of contents
Clarified the types of ICM-compatibility exceptions and their documentation requirements.
Added a section detailing actions to maintain ICM-compatibility, including a table outlining the relationship between meta-releases, ICM versions, and lifecycle states for API designers, providers, and consumers.
Updated version and status to reflect latest draft for ICM WG discussion.
jpengar
left a comment
jpengar
left a comment
There was a problem hiding this comment.
Generally speaking, I think the content of the proposal looks good. I therefore approve it in advance. I have included some editorial changes for your consideration @tanjadegroot
|
|
||
| The two classes of changes are not necessarily related. For example, a change in ICM deployment info MAY (1) or MAY NOT (2) lead to a change of API design info, e.g. | ||
|
|
||
| 1. a new auth flow impacts the API design info as a new type of credential/token needs to be introduced in the API definition (change of ICM deployment info leads to change of ICM design info) |
There was a problem hiding this comment.
| 1. a new auth flow impacts the API design info as a new type of credential/token needs to be introduced in the API definition (change of ICM deployment info leads to change of ICM design info) | |
| 1. a new security scheme impacts the API design info as a new `securitySchemes` needs to be introduced in the API definition (change of ICM deployment info leads to change of ICM design info) |
This is not accurate. In general, a new OAuth flow introduced by ICM does not affect the API specification. To provide a better example, we could say that ICM introduces new security scheme, changes the mandatory ICM info.description template or changes the scope format as mentioned in other parts of the document.
There was a problem hiding this comment.
@jpengar One question still on this one: the intention of the first example was to show that an ICM deployment info change may impact ICM design info. Would the following additions in bold be correct ? if not I will just leave it as is.
- a new security scheme, required by a new auth flow or by a new behaviour of an existing auth flow, impacts the API design info as a new
securitySchemesitem needs to be introduced in the API definition (change in ICM deployment info leads to change in ICM design info)
|
|
||
| This guideline defines lifecycle management of Identity and Consent Management (ICM) versions and how CAMARA APIs declare and maintain compatibility with them. It defines under what rules API versions and ICM versions can co-evolve while still providing clear compatibility guarantees. | ||
|
|
||
| The guideline recognizes operational reality: API Providers offer the same API version against multiple ICM versions, and API Consumers require an API version and an ICM version as part of a single usage contract — if either aspect changes in a way that affects them, their implementation must adapt. |
There was a problem hiding this comment.
| The guideline recognizes operational reality: API Providers offer the same API version against multiple ICM versions, and API Consumers require an API version and an ICM version as part of a single usage contract — if either aspect changes in a way that affects them, their implementation must adapt. | |
| The guideline recognizes operational reality: API Providers offer the same API version against multiple ICM versions, and API Consumers require an API version and an ICM version as part of a single usage contract — if either aspect changes in a way that affects them, their implementation must adapt. | |
| The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119). |
This change requires the words 'must', 'should', etc. to be capitalised throughout the document. This is just an editorial matter and does not affect content approval.
Co-authored-by: Jesús Peña García-Oliva <jesus.penagarcia-oliva@telefonica.com>
Renamed section 2 from "Glossary" to "Glossary and References"
|
@jpengar, all, I incorporated all comments from Jesus except one on the MUST, SHOULD reference + capitalization that I will still shortly. I rewroted the example section 3.8 on the lifecycle state durations and Provider impacts: ICM version being valid for 3 years leads to actual API deployment lifespan being valid for 2 years (not 3 as was wrongly stated before in line 411). API deployment realistically targets 6 months after their release and hence 12 months after the corresponding ICM version release of those APIs. @ToshiWakayama-KDDI, all: please check that this is still OK and inline with your expectations. |
|
@tanjadegroot and all, one of the action items from yesterday's ICM meeting was to compile a list of ICM-impactable design-info elements. Please see the list I have compiled below of what ICM has defined so far. Please let me know if I have missed anything.
|
plus some additional changes on the side
adjusted the section 3 introduction to better fit the new content. some duplication wit the glossary section could be remove (shorten glossary)
|
@jpengar looks good ! thanks ! One suggestion:
Also added the Please check my propose update in intro of section 3 in commit 5c9df39 WDYT ? |
@tanjadegroot Yes, good catch! I agree with your suggestion. I've updated my previous comment to reflect this.
LGTM. I agree, but take a look at the index and the numbers of the subsections. They should start from 3.1, but currently start from 3.2. Consequently, the links in the index are broken. |
6 participants
What type of PR is this?
Add one of the following kinds:
What this PR does / why we need it:
This PR introduces a guideline for ICM version lifecycle governance and definition of ICM-compatibility of API versions. This allows CAMARA to provide a clear and governed way to handle ICM version dependency of APIs both for API developers in CAMARA, and for API Providers and API Consumers in their API deployments.
In a nutshell, this guideline proposes to introduce the following:
ICM-compatibility: the alignment of APIs with information defined by an ICM version as follows:
x-camara-min-icm: an additional field in the API definition file (yaml) indicating the lowest ICM version this API version is designed to work with.ICM version lifecycle states (Supported, Deprecated, Retired, Revoked): governance, the impact of state changes on ICM-compatibility of APIs, and resulting actions by API designers, API Providers and API Consumers.
ICM compatibility matrix (generated): a Release Management asset that records which API version is ICM-compatible with which ICM version
The proposal is open for review by all and particular by the ICM and Commonalities teams.
Which issue(s) this PR fixes:
Fixes: #351
Special notes for reviewers:
For the list of open issues at the end - I am working on a Wiki page with some proposals will include the link here as soon as available.