Support injection of "direct triples" in RDF output.

RDF consumers might want to get so-called “direct triples”, where each
mapping record is additionally represented by a single triple of the
form

  ?subject_id ?predicate_id ?object_id .

Such triples are not required and are redundant, so we do not emit them
by default, but we add an option to request them.

Author: gouttegd

cli/src/main/java/org/incenp/obofoundry/sssom/cli/SimpleCLI.java

@@ -270,6 +270,10 @@ private void oldEnableSSSOMPyJSON(boolean arg) {
             enableSSSOMPyJSON(arg);
         }
 
+        @Option(names = {"--rdf-direct-triples" },
+                description = "Inject direct triples when writing in RDF/TTL format.")
+        boolean rdfDirectTriples;
+
         @Option(names = {"--sorting" }, negatable = true, defaultValue = "true", fallbackValue = "true",
                 description = "Enable/disable sorting of mappings. This is enabled by default.")
         boolean sortMappings;
@@ -701,6 +705,7 @@ private SSSOMWriter getWriter(String filename, String metaFilename, Serialisatio
             }
             outputOpts.defaultWriteExtraMetadata = ExtraMetadataPolicy.UNDEFINED;
             outputOpts.defaultEnableCondensation = false;
+            ((RDFWriter) writer).setInjectDirectTriples(outputOpts.rdfDirectTriples);
             break;
 
         case TSV:

cli/src/site/apt/index.apt

@@ -285,6 +285,11 @@ sssom-cli set.sssom.tsv:metadata.yaml
   option is equivalent to using <<<--output-format json>>>,
   <<<--json-short-iris>>>, and <<<--json-write-ld-context>>> combined.
 
+  When writing to RDF Turtle, the <<<--rdf-direct-triples>>> option can
+  be used to enable the production of “direct triples” of the form
+  <<<?subject_id ?predicate_id ?object_id .>>>, in addition to the
+  standard reified representation of mapping records.
+  
 ** 2.5. Slot condensation
 
   By default, when writing the result set, “propagatable slots” are

ext/src/main/java/org/incenp/obofoundry/sssom/rdf/RDFConverter.java

@@ -84,6 +84,7 @@ public class RDFConverter {
     private Version assumedVersion = Version.SSSOM_1_0;
     private int bnodeCounter;
     private Set<String> excludedSlots;
+    private boolean directTriples = false;
 
     /**
      * Creates a new instance with the default policy for converting non-standard
@@ -117,6 +118,22 @@ public RDFConverter(ExtraMetadataPolicy policy, Version assumedVersion) {
         this.assumedVersion = assumedVersion;
     }
 
+    /**
+     * Creates a new instance with an explicit policy for converting non-standard
+     * metadata and optionally inject direct triples for mapping records.
+     * 
+     * @param policy            The non-standard metadata policy.
+     * @param withDirectTriples If {@code true}, for every mapping record a direct
+     *                          triple of the form
+     *                          {@code ?subject_id ?predicate_id ?object_id .} will
+     *                          be injected, in addition to the standard reified
+     *                          form.
+     */
+    public RDFConverter(ExtraMetadataPolicy policy, boolean withDirectTriples) {
+        extraPolicy = policy;
+        directTriples = withDirectTriples;
+    }
+
     /*
      * SSSOM to RDF conversions
      */
@@ -237,6 +254,11 @@ public Model toRDF(MappingSet ms, PrefixManager prefixManager) {
             // Add mapping metadata slots
             mappingVisitor.subject = mappingNode;
             mappingHelper.visitSlots(mapping, mappingVisitor);
+
+            if ( injectDirectTriple(mapping) ) {
+                model.add(Values.iri(mapping.getSubjectId()), Values.iri(mapping.getPredicateId()),
+                        Values.iri(mapping.getObjectId()));
+            }
         }
 
         // Add namespace declarations
@@ -418,6 +440,21 @@ private SlotHelper<Mapping> getMappingHelper() {
         return helper;
     }
 
+    /*
+     * Decides whether a mapping should be rendered as a "direct triple".
+     * 
+     * This excludes (1) literal mappings, (2) mappings to sssom:NoTermFound, (3)
+     * negated mappings, as tentatively recommended by the current spec proposal.
+     * This also excludes any mapping that is missing at least one component of the
+     * direct triple; such mappings are not supposed to exist, but there’s nothing
+     * preventing client code from manufacturing one.
+     */
+    private boolean injectDirectTriple(Mapping mapping) {
+        return directTriples && !mapping.isLiteral() && !mapping.isUnmapped()
+                && mapping.getPredicateModifier() != PredicateModifier.NOT && mapping.getSubjectId() != null
+                && mapping.getPredicateId() != null && mapping.getObjectId() != null;
+    }
+
     /*
      * Extract the SSSOM Version value from the RDF model.
      */

ext/src/main/java/org/incenp/obofoundry/sssom/rdf/RDFWriter.java

@@ -42,6 +42,7 @@ public class RDFWriter extends SSSOMWriter {
     private static final String PAV_NS = "http://purl.org/pav/";
 
     private org.eclipse.rdf4j.rio.RDFWriter writer;
+    private boolean directTriples = false;
 
     /**
      * Creates a new instance that will write data to the specified file.
@@ -76,14 +77,27 @@ public RDFWriter(OutputStream stream) {
         writer.getWriterConfig().set(BasicWriterSettings.INLINE_BLANK_NODES, true);
     }
 
+    /**
+     * Configures the writer to inject “direct triples” or not.
+     * 
+     * @param withDirectTriples If {@code true}, for every mapping record the writer
+     *                          will inject a triple of the form
+     *                          {@code ?subject_id ?predicate_id ?object_id .} in
+     *                          addition to the standard reified representation of
+     *                          the record.
+     */
+    public void setInjectDirectTriples(boolean withDirectTriples) {
+        directTriples = withDirectTriples;
+    }
+
     @Override
     protected void doWrite(MappingSet mappingSet) throws IOException {
         // We might need those prefixes as some SSSOM slots are represented in RDF using
         // properties in the corresponding namespaces.
         prefixManager.add("dcterms", DCTERMS_NS);
         prefixManager.add("pav", PAV_NS);
 
-        RDFConverter converter = new RDFConverter(extraPolicy);
+        RDFConverter converter = new RDFConverter(extraPolicy, directTriples);
         converter.excludeMappingSlots(condenseSet(mappingSet));
         Model rdfSet = converter.toRDF(mappingSet, prefixManager);
 

ext/src/test/java/org/incenp/obofoundry/sssom/rdf/RDFWriterTest.java

@@ -134,6 +134,28 @@ void testWriteURIExtensionValue() throws SSSOMFormatException, IOException {
                 (w) -> w.setExtraMetadataPolicy(ExtraMetadataPolicy.UNDEFINED));
     }
 
+    @Test
+    void testWriteDirectTriples() throws IOException {
+        MappingSet ms = getTestSet();
+        ms.getMappings()
+                .add(Mapping.builder().subjectId("https://example.org/entities/0003")
+                        .predicateId("http://www.w3.org/2004/02/skos/core#closeMatch").objectLabel("Third entity")
+                        .objectType(EntityType.RDFS_LITERAL)
+                        .mappingJustification("https://w3id.org/semapv/vocab/ManualMappingCuration").build());
+        ms.getMappings()
+                .add(Mapping.builder().subjectId("https://example.org/entities/0004")
+                        .predicateId("http://www.w3.org/2004/02/skos/core#exactMatch")
+                        .objectId("https://w3id.org/sssom/NoTermFound")
+                        .mappingJustification("https://w3id.org/semapv/vocab/ManualMappingCuration").build());
+        ms.getMappings()
+                .add(Mapping.builder().subjectId("https://example.org/entities/0005")
+                        .predicateId("http://www.w3.org/2004/02/skos/core#exactMatch")
+                        .objectId("https://example.com/entities/0005").predicateModifier(PredicateModifier.NOT)
+                        .mappingJustification("https://w3id.org/semapv/vocab/ManualMappingCuration").build());
+
+        assertWrittenAsExpected(ms, "test-ttl-output-with-direct-triples", null, (w) -> w.setInjectDirectTriples(true));
+    }
+
     private void assertWrittenAsExpected(MappingSet ms, String expectedBasename, String actualBasename,
             Consumer<RDFWriter> consumer) throws IOException {
         if ( actualBasename == null ) {

ext/src/test/resources/output/test-ttl-output-with-direct-triples.ttl

@@ -0,0 +1,63 @@
+@prefix COMENT: <https://example.com/entities/> .
+@prefix COMPID: <https://example.com/people/> .
+@prefix FBbt: <http://purl.obolibrary.org/obo/FBbt_> .
+@prefix ORGENT: <https://example.org/entities/> .
+@prefix ORGPID: <https://example.org/people/> .
+@prefix UBERON: <http://purl.obolibrary.org/obo/UBERON_> .
+@prefix dcterms: <http://purl.org/dc/terms/> .
+@prefix owl: <http://www.w3.org/2002/07/owl#> .
+@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
+@prefix semapv: <https://w3id.org/semapv/vocab/> .
+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+@prefix sssom: <https://w3id.org/sssom/> .
+@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
+
+FBbt:12345678 skos:closeMatch UBERON:1234567 .
+
+ORGENT:0001 skos:closeMatch COMENT:0011 .
+
+ORGENT:0002 skos:closeMatch COMENT:0012 .
+
+<https://example.org/sets/exo2c> a sssom:MappingSet;
+  dcterms:creator COMPID:0000-0000-0002-5678, ORGPID:0000-0000-0001-1234;
+  dcterms:license <https://creativecommons.org/licenses/by/4.0/>;
+  sssom:mappings [ a owl:Axiom;
+      owl:annotatedProperty skos:closeMatch;
+      owl:annotatedSource FBbt:12345678;
+      owl:annotatedTarget UBERON:1234567;
+      sssom:mapping_justification semapv:ManualMappingCuration
+    ], [ a owl:Axiom;
+      owl:annotatedProperty skos:closeMatch;
+      owl:annotatedSource ORGENT:0001;
+      owl:annotatedTarget COMENT:0011;
+      sssom:mapping_justification semapv:ManualMappingCuration;
+      sssom:object_label "alpha";
+      sssom:subject_label "alice";
+      sssom:subject_type owl:Class
+    ], [ a owl:Axiom;
+      owl:annotatedProperty skos:closeMatch;
+      owl:annotatedSource ORGENT:0002;
+      owl:annotatedTarget COMENT:0012;
+      sssom:confidence 7.0E-1;
+      sssom:mapping_justification semapv:ManualMappingCuration;
+      sssom:object_label "beta";
+      sssom:subject_label "bob";
+      sssom:subject_type owl:Class
+    ], [ a owl:Axiom;
+      owl:annotatedProperty skos:closeMatch;
+      owl:annotatedSource ORGENT:0003;
+      sssom:mapping_justification semapv:ManualMappingCuration;
+      sssom:object_label "Third entity";
+      sssom:object_type rdfs:Literal
+    ], [ a owl:Axiom;
+      owl:annotatedProperty skos:exactMatch;
+      owl:annotatedSource ORGENT:0004;
+      owl:annotatedTarget sssom:NoTermFound;
+      sssom:mapping_justification semapv:ManualMappingCuration
+    ], [ a owl:Axiom;
+      owl:annotatedProperty skos:exactMatch;
+      owl:annotatedSource ORGENT:0005;
+      owl:annotatedTarget COMENT:0005;
+      sssom:mapping_justification semapv:ManualMappingCuration;
+      sssom:predicate_modifier sssom:NegatedPredicate
+    ] .