LeftOperand enum is not compliant with IDS or its use of ODRL

[jimmarino]

The info model models the LeftOperand of a constraint as an enum. This means that the infomodel cannot express constraints other than those defined in the enum class. For example, it is impossible to express policies that include usage constraints other than the 17 defined in the enum class.

My understanding of IDS is it supports ODRL and extensible policy constraints so this is a bug in the info model. This is currently a severe blocker for the EDC and need to reach out to the infomodel folks for help.

.cf https://gist.github.com/jimmarino/0e4b1cddc6d42bd704c13e48881797ff

[juliapampus]

Tried to note down some observations, past discussion outcomes, and next steps @jimmarino.

Policy Language in IDS

• IDS extends ODRL: the IDS Usage Control Language was initially defined as a profile of the ODRL language.
• Referring to this comment, IDS introduces pre- and post-duties that could, nevertheless, be mapped to ODRL.
• In IDS, it was tried to map use case requirements to policy classes (see here for templates) and thus, attributes as the left operand or actions were restricted to a number of enums that seemed reasonable.

Action: IDS vs ODRL

Taking a look at this documentation, this is the current status:

• Action: A thing one might be permitted to do or prohibited from doing to something.
  • has super-classes: action
  • is in domain of: action refinement, is included in
  • is in range of: action, is included in
  • has members: aggregate by consumer, aggregate by provider, anonymize, compensate, delete, distribute, ecrypt, grant use, log, modify, next policy, notify, read, track provenance, use, write (16)

ODRL defines top-level actions (use, transfer). According to the documentation, Action terms must be defined using the includedIn property referring to an encompassing Action and either use or transfer as the top-level parent term by transitive means. Details on the includedIn and implies properties can be defined by ODRL profiles.

The ODRL vocabulary defines 72 action types. Some of them appear in IDS, a lot of them not. On top of that, IDS defines other actions (marked cursive).

LeftOperand: IDS vs ODRL

Taking a look at this documentation, this is the current status:

• LeftOperand: Instances of the LeftOperand class are used as the leftOperand of a Constraint.
  • has super-classes: left operand
  • is in domain of: broader LeftOperand
  • is in range of: broader LeftOperand, leftOperand
  • has members: absolute geo-spatial position, count, current event, delay, elapsed time, endpoint, execution system, path to attribute, payAmount, payment, policy evaluation time, purpose, quantity, recurrence rate, security level, state, user (17)
• broader LeftOperand: This LeftOperand is transitively included in the object LeftOperand.

The ODRL vocabulary defines 34 operand types. Same as for actions, some of them appear in IDS, a lot of them not. On top of that, IDS defines other values.

Problem

• The EDC wants to support full ODRL independent from a specific use case. Mapping an ODRL policy to IDS as-is causes information loss in a way it should not. If IDS simply extended ODRL, one could argue that not supporting IDS features is bad but a design decision. However, any information originally expressed in ODRL should be mappable to IDS.
• Members of an IDS Infomodel object are expressed as Java enum classes (in the IDS Infomodel libraries). Thus, custom values cannot be set.

Possible Solution

Long-Term

• Alignment of definition and identifiers for IDS actions and leftOperands (and other attributes that may be restricted by IDS).
• Steps to put into practice:
  1. Change IDS Information Model: new release (v5.x.x.?).
  2. Adapt IDS Infomodel CodeGeneration and IDS Infomodel Serializer to support new IDS Information Model version.
  3. Integrate new libraries into EDC.

Challenges

• Adaptations cannot be integrated in IDS Infomodel v4 because of breaking changes.
• New IDS Infomodel v5 will bring more changes than that.
• No release date for v5 planned for now.
• Work for alignment needs to be done first (difficulties are not to be underestimated because IDS interprets values different from ODRL and thus cannot use the same terms).

Current Work

• IDS Information Model clean up: usage of application profiles; remove duplicated identifiers, use existing (e.g. ids:mediaType to IANA MediaTypes)
• Alignment of ODRL and IDS actions (document in IDS ThinkTank, not accessible -> maybe you could make this a public discussion @Brandstaedter?)

Short-Term ("Quick Fixes")

EDC

• Possible (very bad) workaround for the moment: All java classes (Infomodel lib) support a properties map. An "odrl to ids"-transformer could insert the ODRL Action/leftOperand as a custom property of an fix IDS Action/leftOperand. An "ids to odrl"-transformer knows that and takes this property to map it back to odrl. So in general, we just "forget" all IDS enums and only use the ones from ODRL.

IDS java libraries

(not sure what can be implemented and how)

• Change the IDS Infomodel CodeGeneration (and thus also the serializer) to provide a wrapper class. This could expect the pre-defined enums, but also custom strings - and map this to json-ld.
• Change the IDS Infomodel CodeGeneration (and thus also the serializer) to enrich enum classes with the possibility to add custom strings - on the same level as the default enums, so not as a custom property as mentioned above).

Contact

• IDS Information Model: responsibles from Fraunhofer FIT are @JohannesLipp and @clange
• IDS Usage Control language: responsibles from Fraunhofer IESE are @Brandstaedter and @hosseinzadeha
• IDS Information Model libraries (CodeGen & Serializer): responsible from Fraunhofer IAIS is @timwirtz86
• IESE-side contact person from ODRL: @riannella

[JohannesLipp]

Please also list @PHochmann (https://github.com/PHochmann) as responsible from Fraunhofer FIT for the IDS Information Model, thank you!

[juliapampus]

Due to various reasons (human resources, standardization procedures, etc.) I would vote for an EDC fix, otherwise we cannot include this in current and upcoming milestones @jimmarino. For this, I would create an issue to modify the affected transformer classes, and to keep it easy (and low effort) I would do this after the serializer integration. What do you think?

[jimmarino]

Sorry for the delay. Would another option be to create an alternative implementation of the Constraint interface that sets the getLeftOperand() property to @JsonIgnore and creates another @JsonProperty that is a string type for "leftOperand"?

The one issue that may arise is having the deserializer pick the alternative Constaint implementation when receiving a message.

[juliapampus]

Sounds good at first glance, I think that would have to be tried.

[jimmarino]

I'm fine with that but the fix I suggested looking into would be an EDC fix (the implementation class would be in the EDC repository and under an EDC package). I'm not sure it is feasible but it would involve:

1. Creating an EDC implementation of Constraint with the override method annotated with @JsonIgnore and a new method with JsonProperty
2. Hooking into the InfoModel deserialization (ObjectMapper) to ensure the constraint implementation is properly deserialized to the new Constraint implementation
3. Modifying the transformer class

This would preserve interop but I'm not sure if there are gotchas in this approach.

Jim

[juliapampus]

I see problems with your second point as soon as we integrated the Infomodel Serializer, as you mentioned above. Then, we do not have an ObjectMapper anymore and would cause exceptions. Not sure how or if the serializer classes can be forced to use a customized Infomodel implementation. I guess this would not be that easy if there are no proper interfaces.

[jimmarino]

This can be worked around temporarily by obtaining a reference to the Serializer#mapper field, setting accessible to true, and returning the object instance to register the custom types (no need to override the mapper). It's not ideal, but it would avoid having to use extensible properties for this.

[alexandrudanciu]

Within Catena-X we now have the requirement to support the specification of a (probably non-enforceable) custom usage condition (specific to the ecosystem and independent of ODRL) as a free text string (e.g., english text paragraph). This generic constraint is intended to be used whenever the left operands (i.e., enums specified by the IDSA) are not suitable to express the terms imposed by the data provider.

One obvious approach (also related to this discussion) could be the specification of a USE action, having a constraint, which in turn consists of a custom left operand, an STRING_EQ or DEFINES_AS as operator, and a string as right operand.

Based on the current implementation of the IDS Information Model (regardless of the current EDC implementation), the following fallback alternatives were identified:

• Alternative 1: Contract object referencing an ids:contractDocument (TextResource), which represents the equivalent human-readable encoding of the machine-interpretable contract. This approach is not suitable for the project requirements, as the referenced document content is not embedded in the contract (agreement) and can, therefore, be regarded as mutable.
• Alternative 2: A semantically less expressive but more feasible approach could be attaching the free text paragraph as comment to the action object. This approach needs to be tested and requires an enhancement of the EDC action class and the corresponding transformer.

Regarding semantically desired approach, a corresponding issue was created in the IDSA Information Model repository.

Are there any arguments against the code changes implied by alternative 2 (regardless of the limited semantic expressiveness)?

[juliapampus]

@alexandrudanciu I am not sure if I got your question right. My last comment is referring to a pull request that has been merged 3 months ago. So there is no need to wait for any adaptations from the EDC side.

The EDC allows to define a policy with a LeftOperand including type and value, e.g.:

{
  "edctype": "AtomicConstraint",
  "leftExpression": {
    "edctype": "dataspaceconnector:literalexpression",
    "value": "odrl-instance"
  },
  "rightExpression": {
    "edctype": "dataspaceconnector:literalexpression",
    "value": "..."
  },
  "operator": "EQ"
}

With the Infomodel lib, a representation would not be possible if this "odrl-instance" did not match the pre-defined ids:leftOperand values that are currently implemented as an enum - and do not match all ODRL instances, nor are they extensible:

{
  "@type": "ids:Constraint",
  "@id": "id",
  "ids:operator": {
    "@id": "https://w3id.org/idsa/code/EQ"
  },
  "ids:rightOperand": {
    "@value": "...",
    "@type": "http://www.w3.org/2001/XMLSchema#string"
  },
  "ids:leftOperand": {
    "@id": "https://w3id.org/idsa/code/FIXED_ENUM"
  }
}

The current workaround enables a mapping between EDC and IDS that sets an ODRL instance or any custom values as ids:leftOperand (assuming that source and target system can handle this information):

{
  "@type": "ids:Constraint",
  "@id": "id",
  "ids:leftOperand": "odrl-instance",
  "ids:rightOperand": {
    "@value": "...",
    "@type": "http://www.w3.org/2001/XMLSchema#string"
  },
  "ids:operator": {
    "@id": "https://w3id.org/idsa/code/EQ"
  },
}

[alexandrudanciu]

@juliapampus Great, thank you! I overlooked the reference to the status of the workaround in this discussion

[juliapampus]

Alternative 1: ... This approach is not suitable for the project requirements, as the referenced document content is not embedded in the contract (agreement) and can, therefore, be regarded as mutable.

@alexandrudanciu For your custom usage conditions, I would propose to not use the policy for this, but to add extra information within the contract. E.g. define a condition "unrestricted usage" and append a contract document including custom terms of usage - if it is only about providing human-readable information and not about technical enforcement. E.g. the ids:contract supports an ids:contractAnnex and ids:contractDocument. The EDC's ContractOffer would have to be extended by such a property of type file or string, to then map this to IDS - during the whole negotiation process (offer,agreement, etc.). Why is this not embedded?

[juliapampus]

A policy should enable technical enforcement. And therefore, systems like the EDC stick to ODRL. So an extension of IDS would not be sufficient. The technically perfect solution is a contract document adding extra information, as the contract is the negotiation object and supposed to provide extra stuff for not only technical enforcement but e.g., providing human-readable documents.

[jimmarino]

@alexandrudanciu a few questions:

1. Are these text clauses a duty, permission, or prohibition?
2. Who is responsible for introducing these text clauses into the system and how are they associated with an asset?
3. How would a client "accept/approve" these text clauses during contract negotiation?

Is there a concrete example we can look at?