Use SHACL for specifications

[vcharpenay]

In the current version of the interaction and regulation vocabularies, there is a common pattern: for some entity of type X, there also is an entity of type XSpecification, e.g. :BehaviorSpecification and :OrganizationSpecification.

The treament of such entities should be consistent over the different vocabularies.

The most basic approach, used so far, is to consider both the entity and its specification as instances. This ontology design pattern is e.g. implemented in schema.org to distinguish Products (the entity) from ProductModels (the specification). To avoid duplication of information, the class ProductModel is defined as a sub-class of Product, so that a model can be seen as a "template" to copy as-is. The downside of this approach is that some properties that do legitimately apply to a product don't apply to its model (e.g. purchaseDate. It's also not possible to express this "copy" semantics in the standard RDF technology stack.

The alternative would be to express specifications not as instances but as classes. That is, the designer of a hyperMAS or agents themselves do not only instantiate classes but also create new ones. Assuming I'd like to create a specification for a robot behavior to move items from one place to another (be it by gripping, pushing or carrying the item), I would create a class ex:MoveItemBehavior, declare it as subclass of hmas:Behavior and instantiate it every time a robot moves some item. The class ex:MoveItemBehavior is not to be seen as a template anymore but it's possible e.g. to attach a particular form to it (that's the purpose of action specifications) by declaring SHACL constraints on the class. Here is an example:

ex:MoveItemBehavior
  a rdfs:Class, sh:NodeShape ;
  sh:property [
    sh:path prov:used ;
    sh:hasValue ex:form1
  ] .

ex:form1
  a hctl:Form ;
  hctl:hasTarget "/move" .

A third alternative would be to define specifications in OWL but I'd like to limit the options for now.

Any feedback?

(For a quick introduction to SHACL, you can have a look at a lecture I recently gave in our SemWeb lecture.)

[danaivach]

Description of an action specification of type hmas:ActionSpecification:

<http://example.org/simple-agent#send-message> a hmas:ActionSpecification ;
    hmas:hasForm [ a hctl:Form ;
        hctl:forSubprotocol "fipa.mts.mtp.http.std"; # (FIPA Agent Message Transport Protocol for HTTP Specification)
        hctl:target <http://eduroamverw-130-82-25-24.unisg.ch:7778/acc>   
    ] ;
   hmas:expectsInput [ a fipa:Message; 
      hmas:hasSchema [ a sh:NodeShape ;
        sh:targetNode fipa:Message ;
        sh:property [
          sh:path [ sh:inversePath rdf:type ] ;
          sh:minCount 1 ;
          sh:maxCount 1
        ] ;
        sh:property [
            sh:path fipa:hasReceiver ;
            sh:minCount 1;
            sh:maxCount 1 ;
            sh:hasValue <http://example.org/simple-agent#agent> 
        ] ;
        sh:property [
            sh:path fipa:hasPerformative ;
            sh:maxCount 1 ;
            sh:minCount 1;
            sh:hasValue fipa:request # (FIPA Communicative Act Library Specification)
        ] ;
        sh:property [
            sh:path fipa:hasSender ;
            sh:minCount 1 ;
            sh:maxCount 1 ;
            sh:class hmas:Agent
        ] 
      ]
    ].

Description of an action specification of type sh:NodeShape:

<http://example.org/simple-agent#send-message> a sh:NodeShape;
  sh:targetClass hmas:ActionExecution ;
  sh:property [
    sh:path prov:used ;
    sh:hasValue <http://example.org/simple-agent#form>
  ] ;
  sh:property [
    sh:path hmas:hasInput;
    sh:qualifiedValueShape <http://example.org/simple-agent#input>;
    sh:qualifiedMinCount 1 ;
    sh:qualifiedMaxCount 1 
  ] .

<http://example.org/simple-agent#form> a hctl:Form ;
  hctl:forSubprotocol "fipa.mts.mtp.http.std" ;
  hctl:target <http://eduroamverw-130-82-25-24.unisg.ch:7778/acc> .

<http://example.org/simple-agent#input> a sh:NodeShape;
  sh:class hmas:Input, fipa:Message ;
  sh:property [
    sh:path fipa:hasReceiver ;
    sh:hasValue <http://example.org/simple-agent#agent> ;
    sh:minCount 1;
    sh:maxCount 1;
  ] ;
  sh:property [
    sh:path fipa:hasSender ;
    sh:class hmas:Agent;
    sh:minCount 1;
    sh:maxCount 1;
  ] ;
  sh:property [
    sh:path fipa:hasPerformative ;
    sh:hasValue fipa:request;
    sh:minCount 1;
    sh:maxCount 1;
  ] .

ex:action-execution of type hmas:ActionExecution is validated against the SHACL shape:

ex:action-execution a hmas:ActionExecution;
  prov:used <http://example.org/simple-agent#form> ;
  hmas:hasInput [ a hmas:Input, fipa:Message;
    fipa:hasReceiver <http://example.org/simple-agent#agent> ;
    fipa:hasSender <http://example.org/simple-agent-2#agent> ;
    fipa:hasPerformative fipa:request ;
  ].

<http://example.org/simple-agent-2#agent> a hmas:Agent.

[FabienGandon]

Just wondering if instead of hasSchema we shouldn't use hasShape

[maximelefrancois86]

@danaivach I think the shape needs to be changed as follows:

<http://example.org/simple-agent#send-message> a hmas:ActionSpecification ;
    hmas:hasForm [ a hctl:Form ;
        hctl:forSubprotocol "fipa.mts.mtp.http.std"; # (FIPA Agent Message Transport Protocol for HTTP Specification)
        hctl:target <http://eduroamverw-130-82-25-24.unisg.ch:7778/acc>   
    ] ;
   hmas:expectsInput [ a fipa:Message; 
      hmas:hasSchema [ a sh:NodeShape ;
        sh:targetNode fipa:Message ;
        sh:property [
          sh:path [ sh:inversePath rdf:type ] ;
          sh:minCount 1 ;
          sh:maxCount 1 ;
          sh:node [
            sh:property [
                sh:path fipa:hasReceiver ;
                sh:minCount 1;
                sh:maxCount 1 ;
                sh:hasValue <http://example.org/simple-agent#agent> 
            ] ;
            sh:property [
                sh:path fipa:hasPerformative ;
                sh:maxCount 1 ;
                sh:minCount 1;
                sh:hasValue fipa:request # (FIPA Communicative Act Library Specification)
            ] ;
            sh:property [
                sh:path fipa:hasSender ;
                sh:minCount 1 ;
                sh:maxCount 1 ;
                sh:class hmas:Agent
            ] 
          ]
        ] 
      ]
    ].

You can check that the following graph satisfies this shape on the SHACL playground: https://shacl.org/playground/

[] a fipa:Message ;
  fipa:hasReceiver <http://example.org/simple-agent#agent> ;
  fipa:hasPerformative fipa:request ;
  fipa:hasSender [ a hmas:Agent ] .

[danaivach]

Thank you @maximelefrancois86 , could you please clarify why this is more appropriate?

[maximelefrancois86]

Because the first snippet in https://github.com/HyperAgents/ns.hyperagents.org/issues/116#issuecomment-1545515282 specifies that fipa:hasReceiver , fipa:hasPerformative , fipa:hasSender, must apply to fipa:Message. not to its instance.

The following snippet would be valid:

[] a fipa:Message .

fipa:Message fipa:hasReceiver <http://example.org/simple-agent#agent> .
fipa:Message fipa:hasPerformative fipa:request .
fipa:Message fipa:hasSender [ a hmas:Agent ] .

[DrLeturc]

Need to be deeply discussed and validate during the plenary (20min)

[vcharpenay]

I've just created a scenario to try it out on generic CRUD actions using PROV-O. See branch scenario-crud-actions. The scenario takes the example of forums, it is in the disinformation domain.

[danaivach]

Thank you @vcharpenay . I will have to look at it. Here is an example of a SHACL shape that I have used. I am not aware of the best practices on SHACL shapes, so these should be discussed.

@prefix ex: <http://example.org/> .
@prefix hmas: <https://purl.org/hmas/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix prov: <http://www.w3.org/ns/prov#> .
@prefix xs: <https://www.w3.org/2001/XMLSchema#> .
@prefix hctl: <https://www.w3.org/2019/wot/hypermedia#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

ex:moveGripper a sh:NodeShape;
    sh:targetClass hmas:ActionExecution ;
    sh:property [
        sh:path prov:used ;
            sh:minCount 1;
            sh:maxCount 1 ;
            sh:or (
            [ sh:hasValue ex:httpForm ]
            [ sh:hasValue ex:coapForm ]
         ) ;
    ] ;
    sh:property [
        sh:path hmas:hasInput;
            sh:qualifiedValueShape ex:gripperJointShape ;
            sh:qualifiedMinCount 1 ;
            sh:qualifiedMaxCount 1 
    ] .

ex:gripperJointShape a sh:NodeShape ;
    sh:targetClass ex:GripperJoint ;
    sh:property [
        sh:path ex:hasGripperValue ;
        sh:minCount 1;
        sh:maxCount 1 ;
        sh:datatype xs:integer
    ] .

The following would be valid:

@prefix ex: <http://example.org/> .
@prefix hmas: <https://purl.org/hmas/> .
@prefix prov: <http://www.w3.org/ns/prov#> .
@prefix xs: <https://www.w3.org/2001/XMLSchema#> .

[] a hmas:ActionExecution ; 
    prov:used ex:httpForm ;
    hmas:hasInput ex:gripperJoint.

ex:gripperJoint a ex:GripperJoint ;
    ex:hasGripperValue "50"^^xs:integer.

[DrLeturc]

We adopted SHACL for specifications.