docs(conn): elaborate on CX conventions on Policies

[arnoweiss]

Description

This PR adds a new section to the Connector Kit representing the result of the Data Sovereignty Task Force including some implementation Tips for Data Providers and Enablement Service Providers building Connectors.

Pre-review checks

Please ensure to do as many of the following checks as possible, before asking for committer review:

• DEPENDENCIES are up-to-date. Dash license tool. Committers can open IP issues for restricted libs.
• Copyright and license header are present on all affected files

[matgnt]

even though correct, I think this causes more confusion for the reader then it helps (without an example)

[arnoweiss]

I'm trying to encourage everyone reading to familiarize themselves with the concept of json-ld. Not doing so will lead to even more confusion further down the road.

[matgnt]

Example should be closer to Catena-X, e.g. Dismantler.

[arnoweiss]

As explained - I think there's value in explaining the concepts in the abstract and then narrowing it down to its application in Catena-X

[matgnt]

abstract makes sense, yes. but different use case imho not.

[tom-rm-meyer-ISST]

Same, I would go for the MembershipCredential

[matgnt]

Again, this is something we don't have in CX. We should not use this in our examples.

[arnoweiss]

I think we should explain the generic concept on one page (working-with-policies.md) and their application on another (policies-in-catena.md).

[matgnt]

One minor comment added.

I don't like the examples, because I think they are not 'abstract' but just too far away from our use cases, but other than that, LGTM.

[matgnt]

Formally correct you could say something like:

"...Rule classes constraint property may hold a Constraint or a LogicalConstraint that itself holds - in case of a logical AND - an odrl:and property with a list of Cosntraints."

but this is really a minor comment...

[arnoweiss]

I'd prefer to leave it this way - especially since it also opens the option to

{
  "action": "use",
  "constraint": [
    {
      "leftOperand": "cx-policy:FrameworkAgreement",
      "operator": "eq",
      "rightOperand": "traceability:1.0"
    },
    {
      "leftOperand": "cx-policy:ContractReference",
      "operator": "eq",
      "rightOperand": "x12345"
    },
    {
      "leftOperand": "cx-policy:UsagePurpose",
      "operator": "eq",
      "rightOperand": "cx.core.industrycore:1"
    }
  ]
}

[matgnt]

which is basically also ODRL and there is no way to not allow this - to my understanding.... and btw: your example would have been my preferred solution / documentation examples.
Even though in my text above, I didn't mention this. I just described the LogicalConstraint that we are using - as kind of mandatory - which it isn't.
but as I said, this comment was a minor one. just ignore it :-)

[matgnt]

LGTM

[mhellmeier]

Thanks for fixing and implementing our review comments!

[tom-rm-meyer-ISST]

Got smaller findings. Great contribution, it will help people to better understand how contracts are defined and evaluated!

[tom-rm-meyer-ISST]

Same, I would go for the MembershipCredential

[tom-rm-meyer-ISST]

LGTM

[HFocken]

Thank you for the contribution - much appreciated - a few formal comments to fix, then ready to go.

[HFocken]

Overarching question/comment: could you please add / adapt the Changelog? It was not modified for this PR.

[arnoweiss]

The build is failing due to an error response from clearlydefined, will try again tomorrow morning.

[mhellmeier]

The build is failing due to an error response from clearlydefined, will try again tomorrow morning.

I fixed it in the parallel PR (#875). After it is merged, you just need to merge or rebase main.

[HFocken]

Thanks for addressing all change requests! Good to go from my end!

[mhellmeier]

Thanks for implementing my review comments!

[matgnt]

Only the very recent change in Credential name <-> policy mapping would be left imo.
See:
catenax-eV/cx-odrl-profile#7
Or should we create a separate PR afterwards?

[arnoweiss]

Only the very recent change in Credential name <-> policy mapping would be left imo. See: catenax-eV/cx-odrl-profile#7 Or should we create a separate PR afterwards?

let's create a separate PR when the one you linked is merged.