From f4d3a0a22d51b7823c6d438f440c309ed62db4c2 Mon Sep 17 00:00:00 2001 From: Dylan Van Assche Date: Mon, 18 Sep 2023 11:27:20 +0200 Subject: [PATCH] spec: replace rml:query with rml:iterator Fixes https://github.com/kg-construct/rml-io/issues/28 --- shapes/io.ttl | 24 ++++-------------- shapes/logical_source.ttl | 3 +-- shapes/source.ttl | 23 +++--------------- shapes/target.ttl | 2 +- spec/section/overriding-targets.md | 11 +++++---- spec/section/source-vocabulary.md | 39 ++++++++++++++---------------- test-cases/RMLSTC0003/mapping.ttl | 18 ++++++++------ test-cases/RMLSTC0006b/mapping.ttl | 18 ++++++++------ test-cases/RMLSTC0006c/mapping.ttl | 18 +++++++------- 9 files changed, 63 insertions(+), 93 deletions(-) diff --git a/shapes/io.ttl b/shapes/io.ttl index 24ef500..756b85a 100644 --- 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 index 4805399..870ebe3 100644 --- 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 index 682e0ce..8bb0a8f 100644 --- 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 index 95e22f3..11c8633 100644 --- 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 index 16370e7..f439c0b 100644 --- a/spec/section/overriding-targets.md +++ b/spec/section/overriding-targets.md @@ -34,7 +34,6 @@ http://dbpedia.org/resource/Melissa_Rauch,Melissa Rauch <#SDSourceAccess> a rml:Source, sd:Service; sd:endpoint ; sd:supportedLanguage sd:SPARQL11Query; - sd:resultFormat formats:SPARQL_Results_CSV; . @@ -42,7 +41,8 @@ http://dbpedia.org/resource/Melissa_Rauch,Melissa Rauch <#TriplesMap1> a rml:TriplesMap; rml:logicalSource [ a rml:LogicalSource; rml:source <#SDSourceAccess>; - rml:query """ + rml:referenceFormulation formats:SPARQL_Results_CSV; + rml:iterator """ PREFIX dbo: PREFIX rdf: PREFIX rdfs: @@ -71,7 +71,8 @@ http://dbpedia.org/resource/Melissa_Rauch,Melissa Rauch <#TriplesMap2> a rml:TriplesMap; rml:logicalSource [ a rml:LogicalSource; rml:source <#SDSourceAccess>; - rml:query """ + rml:referenceFormulation formats:SPARQL_Results_CSV; + rml:iterator """ PREFIX dbo: PREFIX rdf: PREFIX rdfs: @@ -177,7 +178,6 @@ http://dbpedia.org/resource/Melissa_Rauch,Melissa Rauch <#SDSourceAccess> a rml:Source, sd:Service; sd:endpoint ; sd:supportedLanguage sd:SPARQL11Query; - sd:resultFormat formats:SPARQL_Results_CSV; . @@ -185,7 +185,8 @@ http://dbpedia.org/resource/Melissa_Rauch,Melissa Rauch <#TriplesMap> a rml:TriplesMap; rml:logicalSource [ a rml:LogicalSource; rml:source <#SDSourceAccess>; - rml:query """ + rml:referenceFormulation formats:SPARQL_Results_CSV; + rml:iterator """ PREFIX dbo: PREFIX rdf: PREFIX rdfs: diff --git a/spec/section/source-vocabulary.md b/spec/section/source-vocabulary.md index 0ee77f3..1534f0f 100644 --- a/spec/section/source-vocabulary.md +++ b/spec/section/source-vocabulary.md @@ -71,6 +71,8 @@ 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`. @@ -78,6 +80,13 @@ 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. + 
 <#XMLNamespace> 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).
 
 
 <#JSON> 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;
 .
 

 
-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.
 
 
 <#SPARQLEndpoint> a rml:LogicalSource;
     rml:source [ a rml:Source, sd:Service;
         sd:endpoint  <http://example.com/sparql>;
         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;
 .
 

 
diff --git a/test-cases/RMLSTC0003/mapping.ttl b/test-cases/RMLSTC0003/mapping.ttl
index 780bf0f..6dd9842 100644
--- a/test-cases/RMLSTC0003/mapping.ttl
+++ b/test-cases/RMLSTC0003/mapping.ttl
@@ -1,23 +1,25 @@
 @prefix rml:  .
 @prefix foaf:  .
 @prefix void:  .
+@prefix formats:  .
 @base  .
 
 <#VoIDSourceAccess> a rml:Source, void:Dataset;
   void:dataDump ;
-  rml:query """
-  PREFIX foaf: 
-
-  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: 
+
+    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
index 780bf0f..6dd9842 100644
--- a/test-cases/RMLSTC0006b/mapping.ttl
+++ b/test-cases/RMLSTC0006b/mapping.ttl
@@ -1,23 +1,25 @@
 @prefix rml:  .
 @prefix foaf:  .
 @prefix void:  .
+@prefix formats:  .
 @base  .
 
 <#VoIDSourceAccess> a rml:Source, void:Dataset;
   void:dataDump ;
-  rml:query """
-  PREFIX foaf: 
-
-  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: 
+
+    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
index 9ede260..d8c7419 100644
--- a/test-cases/RMLSTC0006c/mapping.ttl
+++ b/test-cases/RMLSTC0006c/mapping.ttl
@@ -7,20 +7,20 @@
 <#SDSourceAccess> a rml:Source, sd:Service;
   sd:endpoint ;
   sd:supportedLanguage sd:SPARQL11Query;
-  sd:resultFormat formats:SPARQL_Results_CSV;
-  rml:query """
-  PREFIX foaf: 
-
-  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: 
+
+    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}";