ICM lifecycle and API compatibility governance - for review#545
ICM lifecycle and API compatibility governance - for review#545tanjadegroot wants to merge 4 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>
|
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
There was a problem hiding this comment.
Nice documentation, few minors comments
|
|
||
| This means an ICM design info change typically also triggers a Commonalities update. How tightly ICM and Commonalities lifecycles must be coupled is an open item (see §12). | ||
|
|
||
| ## 4. ICM versioning |
There was a problem hiding this comment.
Could you clarify how changes in ICM deployment info are versioned and how they interact with changes in ICM design info. It would be beneficial to add a subsection or a note to explain the versioning process for ICM deployment info changes and their impact on ICM design info.
There was a problem hiding this comment.
The ICM version reflects changes in both types of ICM info at the same time.
ICM design info and API deployment info are not versioned separately.
A change in ICM deployment info MAY (1) or MAY NOT (2) lead to a change of API design info, e.g.
-
if a new ICM deployment info needs to be captured in API specifications, such as a new auth flow, introducing a new type of credential/token.
-
a breaking change in the ICM deployment info such as the introduction of a 300s client-assertion lifetime cap has no impact on the API design info, but will lead to a major ICM version change.
Note: I am not an ICM specialist, so the above examples could be wrong. Hence, in open issue nr 10 (Example content for the §5.4.2 release-note tables), we are asking the ICM team to provide more examplse of such changes. e.g. taken from previous ICM versions.
There was a problem hiding this comment.
I added some examples to https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/822444052/ICM+lifecycle+-+open+issues+WIP#Example-content-for-the-%C2%A75.4.2-release-note-tables and suggested changes to the table columns to make them as actionable as possible.
| - **Identified at deployment/runtime.** An API Consumer determines the applicable ICM version's deployment info by inspecting API Provider metadata and onboarding artifacts; the API version alone does not pin a specific ICM version on the deployment side. | ||
| - **Not recorded in the CAMARA compatibility matrix.** The matrix governs API version ICM-compatibility (design-time). API deployment ICM-compatibility is the API Provider's responsibility. | ||
|
|
||
| ### 3.3 Maintaining ICM-compatibility |
There was a problem hiding this comment.
Could you add a diagram or a process flow to illustrate how the different stakeholders (API designers, API Providers, API Consumers) interact to maintain ICM-compatibility ?
There was a problem hiding this comment.
yes, I will give this a thought and will come back on it
|
|
||
| The ICM-compatibility matrix is published by Release Management. It is computed, not hand-edited. Only exceptions require human governance action. | ||
|
|
||
| ## 10. Exception mechanism |
There was a problem hiding this comment.
Could you add an example of an exception document to clarify the process of requesting and approving exceptions ?
There was a problem hiding this comment.
I have added examples of exception decision record, and realize we were missing the lifecyce state transition exception (and record in this section as well)
Please check wiki proposal as a start here
it indicates owners, but not yet the full process
|
|
||
| The lifecycle state is published in each ICM version's release notes, as a table in the release notes template. No separate governance artifact is required. Each ICM version release carries the lifecycle state for all ICM versions. State transitions are committed at ICM public release unless an out-of-cycle governance action specifies otherwise. | ||
|
|
||
| The published lifecycle state must be available in machine-readable form for the CAMARA validation support to consume (§6.5). Until a schema is defined, the ICM version release notes are the single authoritative source — readable by humans but not by tooling. |
There was a problem hiding this comment.
As discussed at the last ICM meeting (https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/843055110/2026-06-03+ICM+Minutes), it was agreed that we would need a template for ICM release notes so that the CAMARA tooling could automatically process the ICM lifecycle state. @hdamker said that we could provide a format proposal, but to do so, we need the data and information to be included.
As far as I understand, this information should include the ICM lifecycle state, for which there is already table proposal from @tanjadegroot at https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/822444052/ICM+lifecycle+-+open+issues+WIP#Example-ICM-lifecycle-state-table-in-ICM-release-notes, which looks good to me. What do you think?
My only question is whether the proposed table should somehow consider the 'per-version overrides' mentioned in the document.
There was a problem hiding this comment.
yes you are right - will tweek the wiki page example a bit more to include that. information.
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.
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.