docs: ICM lifecycle and API compatibility governance draft#497
Draft
hdamker wants to merge 2 commits intocamaraproject:mainfrom
Draft
docs: ICM lifecycle and API compatibility governance draft#497hdamker wants to merge 2 commits intocamaraproject:mainfrom
hdamker wants to merge 2 commits intocamaraproject:mainfrom
Conversation
Draft response to the ICM WG request to Release Management (ICM#324, ICM#340, RM#351/camaraproject#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.
hdamker
requested review from
rartych,
soadeyemo and
tanjadegroot
as code owners
Collaborator
tanjadegroot
left a comment
tanjadegroot
left a comment
There was a problem hiding this comment.
First set of comments before going any further. In general:
I think we need to decouple this document from implementations of ICM (auth server, certificate authority, etc.).
There is only 1 contract for API consumers: the API version definition (which includes its declared minimum ICM version expressing its compatibility).
API providers must ensure to offer ICM-compatible API version implementations at all times (and hence update their ICM implementation. I prefer to
- remove reference to AS / certificate authorities, only refer to ICM or ICM version
- remove the notion of API - ICM contract, use instead the term ICM-compatibility.
- remove triangle relationship to simplify.
I prefer to use lifecycle state instead of lifecycle tier (more usual for understanding).
The "orthogonal API" concept, seems to be in contradiction with the objective to move API forward and deprecate ICM versions. I would prefer to drop it as anyway has only 5 occurrences - 2 of which in the definition itself and others can easily be dropped, so the additional concept and definitions are superfluous.
But maybe we need a x-camara-minimum-icm special value if "not applicable" or "any" (or 1.0.0" ? for APIs that are ICM-compatible by default (independently of the version) ? This could make it more clear for ICM implementation evolution, which API version implementations need to be upgraded.
I reviewed up to section 5 along the above lines.
|
|
||
| ## 1. Scope and Purpose | ||
|
|
||
| This guideline defines how Identity and Consent Management (ICM) evolves as an independent Working Group and how CAMARA APIs declare and maintain compatibility with ICM versions. It answers the question posed by the ICM Working Group to Release Management: under what rules can API versions and ICM versions co-evolve while still providing clear compatibility guarantees to API Consumers, aggregators, and certification authorities? |
Collaborator
There was a problem hiding this comment.
Suggested change
| This guideline defines how Identity and Consent Management (ICM) evolves as an independent Working Group and how CAMARA APIs declare and maintain compatibility with ICM versions. It answers the question posed by the ICM Working Group to Release Management: under what rules can API versions and ICM versions co-evolve while still providing clear compatibility guarantees to API Consumers, aggregators, and certification authorities? | |
| This guideline defines lifecycle management of Identity and Consent Management (ICM) versions and how CAMARA APIs declare and maintain compatibility with ICM version. It answers the question posed by the ICM Working Group to Release Management: under what rules can API versions and ICM versions co-evolve while still providing clear compatibility guarantees to API Consumers ? |
|
|
||
| This guideline defines how Identity and Consent Management (ICM) evolves as an independent Working Group and how CAMARA APIs declare and maintain compatibility with ICM versions. It answers the question posed by the ICM Working Group to Release Management: under what rules can API versions and ICM versions co-evolve while still providing clear compatibility guarantees to API Consumers, aggregators, and certification authorities? | ||
|
|
||
| The guideline recognizes operational reality: providers offer the same API version against multiple ICM versions, aggregators depend on this flexibility, and API Consumers combine an API version and an ICM version into a single usage contract — if either side changes in a way that affects them, their integration must adapt. |
Collaborator
There was a problem hiding this comment.
Suggested change
| The guideline recognizes operational reality: providers offer the same API version against multiple ICM versions, aggregators depend on this flexibility, and API Consumers combine an API version and an ICM version into a single usage contract — if either side changes in a way that affects them, their integration must adapt. | |
| The guideline recognizes operational reality: providers offer the same API version against multiple ICM versions, aggregators depend on this flexibility, and API Consumers require an API version and an ICM version to be part of a single usage contract — if either aspect changes in a way that affects them, their implementation must adapt. |
|
|
||
| Terms defined in the CAMARA Commonalities glossary (API, API Consumer, API Provider, meta-release, semantic versioning, scope, etc.) are not repeated here. This section defines terms specific to this guideline. | ||
|
|
||
| - **ICM↔API contract**: the set of ICM-defined rules that shape how APIs are specified — scope format, `securitySchemes` syntax, sub claim format, token structure assumed by the API. Distinct from the contract between API Consumer and API (operations, schemas) and the contract between API Consumer and Authorization Server (flows, grants, assertions). |
Collaborator
There was a problem hiding this comment.
Suggested change
| - **ICM↔API contract**: the set of ICM-defined rules that shape how APIs are specified — scope format, `securitySchemes` syntax, sub claim format, token structure assumed by the API. Distinct from the contract between API Consumer and API (operations, schemas) and the contract between API Consumer and Authorization Server (flows, grants, assertions). | |
| - **ICM-compatibility**: the guarantee that an API version respects the set of rules defined by a given ICM version — auth flows, grants, assertions, scope format, `securitySchemes` syntax, sub claim format, token structure assumed by the API, relevant operations and schemas. |
| Terms defined in the CAMARA Commonalities glossary (API, API Consumer, API Provider, meta-release, semantic versioning, scope, etc.) are not repeated here. This section defines terms specific to this guideline. | ||
|
|
||
| - **ICM↔API contract**: the set of ICM-defined rules that shape how APIs are specified — scope format, `securitySchemes` syntax, sub claim format, token structure assumed by the API. Distinct from the contract between API Consumer and API (operations, schemas) and the contract between API Consumer and Authorization Server (flows, grants, assertions). | ||
| - **Orthogonal API**: an API whose specification is not affected by differences between ICM major versions — its `securitySchemes`, scopes, and operational semantics are valid under any ICM major currently in the Supported tier. The majority of current CAMARA APIs are orthogonal. |
Collaborator
There was a problem hiding this comment.
not sure we need to introduce this concept nor to have a definition for this. Just use ICM-compatibility across major ICM versions.
I would prefer to drop it
|
|
||
| - **ICM↔API contract**: the set of ICM-defined rules that shape how APIs are specified — scope format, `securitySchemes` syntax, sub claim format, token structure assumed by the API. Distinct from the contract between API Consumer and API (operations, schemas) and the contract between API Consumer and Authorization Server (flows, grants, assertions). | ||
| - **Orthogonal API**: an API whose specification is not affected by differences between ICM major versions — its `securitySchemes`, scopes, and operational semantics are valid under any ICM major currently in the Supported tier. The majority of current CAMARA APIs are orthogonal. | ||
| - **ICM major version**: the major component of an ICM semantic version (e.g., "1.x"). Starting with ICM 1.0.0, major-version increments indicate client-facing changes that cannot be expressed additively. |
Collaborator
There was a problem hiding this comment.
Suggested change
| - **ICM major version**: the major component of an ICM semantic version (e.g., "1.x"). Starting with ICM 1.0.0, major-version increments indicate client-facing changes that cannot be expressed additively. | |
| - **ICM major version**: the major component of an ICM semantic version (e.g., "1" on "1.y.z"). Starting with ICM 1.0.0, major-version increments indicate client-facing changes that cannot be expressed additively (e.g. breaking changes for API consumers) |
| - **Exception (waiver)**: a time-bound, governance-approved compatibility authorization that permits a specific (API version, ICM version) pair outside the normal rules. | ||
| - **Compatibility matrix**: the derived artifact listing which (API version, ICM version) pairs are compatible at a given point in time (see §12). | ||
|
|
||
| ## 3. The three contracts |
Collaborator
There was a problem hiding this comment.
I would like to drop this section and the 3 contracts as not needed IMHO, only the API definition is a contract for API consumers (with x-camara-minimum-icm included).
The API - ICM "contract" or rather ICM-compatibility guarantee should be by API providers who should ensure ICM compatibility of their API implementations
|
|
||
| ## 4. Core rule | ||
|
|
||
| **An API version is bound to the ICM major version whose ICM↔API contract it was written against.** |
Collaborator
There was a problem hiding this comment.
Suggested change
| **An API version is bound to the ICM major version whose ICM↔API contract it was written against.** | |
| **An API version is ICM-compatible with any Supported ICM version declared in its published definition and higher available ICM versions.** | |
|
|
||
| **An API version is bound to the ICM major version whose ICM↔API contract it was written against.** | ||
|
|
||
| For APIs whose contract is not affected by differences between ICM majors — *orthogonal APIs*, which make up the large majority of current CAMARA APIs — the binding has no operational effect: such an API remains compatible with any ICM major currently in the Supported tier. |
Collaborator
There was a problem hiding this comment.
Suggested change
| For APIs whose contract is not affected by differences between ICM majors — *orthogonal APIs*, which make up the large majority of current CAMARA APIs — the binding has no operational effect: such an API remains compatible with any ICM major currently in the Supported tier. | |
| For APIs who are not impacted by differences between ICM majors — which make up the large majority of current CAMARA APIs — the binding has no operational effect: such an API remains compatible with any ICM version currently in the Supported state. |
|
|
||
| For APIs whose contract is not affected by differences between ICM majors — *orthogonal APIs*, which make up the large majority of current CAMARA APIs — the binding has no operational effect: such an API remains compatible with any ICM major currently in the Supported tier. | ||
|
|
||
| For APIs whose ICM↔API contract IS affected (e.g., an API that uses a specific scope format introduced in an ICM major, or relies on an operator-token mechanism), the binding is explicit and operational: the API can only be served by AS implementations that honor its ICM major's contract. |
Collaborator
There was a problem hiding this comment.
Suggested change
| For APIs whose ICM↔API contract IS affected (e.g., an API that uses a specific scope format introduced in an ICM major, or relies on an operator-token mechanism), the binding is explicit and operational: the API can only be served by AS implementations that honor its ICM major's contract. | |
| For APIs whose ICM-compatibility is impacted (e.g., an API that uses a specific scope format introduced in a new ICM version, or relies on an operator-token mechanism), its compatibility is explicitly expressed in the API version's x-camara-minimum-icm field and operational: the API version can only be served by ICM implementations that provide this ICM version. |
|
|
||
| For APIs whose ICM↔API contract IS affected (e.g., an API that uses a specific scope format introduced in an ICM major, or relies on an operator-token mechanism), the binding is explicit and operational: the API can only be served by AS implementations that honor its ICM major's contract. | ||
|
|
||
| Concretely: `x-camara-min-icm-version: 1.2.0` declared in an API spec means the API was written against the ICM 1.x ICM↔API contract and requires features introduced from ICM version 1.2.0 onward within that major. |
Collaborator
There was a problem hiding this comment.
Suggested change
| Concretely: `x-camara-min-icm-version: 1.2.0` declared in an API spec means the API was written against the ICM 1.x ICM↔API contract and requires features introduced from ICM version 1.2.0 onward within that major. | |
| Concretely: `x-camara-min-icm-version: 1.2.0` declared in an API version means this API version was written against the features introduced from ICM version 1.2.0 and onward. |
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What type of PR is this?
What this PR does / why we need it:
Adds a draft governance document for ICM version evolution and its dependencies with CAMARA API versions, placed under
documentation/SupportingDocuments/. Agreed by the Release Management WG to serve as the base for further discussion in response to the ICM WG's request to define release governance between ICM and APIs.Key elements:
x-camara-min-icm-versiondeclaration in API specs, publication-time fixedOpen governance decisions (durations, exception process, interaction with certification) are listed in §15 for WG discussion.
Which issue(s) this PR fixes:
Relates to #351 and #459. Also related: camaraproject/IdentityAndConsentManagement#324 and camaraproject/IdentityAndConsentManagement#340.
Special notes for reviewers:
This is a draft for WG discussion. §15 lists the open governance decisions that need WG agreement before adoption. Feedback welcome inline or as review comments.
Changelog input
Additional documentation
None.