Merge pull request #46 from kg-construct/feature/condition

Added Condition shortcut suggestion

spec/docs/advanced.md

@@ -13,7 +13,10 @@ For an old example, see [RMLFNOTC0018](https://github.com/RMLio/rml-fno-test-cas
 For now, it is unclear how to handle a nested function where that nested Triples Map contains a join condition.
 </p>
 
-```turtle "example": "use nested function"
+<aside class="example" id="example-nested-function" title="usage of nested function">
+<aside class="ex-mapping">
+
+```turtle
 @prefix dbo: <http://dbpedia.org/ontology/> .
 @prefix grel: <http://users.ugent.be/~bjdmeest/function/grel.ttl#> .
 @prefix rml: <http://w3id.org/rml/> .
@@ -64,3 +67,114 @@ For now, it is unclear how to handle a nested function where that nested Triples
             rml:inputValue "-"
         ] .
 ```
+
+</aside>
+</aside>
+
+### Conditions
+
+Conditions are a shortcut to make RML mappings more intuitive, but rely on existing FNML functionality.
+It is a shortcut that is applied using the `rml:condition`: an additional ExpressionMap predicate.
+To be able to use this shortcut, conforming mapping engines MUST support following functions:
+
+- isNull
+- isNotNull
+- equals
+- noEquals
+- IF
+
+<p class="note" title="Condition function definitions">
+  isNotNull and IF are defined below, rest is an excercise for the reader.
+  The actual FnO definitions are TODO.
+</p>
+
+<aside class="example" id="example-condition" title="usage of condition">
+<aside class="ex-mapping">
+
+```turtle
+@prefix dbo: <http://dbpedia.org/ontology/> .
+@prefix fns: <http://example.com/fns#> .
+@prefix rml: <http://w3id.org/rml/> .
+
+<#Person_Mapping>
+    rml:logicalSource <#LogicalSource> ;
+    rml:subjectMap <#SubjectMap> ;
+    rml:predicateObjectMap <#NameMapping> .
+
+<#NameMapping>
+    rml:predicate dbo:title ;
+    # A condition can be defined in any expression map
+    rml:objectMap [
+        # new predicate that links to a function-valued expression map,
+        # that function MUST return a boolean
+        rml:condition [
+            rml:functionExecution [
+                # isNotNull(parameter: X) / definition: X != NULL ? TRUE : FALSE ;
+                rml:function fns:isNotNull ;
+                rml:input [
+                    # The parameter that is checked for NULL
+                    rml:parameter fns:parameter ;
+                    rml:inputValueMap [
+                        rml:reference "name"
+                    ]
+                ]
+            ] ;
+            rml:return fns:boolOut # if fno:boolOut is the first specified return, this triple can be ommitted.
+        ] ;
+        # The actual expression used if the condition returns TRUE
+        rml:constant "[a filled in title]"
+    ] .
+```
+</aside>
+
+This is actually a shortcut to the following
+
+<aside class="ex-mapping">
+
+```turtle
+@prefix dbo: <http://dbpedia.org/ontology/> .
+@prefix fns: <http://example.com/fns#> .
+@prefix rml: <http://w3id.org/rml/> .
+
+<#Person_Mapping>
+    rml:logicalSource <#LogicalSource> ;
+    rml:subjectMap <#SubjectMap> ;
+    rml:predicateObjectMap <#NameMappingExtended> .
+
+<#NameMappingExtended>
+    rml:predicate dbo:title ;
+    rml:objectMap [
+        rml:functionExecution [
+            # IF(bool: X, expression: Y)
+            # Function definition: X === TRUE ? Y : NULL
+            rml:function fns:IF ;
+            rml:input [
+                # = original condition function
+                rml:parameter fns:boolParameter ;
+                rml:inputValueMap [
+                    rml:functionExecution [
+                        rml:function fns:isNotNull ;
+                        rml:input [
+                            rml:parameter fns:parameter ;
+                            rml:inputValueMap [
+                                rml:reference "name"
+                            ]
+                        ]
+                    ]
+                ]
+            ] , [
+                # = original expression
+                rml:parameter fns:expressionParameter ;
+                rml:inputValueMap [
+                    rml:constant "[a filled in title]"
+                ]
+            ]
+        ] ;
+    ] .
+# Any custom function can be used,
+# or nested functions (eg AND/OR),
+# depending on what the engines support
+```
+
+</aside>
+</aside>

spec/docs/config.js

@@ -0,0 +1,105 @@
+async function loadTurtle() {
+    //this is the function you call in 'preProcess', to load the highlighter
+    const worker = await new Promise(resolve => {
+        require(["core/worker"], ({ worker }) => resolve(worker));
+    });
+    const action = "highlight-load-lang";
+    const langURL =
+        "https://cdn.jsdelivr.net/gh/redmer/highlightjs-turtle/src/languages/turtle.js";
+    const propName = "hljsDefineTurtle"; // This funtion is defined in the highlighter being loaded
+    const lang = "turtle"; // this is the class you use to identify the language
+    worker.postMessage({ action, langURL, propName, lang });
+    return new Promise(resolve => {
+        worker.addEventListener("message", function listener({ data }) {
+            const { action: responseAction, lang: responseLang } = data;
+            if (responseAction === action && responseLang === lang) {
+                worker.removeEventListener("message", listener);
+                resolve();
+            }
+        });
+    });
+}
+
+var respecConfig = {
+    // check https://respec.org/docs/ for the meaning of these keys
+    preProcess: [loadTurtle],
+    authors: [
+        {
+            name: "Ben De Meester",
+        },
+        {
+            name: "Samaneh Jozashoori",
+        },
+        {
+            name: "Pano Maria"
+        },
+        {
+            name: "David Chaves-Fraga"
+        },
+        {
+            name: "Anastasia Dimou"
+        },
+    ],
+    edDraftURI: "https://w3id.org/rml/fnml/spec/",
+    editors: [
+        {
+            name: "Ben De Meester",
+            company: "Ghent University – imec – IDLab",
+            url: "https://ben.de-meester.org/#me",
+            orcid: "0000-0003-0248-0987",
+            companyURL: "https://knows.idlab.ugent.be/"
+        }
+    ],
+    formerEditors: [
+        {
+            name: "Anastasia Dimou",
+            url: "https://natadimou.com/#me",
+            orcid: "0000-0003-2138-7972",
+        }
+    ],
+    github: "https://github.com/kg-construct/rml-fnml",
+    latestVersion: null,
+    license: "w3c-software-doc",
+    localBiblio: {
+        RML: {
+            title: "RDF Mapping Language (RML)",
+            href: "https://rml.io/specs/rml/",
+            status: "Unofficial Draft",
+            publisher: "IDLab - imec - Ghent University",
+            date: "08 October 2020",
+        },
+        FnO: {
+            title: "Function Ontology (FnO)",
+            href: "https://w3id.org/function/spec/",
+            status: "Unofficial Draft",
+            publisher: "IDLab - imec - Ghent University",
+            date: "10 November 2021",
+        },
+        CollectionsContainers: {
+            title: "Collections and Containers in RML",
+            href: "https://w3id.org/kg-construct/collections-containers",
+            status: "Unofficial Draft",
+            publisher: "Knowledge Graph Construction W3C Community Group ",
+            date: "16 August 2022",
+        },
+    },
+    otherLinks: [
+        {
+            key: "Website",
+            data: [{
+                value: "https://rml.io",
+                href: "https://rml.io"
+            },
+            {
+                value: "https://fno.io",
+                href: "https://fno.io"
+            }]
+        },
+    ],
+    // shortName: "RML-FNML",
+    specStatus: "CG-DRAFT",
+    // W3C config
+    copyrightStart: "2021",
+    doJsonLd: true,
+    group: "kg-construct",
+};