docs: company certificate standard/update & fix merge conflicts by PaddseL · Pull Request #1 · PaddseL/catenax-ev.github.io

PaddseL · 2025-11-12T17:31:27Z

This version of the PR has the latest upstream changes merged into and the merge conflicts resolved.

Initial suggestions from @nicoprow and @FEILSTE:
Docs/company certificate standard/update nicoprow/catenax-ev.github.io#1
Additional suggestions from the meetings this week:
chore: apply code review suggestions, qol changes nicoprow/catenax-ev.github.io#2

Bumped version to v2.4.0

first draft for revising response codes

WIP

Added fixes.

Fixed image link.

Fixed typo

WIP

Adapt EDC offers.

Updated section 2.1.5

Updated state machine image

…ceiver. A few additional changes

Explained EDC HTTP response limitations.

- Added explanation for use of Certificate Receiver/Distributor terms. - Reworked the information regarding the feedbackUrl (also made them part of the normative standard). - Reworked the Note for the EDC issue with 400 response codes.

Fixed formatting for one **MUST**

Fixed more normative formatting.

Added comments from todays discussion.

Added restriction to one unique asset per API (version/subject)

Such comments should go onto the pull request on github instead

- Added all changes from todays expert group discussion - refactored naming - updated all legacy images and changed them from png to svg

FEILSTE · 2025-11-18T14:45:49Z

@PaddseL Thank you for your consolidation efforts!

Find four points of mine described below, but other than that this gets a confirmation from me:

2.1.1.3 Company Certificate Feedback (and following) -> Please change it back from Status to Feedback, since this is where the Consumer provides Feedback to the Provider. We explicitly changed the naming from Status to Feedback, to make this clear. (Also in the Context change it to Feedback: "context": "CompanyCertificateManagement-CCMAPI-Feedback:1.0.0" (also revert back in 2.1.5.1 and 2.1.5.2)
For the Certificate Status Update (in terms of the pull scenario, which was requested during one of the last meetings), please let's use a separate naming:
2.1.1.4 Company Certificate Available -> perhaps name the heading '2.1.1.4 Company Certificate Available for Pull' -> then as you designed; but perhaps change the context: "context": "CompanyCertificateManagement-CCMAPI-Cert-Available:1.0.0"
In 2.1.4.1 Notification API you describe the API as 'Notification API'; I'd argue that this is not a notification API, but just an API, so perhaps it makes sense to drop the "notification" and just call it 'cx-taxo:CompanyCertificateApi'? But I also don't have strong feelings about keeping the naming as is now.
I just noticed, that we made a mistake in line 647: "- Business Application Provider MUST offer the push mechanism option to the Certificate Consumer application user, if the Certificate Consumer supports the push mechanism.". Let's drop the Certificate Consumer before the application user -> "- Business Application Provider MUST offer the push mechanism option to the application user, if the Certificate Consumer supports the push mechanism." Since of course it would be the Certificate Provider who uses the push mechanism.

leszekszajnowski · 2025-11-18T17:14:44Z

-    "receiverBpn" : "BPNL0000000002CD",
-    "sentDateTime" : "2025-05-04T00:00:00-07:00",
-    "version" : "3.1.0"
+  "header": {


I'm not sure if it is by purpose or maybe I have missed something, but this request and all requests below are slightly different than the ones defined in the openapi spec.

You can see that in the API spec there are additional fields like: 'expectedResponseBy' and 'context'. This is the case for ALL endpoints in the standard expect /status
Why are they in the API spec and not mentioned in the standard. Should we support those ? What is their purpose ?

@nicoprow I would say remove from the open API spec?

context is in the example in line 127, relatedMessageId and expectedResponseBy are optional attributes in the message header aspect model, which is referenced in the openAPI yaml.

I would leave it as it is, like this we're reusing the message header from CX0151 but are only specifying the relevant information in the examples.

But I think it still should be explained in the standard what this property is if we have it in the spec. Does not matter if it is optional or not.

Ok, for the 'context'. Missed it. Thanks.

leszekszajnowski · 2025-11-18T17:20:04Z

+```
+
+>**`documentId` explanation**:
+> The reasoning why a documentId (the unique ID of EDC asset of the certificate) is to be returned (and not for example the certificate as a return payload) is,


So can I assume that documentI**d** present in the standard (through all endpoints) is always the Id of the asset representing the certificate and the documentI**D** present in the PUSH is only an internal Id of the certificate not related to the asset of certificate ?

seems to me that way; I can only speak for the documentId that we added to the pull scenario - that is intended to act as a shortcut for getting the new certificate, so the edc catalog filter returns only exactly this one document and no others

they are referring to the same ID. the spelling with the capital D is just due to the business certificate aspect model, changing the aspect model is out of scope for this patch release from my understanding.

I was more asking about the relation between the asset ID representing the certificate and documentId.

So you are saying that the docuemntID present in the request body of the PUSH mechanism is the ID of the asset of the certificate in the EDC ?

I also raised that at the initial version of the PR: there is no written requirement on the naming of the asset for the pull mechanism.

When using the push mechanism, the certificate technically and by standard does not need an EDC asset:

Certificate Provider MUST expose company certificates in their catalog when using the pull mechanism.

However, for me it would make sense to implement it that way (asset ID = documentID) when using both mechanisms.

EDIT:
I just realized where the confusion comes from. The wording

documentId (the unique ID of EDC asset of the certificate)

might be misleading here, i would suggest changing it to

documentId (the unique ID of the certificate)

which is more fitting in my opinion.

If this comes down to interpretation, it means we need to write it explicitly into the standard. If we end up with non-interoperable solutions, then the standard did not do its job. For the pull scenario we explicitly defined the documentId as the EDC assetId.
Since it appears to be not clear for the push scenario, I would suggest the expert group votes on if this also will be defined that way for the push scenario?

Yes exacly! But those IDs are 2 different things.
I can imagine that a provider has the certificate persisted somewhere with this metadata including documentID, and can expose this certificate in 2 different edcs for 2 different use cases (for whatever reason). Then the 'documentID' as reference to asset id makes no sense in this case as there can be multiple asset Ids (?). It also creates a dependency to the asset Id - and what if this changes?

That is why I'm more on saying:

documentId (present in CM APIs) = the unique ID of EDC asset of the certificate

documentID (present in Certificate metadata) = some internal certificate ID of the provider, not related to the asset id.

Sorry but i can't find any explicit requirement for the naming of certificate assets (for the pull mechanism), the only thing i found is the following:

The following sections detail how notification API and certificate assets should be offered in the dataspace. Please note the depicted examples show @id fields with random example UUIDs. Every dataspace participant may use their individual random uuid.

Also, to search for certificate assets with a catalog request, following requirements are specified:

The certificate assets MUST be created by the Certificate Provider in their connector catalog to be consumed by the Certificate Consumer. The property certificateType MUST reference the type of the certificate as defined in 3.2.2 Certificate Type. The property enclosedSites MUST contain all BPNSs for which the certificate is valid. The subject MUST reference cx-taxo:CompanyCertificate. Additionally, the assets MUST contain the type cx-taxo:Submodel and the semanticId specified in 3.1.2 Business Partner Company Certificate Submodel.

Also, this hint:

The certificate assets are identified by the combination of dct:subject, dct:certificateType and dct:enclosedSites. When searching the EDC catalog for a specific asset for which the assetId is unkown, make use of those properties in the catalog filter.

Sorry but i can't find any explicit requirement for the naming of certificate assets (for the pull mechanism), the only thing i found is the following:

The following sections detail how notification API and certificate assets should be offered in the dataspace. Please note the depicted examples show @id fields with random example UUIDs. Every dataspace participant may use their individual random uuid.

Also, to search for certificate assets with a catalog requests, following requirements are specified:

The certificate assets MUST be created by the Certificate Provider in their connector catalog to be consumed by the Certificate Consumer. The property certificateType MUST reference the type of the certificate as defined in 3.2.2 Certificate Type. The property enclosedSites MUST contain all BPNSs for which the certificate is valid. The subject MUST reference cx-taxo:CompanyCertificate. Additionally, the assets MUST contain the type cx-taxo:Submodel and the semanticId specified in 3.1.2 Business Partner Company Certificate Submodel.

Also, this hint:

The certificate assets are identified by the combination of dct:subject, dct:certificateType and dct:enclosedSites. When searching the EDC catalog for a specific asset for which the assetId is unkown, make use of those properties in the catalog filter.

So for me, this documentID in the Certificate metadata (Push content) is nothing more but an internal ID.
We search those assets using only the criterias you mentioned here.

leszekszajnowski · 2025-11-19T15:01:49Z

2.1.1.3 Company Certificate Feedback (and following) -> Please change it back from Status to Feedback, since this is where the Consumer provides Feedback to the Provider. We explicitly changed the naming from Status to Feedback, to make this clear. (Also in the Context change it to Feedback: "context": "CompanyCertificateManagement-CCMAPI-Feedback:1.0.0" (also revert back in 2.1.5.1 and 2.1.5.2)

Maybe I miss understood you, but do you want to change the endpoint from /status to /feedback ? Because that would be a breaking change.

In 2.1.4.1 Notification API you describe the API as 'Notification API'; I'd argue that this is not a notification API, but just an API, so perhaps it makes sense to drop the "notification" and just call it 'cx-taxo:CompanyCertificateApi'? But I also don't have strong feelings about keeping the naming as is now.

That would be also a breaking change, as this is one of the property used to search this asset in the catalog call.

FEILSTE · 2025-11-19T15:38:05Z

2.1.1.3 Company Certificate Feedback (and following) -> Please change it back from Status to Feedback, since this is where the Consumer provides Feedback to the Provider. We explicitly changed the naming from Status to Feedback, to make this clear. (Also in the Context change it to Feedback: "context": "CompanyCertificateManagement-CCMAPI-Feedback:1.0.0" (also revert back in 2.1.5.1 and 2.1.5.2)

Maybe I miss understood you, but do you want to change the endpoint from /status to /feedback ? Because that would be a breaking change.

In 2.1.4.1 Notification API you describe the API as 'Notification API'; I'd argue that this is not a notification API, but just an API, so perhaps it makes sense to drop the "notification" and just call it 'cx-taxo:CompanyCertificateApi'? But I also don't have strong feelings about keeping the naming as is now.

That would be also a breaking change, as this is one of the property used to search this asset in the catalog call.

Yes to both;
But as I wrote, it would be fine for me that the second change is postponed and discussed again to a later date.
To the first point though: feedback and status are two different things. The request API for the pull method now provides the status of the request as a polling mechanism. The feedback api is used by both methods (pull and push), and what is provided to this api is business feedback (accept, reject, ...) to a specific certificate and not the status of a process. This is why I would like to keep the naming change from status to feedback in the standard. We could - to prevent a breaking change - leave the context the same (Status instead of Feedback), but I would like to at least update the wording in the standard to use Feedback instead of Status in all the describing text and the headings. Then a later update could do the breaking change and rename the context.

…/update' into docs/company-certiciate-standard/update-fix-merge-conflicts

FEILSTE · 2025-11-25T10:08:28Z

+Business Application Provider:
+
+- Business Application Provider **MUST** implement all features of the Certificate Notification API, including the support of the push, the pull and also the feedback and available mechanism.
+- Business Application Provider **MUST** offer the push mechanism option to the Certificate Consumer application user, if the Certificate Consumer supports the push mechanism.


Can you change it to:

Business Application Provider MUST offer the push mechanism option to the application user, if the Certificate Consumer supports the push mechanism." Since of course it would be the Certificate Provider who uses the push mechanism.

…/update' into docs/company-certiciate-standard/update-fix-merge-conflicts

…merge-conflicts

…/update' into docs/company-certiciate-standard/update-fix-merge-conflicts

leszekszajnowski · 2025-11-26T10:44:25Z

+    "version": "3.1.0"
+  },
+  "content": {
+    "requestStatus": "IN_PROGRESS"


If the /request is answered with "requestStatus": "IN_PROGRESS", how to answer with a follow up call with
"content": { "documentId": "00000000-0000-0000-0000-000000000001", "requestStatus": "COMPLETED" }

or with REJECTED ?

This is not part of the /status (where there is no requestStatus field call) so how should it work ?

The request mechanism is designed to be polled. The Certificate Consumer needs to repeatedly call the / request endpoint of the Certificate Provider until the requestStatus is in a final state, therefore COMPLETED or REJECTED. If the final state is COMPLETED, the Certificate Consumer can consume the certificate from the Certificate Provider with the pull mechanism.

ok, thanks @PaddseL :)

FEILSTE · 2025-11-26T12:17:06Z

Thank you @PaddseL ; I won't be able to make it to today's sync, but this gets an approval from MB side.

…/update' into docs/company-certiciate-standard/update-fix-merge-conflicts

leszekszajnowski · 2025-12-01T18:59:59Z

The added comment regarding the locations in the certififcate request is accurate.

Thanks Patrick!

nicoprow and others added 30 commits July 24, 2025 18:09

Update CX-0135-CompanyCertificateManagement.md

98a8484

first draft for revising response codes

Update CX-0135-CompanyCertificateManagement.md

297f260

WIP

Update CX-0135-CompanyCertificateManagement.md

4f426f4

Added fixes.

Added state machine image.

4206eab

Update CX-0135-CompanyCertificateManagement.md

340d71f

Fixed image link.

Update CX-0135-CompanyCertificateManagement.md

698dcbc

Fixed typo

Update CX-0135-CompanyCertificateManagement.md

06c4b63

WIP

Update CX-0135-CompanyCertificateManagement.md

665d507

WIP

Update CX-0135-CompanyCertificateManagement.md

53fbade

WIP

Add placeholder roles for certificate provider and certificate consumer.

1a66b71

Adapt EDC offers.

Update CX-0135-CompanyCertificateManagement.md

cf590e0

Updated section 2.1.5

Add files via upload

1e555a2

Updated state machine image

replace DPPC and DPCC with Certificate Distributor and Certificate Re…

9fc158d

…ceiver. A few additional changes

Adopted renaming for state machine image & fixed typo in API assets.

befd07d

add senderFeedbackUrl to feddback-endpoint request.

cc3e677

Explained EDC HTTP response limitations.

Update CX-0135-CompanyCertificateManagement.md

ad390d7

- Added explanation for use of Certificate Receiver/Distributor terms. - Reworked the information regarding the feedbackUrl (also made them part of the normative standard). - Reworked the Note for the EDC issue with 400 response codes.

Update CX-0135-CompanyCertificateManagement.md

1ea8ee2

Fixed formatting for one **MUST**

Update CX-0135-CompanyCertificateManagement.md

85f728c

Fixed more normative formatting.

Update CX-0135-CompanyCertificateManagement.md

fa2c901

Added comments from todays discussion.

Update CX-0135-CompanyCertificateManagement.md

f5e69ed

Added restriction to one unique asset per API (version/subject)

add first draft of openapi spec for certificate notification API

977a67f

remove inline ToDos and comments

d88211c

Such comments should go onto the pull request on github instead

add submodel reference and add openapi spec to main document.

589a30a

Update based on todays expert group discussion

6c9e0e7

- Added all changes from todays expert group discussion - refactored naming - updated all legacy images and changed them from png to svg

incorporate review remarks

e4a69ab

merge EDC Assets for Certificate Notification API

d0b9c5c

rewording message flow expectations to match one API asset

5f29bf8

fix wordings for certificate type and merging of notification API

fd64040

fix: add missing certificate type examples

15072a0

chore: add link to industry core reference

5451824

PaddseL changed the title ~~Docs/company certiciate standard/update fix merge conflicts~~ docs: company certificate standard/update & fix merge conflicts Nov 12, 2025

leszekszajnowski reviewed Nov 18, 2025

View reviewed changes

PaddseL added 2 commits November 21, 2025 14:28

feat: adjust payloads and example

68b3bcf

chore: use feedback instead of status where applicable

c379040

PaddseL force-pushed the docs/company-certiciate-standard/update-fix-merge-conflicts branch 2 times, most recently from db10d3e to 485baa9 Compare November 21, 2025 13:44

Merge remote-tracking branch 'origin/docs/company-certiciate-standard…

c19428b

…/update' into docs/company-certiciate-standard/update-fix-merge-conflicts

PaddseL force-pushed the docs/company-certiciate-standard/update-fix-merge-conflicts branch from 485baa9 to c19428b Compare November 21, 2025 14:46

FEILSTE reviewed Nov 25, 2025

View reviewed changes

PaddseL added 6 commits November 25, 2025 18:24

chore: apply code review suggestions

49ced3f

Merge remote-tracking branch 'origin/docs/company-certiciate-standard…

103fd7d

…/update' into docs/company-certiciate-standard/update-fix-merge-conflicts

fix: fix linter errors

127d1c8

Merge remote-tracking branch 'origin/docs/company-certiciate-standard…

12249b8

…/update' into docs/company-certiciate-standard/update-fix-merge-conflicts

Merge branch 'main' into docs/company-certiciate-standard/update-fix-…

5e773db

…merge-conflicts

refactor: formatting

52fb8ba

PaddseL force-pushed the docs/company-certiciate-standard/update-fix-merge-conflicts branch from 78f4c8c to 5b9a41d Compare November 25, 2025 18:09

Merge remote-tracking branch 'origin/docs/company-certiciate-standard…

c10f1ca

…/update' into docs/company-certiciate-standard/update-fix-merge-conflicts

PaddseL force-pushed the docs/company-certiciate-standard/update-fix-merge-conflicts branch from 5b9a41d to c10f1ca Compare November 25, 2025 18:20

leszekszajnowski reviewed Nov 26, 2025

View reviewed changes

PaddseL added 5 commits November 27, 2025 15:12

chore: version bump

522823b

Merge remote-tracking branch 'origin/docs/company-certiciate-standard…

8266737

…/update' into docs/company-certiciate-standard/update-fix-merge-conflicts

feat: add hint for locationBpns

78c9bbb

chore: bump version

d857bb6

Merge remote-tracking branch 'origin/docs/company-certiciate-standard…

de64652

…/update' into docs/company-certiciate-standard/update-fix-merge-conflicts

Conversation

PaddseL commented Nov 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

FEILSTE commented Nov 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PaddseL Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leszekszajnowski Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

PaddseL Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leszekszajnowski commented Nov 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

FEILSTE commented Nov 19, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

leszekszajnowski Nov 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

FEILSTE commented Nov 26, 2025

Uh oh!

leszekszajnowski commented Dec 1, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

PaddseL commented Nov 12, 2025 •

edited

Loading

PaddseL Nov 19, 2025 •

edited

Loading

leszekszajnowski Nov 19, 2025 •

edited

Loading

PaddseL Nov 19, 2025 •

edited

Loading

leszekszajnowski commented Nov 19, 2025 •

edited

Loading

leszekszajnowski Nov 26, 2025 •

edited

Loading