Add support for using phylorefs as specifiers

docs/context/development/phyx.json

@@ -4,6 +4,7 @@
     "rdf": "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
     "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
     "owl": "http://www.w3.org/2002/07/owl#",
+    "skos": "http://www.w3.org/2004/02/skos/core#",
 
     "obo": "http://purl.obolibrary.org/obo/",
     "dwc": "http://rs.tdwg.org/dwc/terms/",
@@ -186,6 +187,12 @@
 
     "title": "dct:title",
 
-    "representsTaxonomicUnits": "obo:CDAO_0000187"
+    "representsTaxonomicUnits": "obo:CDAO_0000187",
+
+    "apomorphy": "testcase:apomorphy",
+    "exactMatch": {
+      "@id": "skos:exactMatch",
+      "@type": "@id"
+    }
   }
 }

docs/context/development/schema.json

@@ -1,5 +1,23 @@
 {
   "definitions": {
+    "id": {
+      "type": "object",
+      "description": "Any entity that can be identified by a URI.",
+      "additionalProperties": false,
+      "properties": {
+        "@id": {
+          "type": "string",
+          "description": "The URI used to identify this entity.",
+          "minLength": 1
+        },
+        "@type": {
+          "type": "string",
+          "description": "The type of this entity.",
+          "minLength": 1
+        }
+      },
+      "required": [ "@id" ]
+    },
     "agent": {
       "type": "object",
       "description": "A person or entity.",
@@ -111,9 +129,7 @@
             }
           },
           "required": [
-            "name",
-            "volume",
-            "identifier"
+            "name"
           ]
         },
         "identifier": {
@@ -164,6 +180,9 @@
             "http://rs.tdwg.org/dwc/terms/Occurrence"
           ]
         },
+        "rdf:ID": {
+          "$ref": "#/definitions/id"
+        },
         "label": {
           "type": "string",
           "minLength": 1
@@ -201,8 +220,6 @@
           },
           "required": [
             "@type",
-            "nomenclaturalCode",
-            "label",
             "nameComplete"
           ]
         }
@@ -277,14 +294,22 @@
       "minItems": 0,
       "items": {
         "required": [
-          "cladeDefinition"
+          "definition"
         ],
         "properties": {
           "regnumId": {
             "type": "string",
             "description": "The identifier of this clade definition in the Regnum database",
             "minLength": 1
           },
+          "phylorefType": {
+            "description": "The type of this phyloreference.",
+            "enum": [
+              "phyloref:PhyloreferenceUsingMaximumClade",
+              "phyloref:PhyloreferenceUsingMinimumClade",
+              "phyloref:PhyloreferenceUsingApomorphy"
+            ]
+          },
           "label": {
             "type": "string",
             "description": "The name or label of this phyloreference."
@@ -313,7 +338,10 @@
             "uniqueItems": true,
             "minItems": 1,
             "items": {
-              "$ref": "#/definitions/taxonomic_unit"
+              "anyOf": [
+                { "$ref": "#/definitions/taxonomic_unit" },
+                { "$ref": "#/definitions/id" }
+              ]
             }
           },
           "externalSpecifiers": {
@@ -322,7 +350,10 @@
             "uniqueItems": true,
             "minItems": 0,
             "items": {
-              "$ref": "#/definitions/taxonomic_unit"
+              "anyOf": [
+                { "$ref": "#/definitions/taxonomic_unit" },
+                { "$ref": "#/definitions/id" }
+              ]
             }
           }
         }

src/wrappers/PhylorefWrapper.js

@@ -2,6 +2,7 @@
 const moment = require('moment');
 const { has, cloneDeep } = require('lodash');
 
+const owlterms = require('../utils/owlterms');
 const { TaxonomicUnitWrapper } = require('./TaxonomicUnitWrapper');
 const { PhylogenyWrapper } = require('./PhylogenyWrapper');
 
@@ -369,10 +370,56 @@ class PhylorefWrapper {
   }
 
   static getIncludesRestrictionForTU(tu) {
+    const tunit = new TaxonomicUnitWrapper(tu).asOWLEquivClass;
+
+    if (has(tunit, '@id')) {
+      // This is a reference! So we treat it differently.
+      const type = tunit['@type'] || '';
+      if (type === 'phyloref:Phyloreference') {
+        // Phyloreferences need to be incorporated directly with a `some` clause.
+        return {
+          '@type': 'owl:Restriction',
+          onProperty: owlterms.CDAO_HAS_DESCENDANT,
+          someValuesFrom: tunit,
+        };
+      }
+
+      // If it's not a Phyloreference, we assume that it is an opaque taxonomic
+      // unit that has been identified with its own URI. In that case, we need
+      // to use the same EXCLUDES_TU property that we usually use.
+    }
+
+    return {
+      '@type': 'owl:Restriction',
+      onProperty: owlterms.PHYLOREF_INCLUDES_TU,
+      someValuesFrom: tunit,
+    };
+  }
+
+  static getExcludesRestrictionForTU(tu) {
+    const tunit = new TaxonomicUnitWrapper(tu).asOWLEquivClass;
+
+    if (has(tunit, '@id')) {
+      // This is a reference! So we treat it differently.
+      const type = tunit['@type'] || '';
+      if (type === 'phyloref:Phyloreference') {
+        // Phyloreferences need to be incorporated directly with a `some` clause.
+        return {
+          '@type': 'owl:Restriction',
+          onProperty: owlterms.PHYLOREF_EXCLUDES_LINEAGE_TO,
+          someValuesFrom: tunit,
+        };
+      }
+
+      // If it's not a Phyloreference, we assume that it is an opaque taxonomic
+      // unit that has been identified with its own URI. In that case, we need
+      // to use the same EXCLUDES_TU property that we usually use.
+    }
+
     return {
       '@type': 'owl:Restriction',
-      onProperty: 'phyloref:includes_TU',
-      someValuesFrom: new TaxonomicUnitWrapper(tu).asOWLEquivClass,
+      onProperty: owlterms.PHYLOREF_EXCLUDES_TU,
+      someValuesFrom: tunit,
     };
   }
 
@@ -387,11 +434,7 @@ class PhylorefWrapper {
       someValuesFrom: {
         '@type': 'owl:Class',
         intersectionOf: [
-          {
-            '@type': 'owl:Restriction',
-            onProperty: 'phyloref:excludes_TU',
-            someValuesFrom: new TaxonomicUnitWrapper(tu1).asOWLEquivClass,
-          },
+          PhylorefWrapper.getExcludesRestrictionForTU(tu1),
           PhylorefWrapper.getIncludesRestrictionForTU(tu2),
         ],
       },
@@ -530,11 +573,7 @@ class PhylorefWrapper {
       '@type': 'owl:Class',
       intersectionOf: [
         includedExpr,
-        {
-          '@type': 'owl:Restriction',
-          onProperty: 'phyloref:excludes_TU',
-          someValuesFrom: new TaxonomicUnitWrapper(tu).asOWLEquivClass,
-        },
+        PhylorefWrapper.getExcludesRestrictionForTU(tu),
       ],
     }];
 
@@ -549,11 +588,7 @@ class PhylorefWrapper {
           {
             '@type': 'owl:Restriction',
             onProperty: 'obo:CDAO_0000144', // has_Ancestor
-            someValuesFrom: {
-              '@type': 'owl:Restriction',
-              onProperty: 'phyloref:excludes_TU',
-              someValuesFrom: new TaxonomicUnitWrapper(tu).asOWLEquivClass,
-            },
+            someValuesFrom: PhylorefWrapper.getExcludesRestrictionForTU(tu),
           },
         ],
       });
@@ -664,19 +699,40 @@ class PhylorefWrapper {
     const internalSpecifiers = phylorefAsJSONLD.internalSpecifiers || [];
     const externalSpecifiers = phylorefAsJSONLD.externalSpecifiers || [];
 
+    // If it is an apomorphy-based class expression, we can't generate logical
+    // expressions for it anyway.
+    const phylorefType = phylorefAsJSONLD.phylorefType;
+    if (
+      (phylorefType && phylorefType === 'phyloref:PhyloreferenceUsingApomorphy')
+      || (has(phylorefAsJSONLD, 'apomorphy'))
+    ) {
+      // This is an apomorphy-based definition!
+      phylorefAsJSONLD.subClassOf = [
+        'phyloref:Phyloreference',
+        'phyloref:PhyloreferenceUsingApomorphy',
+      ];
+
+      return phylorefAsJSONLD;
+    }
+
     // We might need to make component classes.
     // So we reset our component class counts and records.
     PhylorefWrapper.componentClassCount = 0;
     PhylorefWrapper.componentClassesByLabel = {};
     phylorefAsJSONLD.hasComponentClass = [];
 
+    // The type of this phyloreference.
+    let calculatedPhylorefType;
+
     // The list of logical expressions generated for this phyloref.
     let logicalExpressions = [];
 
     if (internalSpecifiers.length === 0) {
       // We can't handle phyloreferences without at least one internal specifier.
       phylorefAsJSONLD.malformedPhyloreference = 'No internal specifiers provided';
     } else if (externalSpecifiers.length > 0) {
+      calculatedPhylorefType = 'phyloref:PhyloreferenceUsingMaximumClade';
+
       // If the phyloreference has at least one external specifier, we
       // can provide a simplified expression for the internal specifier,
       // in the form:
@@ -701,6 +757,8 @@ class PhylorefWrapper {
         );
       }
     } else {
+      calculatedPhylorefType = 'phyloref:PhyloreferenceUsingMinimumClade';
+
       // We only have internal specifiers. We therefore need to use the algorithm in
       // PhylorefWrapper.createClassExpressionsForInternals() to create this expression.
       logicalExpressions = PhylorefWrapper.createClassExpressionsForInternals(
@@ -762,6 +820,15 @@ class PhylorefWrapper {
     }
     phylorefAsJSONLD.subClassOf.push('phyloref:Phyloreference');
 
+    // If the this Phyloref has a phylorefType that differs from the calculated
+    // phyloref type, throw an error.
+    if (has(phylorefAsJSONLD, 'phylorefType') && phylorefAsJSONLD.phylorefType !== calculatedPhylorefType) {
+      throw new Error(
+        `Phyloref ${this.label} has phylorefType set to '${phylorefAsJSONLD.phylorefType}', but it appears to be a '${calculatedPhylorefType}'.`
+      );
+    }
+    phylorefAsJSONLD.subClassOf.push(calculatedPhylorefType);
+
     return phylorefAsJSONLD;
   }
 }

src/wrappers/TaxonomicUnitWrapper.js

@@ -235,6 +235,10 @@ class TaxonomicUnitWrapper {
       return new SpecimenWrapper(this.specimen).asOWLEquivClass;
     }
 
+    // Is this just a reference (i.e. { "@id": <URI> })? If so, return that
+    // unchanged.
+    if (has(this.tunit, '@id')) return this.tunit;
+
     // Nothing we can do, so just ignore it.
     return undefined;
   }