Instantiate less epo:agentInRole instances

[cristianvasquez]

When dealing with lots, we often encounter multiple epo:agentInRole instances for the same agent-role combination.

An epo:AgentInRole is a construct that represents an Agent playing a role in the context of one or more elements.

Instead of having:

:someAgentInRole1 a epo:Reviewer ;
	epo:playedBy :someOrg ;
	epo:contextualizedBy :someLot1 .

:someAgentInRole2 a epo:Reviewer ;
	epo:playedBy :someOrg ;
	epo:contextualizedBy :someLot2 .

We prefer:

:someAgentInRole a epo:Reviewer ;
	epo:playedBy :someOrg ;
	epo:contextualizedBy :someLot1, :someLot2 .

This approach is simpler and aligns with the intended use of multiple epo:contextualizedBy target values. It is also potentially easier for end users to understand.

Although the owl/shape does not explicitly restrict an agent from playing the same role multiple times, this is what was intended during modelling.

This can be implemented with another URI pattern choice, where the URI of agentInRole is a function of the agent URI and the role type (+uri placeholder where the role is played)

If there are nuances I don't see please comment.

[csnyulas]

We looked into this, and have found a solution to create AgentInRole (subclass) instances that are reused as values for different epo:contextualizedBy relationships. As you suggested we could do this by changing the URI pattern of those instances, replacing the reference to the XPath of the element that we are iterating over (represented by the path() function), with the "content" of the cac:PartyIdentification/cbc:ID element (which in case of the OPT-301-Lot-ReviewOrg field, for example, would be
concat(cac:AppealReceiverParty/cac:PartyIdentification/cbc:ID, cac:AppealReceiverParty/cac:PartyIdentification/cbc:ID/@schemeName)).

We tested this, and it seems to be working. However, as you can see, in such cases the URI generation pattern will become quite complex, and not very intuitive. It will not fall under any of the URI patterns that we have have used so far, and that we documented here. Describing this URI pattern in the documentation will be a challenge, and there is no guarantee that the reader will understand the logic and the need/benefit for why we complicate things.

Please advise if we should go ahead and implement this solution, or not (i.e. keep the current simple but clear solution).

[cristianvasquez]

That's great news!,

Although the pattern might become more complex, it will result in a smaller, simpler graph that is easier to query and explore through applications.

Regarding the documentation I propose we maintain the documentation for the general case, and write down a SHACL document that focuses solely in documenting how URIs are formed for exceptional cases. We can use this document to trace the rationale behind our URI choices.

epo:ReviewerShape a sh:NodeShape ;
    sh:targetClass epo:Reviewer ;
    rdfs:comment "We found identify reviewers in the following way...." ;
    ex:github <https://github.com/OP-TED/ted-rdf-mapping-eforms/issues/31> .

In the future we can expand this documentation to include patterns for the important classes, and validate URIs. For example, this would document how the ex:Movie URI looks like:

ex:MovieShape a sh:NodeShape ;
    sh:targetClass ex:Movie ;
    rdfs:comment "We found that movies are entities that..." ;
    sh:property [
        sh:path sh:targetNode ;
        sh:pattern "^http://example.org/resource/movie/[a-zA-Z0-9\\-]+$" ;
        sh:message "The movie URI must start with 'http://example.org/resource/movie/' followed by alphanumeric characters or hyphens." ;
    ] ;

In summary, let's adopt that URI pattern, and create a SHACL document that documents exceptions. Should we put this close to the documentation?