Need for the machine-readable specification of the input-output of all the examples

[vroddon]

As a result of the meeting in Madrid (see the agenda) on Dec. 19th, 2024, it was agreed on the need to specify a common data model for the input data and the output data of the ODRL Evaluator.

Changes derived to this agreement include providing links to the RDF or JSON examples.

[vroddon]

@besteves4 do you voluntueer to create a file in the repo https://w3c.github.io/odrl/formal-semantics/odrlfs.ttl with the new vocabulary needed?
Classes: ComplianceReport, ...
Object properties: deonticState, activationState, etc.
Constraints and their deontic state, performance state, etc.
Please note that we may want to define two implemention levels (basic=yes/no and advance=with explanation), so elements should have the metadata marking this.
At least @YassirSellami , @fornaran , @vroddon to verify this important file!

[joshcornejo]

Based on the diagram:

I've added a placeholder section to my state of the world

        "facts": [
          {
            "issue": 1734701110,  // date represented as an EPOC
            "actor": "54:6b65977c-9dd8-4989-80f4-225b96258645:19399",
            "action": "modify",
            "asset": "54:6b65977c-9dd8-4989-80f4-225b96258645:13275"
          },
          {
            "issue": 1734701110,
            "actor": "54:6b65977c-9dd8-4989-80f4-225b96258645:19399",
            "action": "read",
            "asset": "54:6b65977c-9dd8-4989-80f4-225b96258645:13275"
          },
          {
            "issue": 1734701110,
            "actor": "54:6b65977c-9dd8-4989-80f4-225b96258645:19399",
            "action": "the-last-action", // extended custom action
            "asset": "54:6b65977c-9dd8-4989-80f4-225b96258645:13275"
          }

[joshcornejo]

On the subject of inputs, we should also specify what is the expected name for the endpoint (e.g. some authZen examples have implemented "is")

I have 3 different API:

1. simple, with parameters built as part of the query (useful for simple IoT-type devices):

{url}/{id}/evaluate?actor=""&action=""&asset=""

2. AuthZen compatible

{url}/authz/is/

with a JSON object as part of the BODY:

{
  "subject": {
    "id": "an_uuid"
  },
  "resource": {
    "id": "another_uuid"
  },
  "action": {
    "name": "read"
  },
  "context": {
    "did": "id" // expects the decentralised ID that references the world
  }
}

3. A combined did/AuthZen for advanced mode (agent has "did-awareness"):

{url}/{id}/authz/is/

{
  "subject": {
    "id": "an_uuid"
    // can have more attributes, but not useful in ODRL 2.2
  },
  "resource": {
    "id": "another_uuid"
    // can have more attributes, but not useful in ODRL 2.2
  },
  "action": {
    "name": "read",
  },
  "context": {
    "comment": "The request could also set all the variables",
    "variable_uuid1": { "some_purpose" },            // "purpose"
    "variable_uuid2": { [ "ENG", "SPA", "ITA"] } ,   // "language"
    "variable_uuid3": {                              // "spatial" example 1
      "@context": {
        "geo": "http://www.opengis.net/ont/geosparql#",
        "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
        "dct": "http://purl.org/dc/terms/",
        "ex": "http://example.org/"
      },
      "@id": "ex:VaticanCity",
      "@type": "geo:Feature",
      "rdfs:label": "Vatican City",
      "dct:description": "The Vatican City is an independent city-state enclaved within Rome, Italy.",
      "geo:hasGeometry":  // as a polygon
      {
        "@id": "ex:VaticanGeometry",
        "@type": "geo:Polygon",
        "geo:asWKT": "POLYGON((12.4516 41.9029, 12.4571 41.9029, 12.4571 41.9075, 12.4516 41.9075, 12.4516 41.9029))",
        "rdfs:label": "Boundary of Vatican City"
      },
    "variable_uuid4": {                              // "spatial" example 2
     "@context": {
        "geo": "http://www.opengis.net/ont/geosparql#",
        "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
        "dct": "http://purl.org/dc/terms/",
        "ex": "http://example.org/"
      },
      "@id": "ex:Monaco",
      "@type": "geo:Feature",
      "rdfs:label": "Monaco",
      "dct:description": "Monaco is a sovereign city-state located on the French Riviera in Western Europe.",
      "geo:hasGeometry": // as a point
        {
          "@id": "ex:MonacoCenter",
          "@type": "geo:Point",
          "geo:asWKT": "POINT(7.4246 43.7384)",
          "rdfs:label": "Geometric center of Monaco"
        }
    }
  }
}

Notes:

• the reason you can't set variables in "simple" as part of the query parameters is to prevent limitations on tiny agents
• there is no setting of parameters in option 2 because it is a wrapper of "simple" to achieve AuthZen compatibility

[joshcornejo]

Ramblings for future discussion when using agents on behalf of the named subject:

  "subject": {
    "id": "some_delegate_uuid"
    "delegate": "true|false",
    "function": "assignee"
  }

Note: For security, we wouldn't expect the delegate to know the UUID of "who they are replacing", and we still need to check the policy (no time saved by having that extra information).

The delegate property allows actors to interact with ODRL policies on behalf of a party - in this case the relevant odrl:Assignee mentioned in the policy. (I don't foresee a specific need for the "input" to have any other functions in the subject property, but the same structure could be used if there is an inclusion of other roles in an input)

The evaluation engine can check all the functions and find if there is a relationship (pseudocode):

for each Rule in Policy
    fUuid = extract(party's uuid in the requested function)
    if some_delegate_uuid ∼ fUuid
        collect(Rule)

    # the collection of rules is what will be evaluated

∼ : There's no agreed symbol for "is related to", so this is the closest I could find.