spec: replace rml:query with rml:iterator

Fixes #28
kg-construct · Sep 18, 2023 · f4d3a0a · f4d3a0a
1 parent 20365d9
commit f4d3a0a
Show file tree

Hide file tree

Showing 9 changed files with 63 additions and 93 deletions.
diff --git a/shapes/io.ttl b/shapes/io.ttl
@@ -35,8 +35,7 @@
     """ ;
     sh:message """
     RML Logical Source requires one rml:source and depending on the source 
-    type: one rml:query, one rml:referenceFormulation and/or 
-    one rml:iterator.
+    type: one rml:referenceFormulation and/or one rml:iterator.
     """ ;
     sh:name "RML Logical Source" ;
     sh:property [ sh:description """
@@ -118,8 +117,8 @@
     such descriptions.
     """ ;
     sh:message """
-    RML Source accepts one or multiple rml:null, one rml:query,
-    one rml:compression, and one rml:encoding. All of them are optional.
+    RML Source accepts one or multiple rml:null, one rml:compression,
+    and one rml:encoding. All of them are optional.
     """ ;
     sh:name "RML Source" ;
     sh:property [ sh:datatype xsd:string ;
@@ -134,26 +133,13 @@
             sh:name "rml:null" ;
             sh:nodeKind sh:Literal ;
             sh:path rml:null ],
-        [ sh:datatype xsd:string ;
-            sh:description """
-        rml:query specifies the query to execute on a data source if that data
-        source suports it.
-        """ ;
-            sh:maxCount 1 ;
-            sh:message """
-        rml:query must be provided as a string Literal.
-        """ ;
-            sh:minCount 0 ;
-            sh:name "rml:query" ;
-            sh:nodeKind sh:Literal ;
-            sh:path rml:query ],
         [ sh:description """
         rml:compression specifies the compression algorithm to use when
         accessing the data source. By default, no compression is applied.
         """ ;
             sh:maxCount 1 ;
             sh:message """
-        rml:query must be provided as an IRI.
+        rml:compression must be provided as an IRI.
         """ ;
             sh:minCount 0 ;
             sh:name "rml:compression" ;
@@ -203,7 +189,7 @@
         """ ;
             sh:maxCount 1 ;
             sh:message """
-        rml:query must be provided as an IRI.
+        rml:compression must be provided as an IRI.
         """ ;
             sh:minCount 0 ;
             sh:name "rml:compression" ;

diff --git a/shapes/logical_source.ttl b/shapes/logical_source.ttl
@@ -19,8 +19,7 @@
     """ ;
     sh:message """
     RML Logical Source requires one rml:source and depending on the source 
-    type: one rml:query, one rml:referenceFormulation and/or 
-    one rml:iterator.
+    type: one rml:referenceFormulation and/or one rml:iterator.
     """ ;
 
     # rml:source

diff --git a/shapes/source.ttl b/shapes/source.ttl
@@ -20,8 +20,8 @@
     such descriptions.
     """ ;
     sh:message """
-    RML Source accepts one or multiple rml:null, one rml:query,
-    one rml:compression, and one rml:encoding. All of them are optional.
+    RML Source accepts one or multiple rml:null, one rml:compression,
+    and one rml:encoding. All of them are optional.
     """ ;
 
     # rml:null
@@ -40,23 +40,6 @@
         sh:datatype xsd:string ;
     ] ; 
 
-    # rml:query
-    sh:property [
-        sh:path rml:query ;
-        sh:name "rml:query" ;
-        sh:description """
-        rml:query specifies the query to execute on a data source if that data
-        source suports it.
-        """ ;
-        sh:message """
-        rml:query must be provided as a string Literal.
-        """ ;
-        sh:minCount 0 ;
-        sh:maxCount 1 ;
-        sh:nodeKind sh:Literal;
-        sh:datatype xsd:string ;
-    ] ; 
-
     # rml:compression
     sh:property [
         sh:path rml:compression ;
@@ -66,7 +49,7 @@
         accessing the data source. By default, no compression is applied.
         """ ;
         sh:message """
-        rml:query must be provided as an IRI.
+        rml:compression must be provided as an IRI.
         """ ;
         sh:minCount 0 ;
         sh:maxCount 1 ;

diff --git a/shapes/target.ttl b/shapes/target.ttl
@@ -33,7 +33,7 @@
         accessing the data target. By default, no compression is applied.
         """ ;
         sh:message """
-        rml:query must be provided as an IRI.
+        rml:compression must be provided as an IRI.
         """ ;
         sh:minCount 0 ;
         sh:maxCount 1 ;

diff --git a/spec/section/overriding-targets.md b/spec/section/overriding-targets.md
@@ -34,15 +34,15 @@ http://dbpedia.org/resource/Melissa_Rauch,Melissa Rauch
 &lt;#SDSourceAccess&gt; a rml:Source, sd:Service;
   sd:endpoint <http://dbpedia.org/sparql/>;
   sd:supportedLanguage sd:SPARQL11Query;
-  sd:resultFormat formats:SPARQL_Results_CSV;
 .
 </pre>
 
 <pre class="ex-mapping">
 &lt;#TriplesMap1&gt; a rml:TriplesMap;
   rml:logicalSource [ a rml:LogicalSource;
     rml:source &lt;#SDSourceAccess&gt;;
-    rml:query """
+    rml:referenceFormulation formats:SPARQL_Results_CSV;
+    rml:iterator """
       PREFIX dbo: <http://dbpedia.org/ontology/>
       PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
       PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
@@ -71,7 +71,8 @@ http://dbpedia.org/resource/Melissa_Rauch,Melissa Rauch
 &lt;#TriplesMap2&gt; a rml:TriplesMap;
   rml:logicalSource [ a rml:LogicalSource;
     rml:source &lt;#SDSourceAccess&gt;;
-    rml:query """
+    rml:referenceFormulation formats:SPARQL_Results_CSV;
+    rml:iterator """
       PREFIX dbo: <http://dbpedia.org/ontology/>
       PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
       PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>
@@ -177,15 +178,15 @@ http://dbpedia.org/resource/Melissa_Rauch,Melissa Rauch
 &lt;#SDSourceAccess&gt; a rml:Source, sd:Service;
   sd:endpoint <http://dbpedia.org/sparql/>;
   sd:supportedLanguage sd:SPARQL11Query;
-  sd:resultFormat formats:SPARQL_Results_CSV;
 .
 </pre>
 
 <pre class="ex-mapping">
 &lt;#TriplesMap&gt; a rml:TriplesMap;
   rml:logicalSource [ a rml:LogicalSource;
     rml:source &lt;#SDSourceAccess&gt;;
-    rml:query """
+    rml:referenceFormulation formats:SPARQL_Results_CSV;
+    rml:iterator """
       PREFIX dbo: <http://dbpedia.org/ontology/>
       PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
       PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#>

diff --git a/spec/section/source-vocabulary.md b/spec/section/source-vocabulary.md
@@ -71,13 +71,22 @@ with default parameters
 - `rml:XPathReferenceFormulation`: XML documents with optionally
 the definition of XML namespaces used in references.
 By default, no namespaces are defined.
+- `rml:SQL2008Query`: SQL query for a relational database.
+- `rml:SQL2008Table`: Shortcut to select all columns from a SQL table.
 
 `rml:XPathReferenceFormulation` may specify zero or more 
 `rml:namespace` properties with a `rml:Namespace`.
 A `rml:Namespace` contains the following required properties:
  - `rml:namespacePrefix`: A Literal with the prefix used for the XML namespace.
  - `rml:namespaceURL`: A Literal with the URL identifying the XML namespace.
 
+SPARQL queries iterations can be specified by using the W3C Formats namespace:
+
+- `formats:SPARQL_Results_CSV`: SPARQL results as CSV.
+- `formats:SPARQL_Results_TSV`: SPARQL results as TSV.
+- `formats:SPARQL_Results_JSON`: SPARQL results as JSON.
+- `formats:SPARQL_Results_XML`: SPARQL results as XML.
+
 <pre class="ex-source">
 &lt;#XMLNamespace&gt; a rml:LogicalSource;
      rml:source [ a rml:Source, dcat:Distribution;
@@ -122,12 +131,6 @@ However, JSON has a NULL character specified: `null`,
 this one is used together with the ones specified through `rml:null`.
 - **rml:compression** specifies if the source is compressed
 and the used compression algorithm. Defaults to no compression.
-- **rml:query** defines which query should be applied on the source 
-during access. Example: SPARQL query for a SPARQL endpoint or a SQL query
-for a relational database. Defaults to an empty string.
-This property is a broader version of `rml:sqlQuery`.
-A whole table or view of a relational database can be specified
-through a `SELECT * FROM {table}` query (`rml:tableName` compatibility).
 
 <pre class="ex-source">
 &lt;#JSON&gt; a rml:LogicalSource;
@@ -146,8 +149,7 @@ through a `SELECT * FROM {table}` query (`rml:tableName` compatibility).
 | --------------------------- | -------------------- | ------------------------- |
 | `rml:encoding`              | `rml:Source`         | `rml:Encoding`            |
 | `rml:null`                  | `rml:Source`         | `Literal`                 |
-| `rml:compression`           | `rml:Source`         | `rml:Compression`        |
-| `rml:query`                 | `rml:Source`         | `Literal`                 |
+| `rml:compression`           | `rml:Source`         | `rml:Compression`         |
 
 #### NULL values
 
@@ -159,14 +161,6 @@ For example, in relational databases `NULL` is always considered as a NULL
 value while also an empty column can be considered as a NULL value by
 specifying it through `rml:null` in a Source.
 
-#### Query
-
-Each Source MAY specify a query to apply when accessing the source 
-with `rml:query`.
-
-This property is under review in
-[Issue 28](https://github.com/kg-construct/rml-io/issues/28).
-
 #### Compression formats
 
 Each Source MAY specify the compression with `rml:compression`
@@ -226,13 +220,15 @@ the `student` table. The database username and password are provided as well.
         d2rq:jdbcDriver "com.mysql.jdbc.Driver";
         d2rq:username "user";
         d2rq:password "password";
-        rml:query "SELECT * FROM student;";
-        rml:referenceFormulation rml:SQL2008;
     ];
+    rml:iterator "SELECT * FROM student;";
+    rml:referenceFormulation rml:SQL2008Query;
 .
 </pre>
 
-Note that there is no `rml:iterator` present because its default is row.
+A shortcut is available to select all columns from a table,
+such as in the example above, by using the `rml:SQL2008Table`
+as `rml:referenceFormulation`.
 
 The following example shows a Source of a 
 XML file with no compression.
@@ -262,15 +258,16 @@ The following example is GZip compressed JSON file as Source:
 
 Sources can also describe access to SPARQL endpoints with the 
 W3C Service Description ontology. SPARQL endpoints need a SPARQL query, 
-specified by `rml:query`.
+to iterate over.
 
 <pre class="ex-source">
 &lt;#SPARQLEndpoint&gt; a rml:LogicalSource;
     rml:source [ a rml:Source, sd:Service;
         sd:endpoint  &lt;http://example.com/sparql&gt;;
         sd:supportedLanguage sd:SPARQL11Query;
-        rml:query "CONSTRUCT WHERE { ?s ?p ?o. } LIMIT 100";
     ];
+    rml:iterator "CONSTRUCT WHERE { ?s ?p ?o. } LIMIT 100";
+    rml:referenceFormulation formats:SPARQL_Results_CSV;
 .
 </pre>
 

diff --git a/test-cases/RMLSTC0003/mapping.ttl b/test-cases/RMLSTC0003/mapping.ttl
@@ -1,23 +1,25 @@
 @prefix rml: <http://w3id.org/rml/> .
 @prefix foaf: <http://xmlns.com/foaf/0.1/> .
 @prefix void: <http://rdfs.org/ns/void#> .
+@prefix formats: <https://www.w3.org/ns/formats/> .
 @base <http://example.com/rules/> .
 
 <#VoIDSourceAccess> a rml:Source, void:Dataset;
   void:dataDump <file://./Friends.nt>;
-  rml:query """
-  PREFIX foaf: <http://xmlns.com/foaf/0.1/>
-
-  SELECT ?name ?age WHERE {
-    ?person foaf:name ?name .
-    ?person foaf:age ?age .
-  }
-  """;
 .
 
 <#TriplesMap> a rml:TriplesMap;
   rml:logicalSource [ a rml:LogicalSource;
     rml:source <#VoIDSourceAccess>;
+    rml:iterator """
+    PREFIX foaf: <http://xmlns.com/foaf/0.1/>
+
+    SELECT ?name ?age WHERE {
+        ?person foaf:name ?name .
+        ?person foaf:age ?age .
+    }
+    """;
+    rml:referenceFormulation formats:SPARQL_Results_CSV;
   ];
   rml:subjectMap [ a rml:SubjectMap;
     rml:template "http://example.org/{id}";

diff --git a/test-cases/RMLSTC0006b/mapping.ttl b/test-cases/RMLSTC0006b/mapping.ttl
@@ -1,23 +1,25 @@
 @prefix rml: <http://w3id.org/rml/> .
 @prefix foaf: <http://xmlns.com/foaf/0.1/> .
 @prefix void: <http://rdfs.org/ns/void#> .
+@prefix formats: <https://www.w3.org/ns/formats/> .
 @base <http://example.com/rules/> .
 
 <#VoIDSourceAccess> a rml:Source, void:Dataset;
   void:dataDump <file://./Friends.nt>;
-  rml:query """
-  PREFIX foaf: <http://xmlns.com/foaf/0.1/>
-
-  SELECT ?name ?age WHERE {
-    ?person foaf:name ?name .
-    ?person foaf:age ?age .
-  }
-  """;
 .
 
 <#TriplesMap> a rml:TriplesMap;
   rml:logicalSource [ a rml:LogicalSource;
     rml:source <#VoIDSourceAccess>;
+    rml:iterator """
+    PREFIX foaf: <http://xmlns.com/foaf/0.1/>
+
+    SELECT ?name ?age WHERE {
+        ?person foaf:name ?name .
+        ?person foaf:age ?age .
+    }
+    """;
+    rml:referenceFormulation formats:SPARQL_Results_CSV;
   ];
   rml:subjectMap [ a rml:SubjectMap;
     rml:template "http://example.org/{id}";

diff --git a/test-cases/RMLSTC0006c/mapping.ttl b/test-cases/RMLSTC0006c/mapping.ttl
@@ -7,20 +7,20 @@
 <#SDSourceAccess> a rml:Source, sd:Service;
   sd:endpoint <http://example.com/sparql/>;
   sd:supportedLanguage sd:SPARQL11Query;
-  sd:resultFormat formats:SPARQL_Results_CSV;
-  rml:query """
-  PREFIX foaf: <http://xmlns.com/foaf/0.1/>
-
-  SELECT ?name ?age WHERE {
-    ?person foaf:name ?name .
-    ?person foaf:age ?age .
-  }
-  """;
 .
 
 <#TriplesMap> a rml:TriplesMap;
   rml:logicalSource [ a rml:LogicalSource;
     rml:source <#SDSourceAccess>;
+    rml:iterator """
+    PREFIX foaf: <http://xmlns.com/foaf/0.1/>
+
+    SELECT ?name ?age WHERE {
+        ?person foaf:name ?name .
+        ?person foaf:age ?age .
+    }
+    """;
+    rml:referenceFormulation formats:SPARQL_Results_CSV;
   ];
   rml:subjectMap [ a rml:SubjectMap;
     rml:template "http://example.org/{id}";