Should we add an optional property for artifact API base route?

In the dataset manufacturing, some implementation using description logic have been made to simplify the instantiation of a dataset

This logic can simplify a lot the implementation of artifact specification, especially when we have many copies of the same artifact

At this point we are very close to be able to implement pre-made entire Resource Profiles using description logic

Implementing these kind of classes can be very useful from a developper point of view. The main points are:

avoiding a lot of code repetition
on an API change, allowing maintainers to update the description class without touching the instantiation itself

I see two scenarii where it could be useful to instantiate easily entire Resource Profiles:

provide straightforward ways to implement many resource profiles directly related to our ontology that the users should not develop themselves (JaCaMo workspaces/Jade workspaces/HypermediaHMAS platforms/etc)
allow manufacturers to implement their own Resource Profiles for product they sell and provide a URI for customers. These customers would just have to instantiate the provided class to implement their artifacts resource profiles easily

The only problem blocking the developpers to implement such classes are the URLs for the different signifiers that are deeply nested in the sh:NodeShape hierarchy

I would like to launch a discussion here about a property that would be welcome in this context.

It would be an optional parameter, so it would not break anything to what has been made before.

For the sake of the explanation, we will name it hmas:baseRoute but any better name would be appreciated

This property is meant to be attached to a ResourceProfile and would describe the base route to reach to API

Many API work with a base URL completed by specific suffixes to reach specific endpoints. When this property is set we would only have to specify the suffix in the NodeShape Hierarchy.

Then it becomes possible to define for example a robotic arm with different signifiers located on the same URI:

/tcp GET (get the current position)
/tcp/target GET (get the current target)
/tcp/target POST (set the current target)
...

We can then define a emse:CherryBotResourceProfile using description logic and implement our instance of a Cherrybot in a straight-forward way:

robotic-arm-1: a emse:CherryBotResourceProfile ;
    hmas:baseRoute <https://link.to.my.endpoint/robotic-arm-1/> .

What are your thoughts about this?

I think that the motivation and the scenarios are reasonable. Could you confirm that your approach falls under Section 5 of RFC3986, and specifically under the case of 5.1.1 "Base URI Embedded in Content"?

If I were to look for possible disadvantages, these would come from the constraint of using action execution shapes "always" in conjunction with a resource profile to avoid information loss. For example, an Action Execution (AE) could not be validated against an unresolved AE Shape, and an agent couldn't share an unresolved AE Shape with another agent. However, these issues can be mitigated since the use of the base URI property is optional, and the above scenarios of shapes "in-the-wild" are currently rarer than your IRL-motivated scenarios.

Regarding semantics, there is no conflict with hctl:hasTarget (e.g., due to RFC3986 5.1.1). Therefore, I assume that there is no propagated conflict with prov:used.

I think that the motivation and the scenarios are reasonable. Could you confirm that your approach falls under Section 5 of RFC3986, and specifically under the case of 5.1.1 "Base URI Embedded in Content"?

Yes it is exactly what I wanted to express with more barbarian words. By the way according to this document, probably baseURI is a better name

It might be possible to use some OWL logic so that when a baseURI is set, then it propagates into the related shapes by reasoning so that the shape itself could still be used independently

If such a solution is possible, what would be the way you expect the baseURI to be expressed in the data sent by the agent to the artifact?

A solution working fully in OWL RL would be:

to propose terms that allow to implement Signifiers catalogs that can be referenced from anywhere
to propose a term that allow to add extra shapes that an Action Execution targeting an artifact should validate

Example:

On the manufacturer side

siemens:CherrybotReadableOperator a sh:NodeShape ;
    sh:class hmas:ActionExecution ;
    sh:property [
        sh:path prov:used ;
        sh:minQualifiedShape 1 ;
        sh:maxQualifiedShape 1 ;
        sh:qualifiedValueShape [
            sh:class hctl:Form ;
            sh:property hmas:ReadProperty, hmas:GetMethod, hmas:forApplicatonJson, [
                sh:path hctl:hasTarget ;
                sh:minCount 1 ;
                sh:maxCount 1 ;
                sh:hasValue  "/operator"
            ]
        ]
    ] , [
        sh:path hmas:hasOutput ;
        sh:minQualifiedShape 1 ;
        sh:maxQualifiedShape 1 ;
        sh:qualifiedValueShape siemens:JsonGetOperatorOutputBody
    ] .

   <Other signifiers declarations> 

siemens:CherrybotCatalog a hmas:SignifiersCatalog ;
    hmas:proposesSignifier [ hmas:signifies siemens:CherrybotReadableOperator ] ,
    <Other signifiers added to the catalog> .
    ...

On the ontology side we could add:

hmas:SignifiersCatalog a owl:Class ;
    rdfs:label "Catalog"@en, "Catalogue"@en ;
    rdfs:comment "A catalogue of signifiers reusable from a resource profile" .

hmas:proposesSignifier a owl:ObjectProperty ;
    rdfs:domain hmas:SignifiersCatalog ;
    rdfs:range hmas:Signifier .

hmas:exposeSignifiersFrom a owl:ObjectProperty ;
    rdfs:domain hmas:ResourceProfile ;
    rdfs:range hmas:SignifiersCatalog .

hmas:globalSpecification a owl:ObjectProperty ;
    rdfs:label "Global specification"@en ;
    rdfs:label "Additional specification for the data involved in any Action Execution"@en ;
    rdfs:domain hmas:ResourceProfile ;
    rdfs:range sh:NodeShape .

hmas:exposesSignifier a owl:ObjectProperty ;
    rdfs:isDefinedBy hmas:core ;
    rdfs:domain hmas:ResourceProfile ;
    rdfs:range hmas:Signifier ;
    owl:inverseOf hmas:isExposedIn ;
    rdfs:comment "A relation between a resource profile and a signifier it exposes."@en ; 
    rdfs:label "exposes signifier"@en, "expose le signifiant"@fr ;
    dct:source <https://github.com/HyperAgents/ns.hyperagents.org/issues/13#issuecomment-1029349488> ;
    rdfs:seeAlso <https://github.com/HyperAgents/ns.hyperagents.org/issues/13> ;
    owl:propertyChainAxiom (
        hmas:exposeSignifiersFrom
        hmas:proposesSignifier
    ) .

An finally on the developper side:

cup-arm-1: a hmas:ResourceProfile ;
    hmas:exposeSignifiersFrom siemens:CherrybotCatalog ;
    hmas:globalSpecification hmas:AuthorizationHeader, [
        sh:class hmas:ActionExecution ;
        sh:property [
            sh:path hmas:PathToBaseURI ;
            sh:minCount 1 ;
            sh:maxCount 1 ;
            sh:hasValue <https://link.to/cherrybot1/>
        ]
    ] .

cup-arm-2: a hmas:ResourceProfile ;
    hmas:exposeSignifiersFrom siemens:CherrybotCatalog ;
    hmas:globalSpecification hmas:AuthorizationHeader, [
        sh:class hmas:ActionExecution ;
        sh:property [
            sh:path hmas:PathToBaseURI ;
            sh:minCount 1 ;
            sh:maxCount 1 ;
            sh:hasValue <https://link.to/cherrybot2/>
        ]
    ] .

What are your thoughts?

@NicoRobertIn, if part of the proposal is to define these new terms as part of the Core ontology, it would be a good idea to define a motivating scenario that motivates and introduces these terms. This way, the motivation behind the new terms will not be lost by closing the issue, and will become transparent as part of our SAMOD-inspired scenarios.

HyperAgents / hmas

Should we add an optional property for artifact API base route? #229