Merge pull request #141 from kg-construct/127-logical-source

define logical source in core and add spec refs

spec/docs/abstract.md

@@ -1 +1 @@
-This document describes RML, a generic mapping language, based on and extending [R2RML](https://www.w3.org/TR/r2rml). The RDF Mapping language (RML) is a mapping language defined to express customized mapping rules from heterogeneous data structures and serializations to the RDF [RDF-CONCEPTS](https://www.w3.org/TR/rdf-concepts/) data model. RML is defined as a superset of the W3C-standardized mapping language [R2RML](https://www.w3.org/TR/r2rml), aiming to extend its applicability and broaden its scope, adding support for data in other structured formats. [R2RML](https://www.w3.org/TR/r2rml) is the W3C standard to express customized mappings from relational databases to RDF. RML follows exactly the same syntax as R2RML; therefore, RML mappings are themselves RDF graphs. The present document describes the RML-Core language and its concepts through definitions and examples.
+This document describes RML, a generic mapping language, based on and extending [R2RML](https://www.w3.org/TR/r2rml). The RDF Mapping language (RML) is a mapping language defined to express customized mapping rules from heterogeneous data structures and serializations to the RDF [RDF-CONCEPTS](https://www.w3.org/TR/rdf-concepts/) data model. RML is defined as a superset of the W3C-standardized mapping language [R2RML](https://www.w3.org/TR/r2rml), aiming to extend its applicability and broaden its scope, adding support for data in other structured formats. [R2RML](https://www.w3.org/TR/r2rml) is the W3C standard to express customized mappings from relational databases to RDF. RML follows exactly the same syntax as R2RML; therefore, RML mappings are themselves [=RDF graphs=]. The present document describes the RML-Core language and its concepts through definitions and examples.

spec/docs/config.js

@@ -62,12 +62,16 @@ var respecConfig = {
   license: "w3c-software-doc",
   localBiblio: {
     RML: {
-        title: "RDF Mapping Language (RML)",
-        href: "https://rml.io/specs/rml/",
-        status: "Unofficial Draft",
-        publisher: "",
-        date: "",
-      },
+      title: "RDF Mapping Language (RML)",
+      href: "https://rml.io/specs/rml/",
+      status: "Unofficial Draft",
+      publisher: "",
+      date: "",
+    },
+    // TODO: update once RML-IO-Registry is published
+    "RML-IO-Registry": {
+      title: "RML-IO Registry",
+    }
   },
   otherLinks: [
     {

spec/docs/expressions.md

@@ -46,7 +46,7 @@ The [=reference expression set=] of a [=template expression=] is the set of [=re
 
 Sub classes of [=template-valued expression maps=] MAY define a <dfn>reference value transforming function</dfn> which will be applied to each [=reference value=] when evaluating the template.
 
-The <dfn>template value</dfn> when evaluating a [=string template=] for a given [=logical source iteration=] is determined as follows:
+The <dfn>template value</dfn> when evaluating a [=string template=] for a given [=logical iteration=] is determined as follows:
 1. Let `result` be the [=reference expression set=] of the [=string template=]
 2. For each [=reference expression=] in `result`:
     1. Let `values` be the [=reference value=] of the [=reference expression=] that is enclosed in the curly braces

spec/docs/index.html

@@ -96,6 +96,8 @@
 
 <section id="tooling" data-include="tooling.md" data-include-format="markdown"></section>
 
+<section id="logicalSource" data-include="logicalSource.md" data-include-format="markdown"></section>
+
 <section id="mapping" data-include="mapping.md" data-include-format="markdown"></section>
 
 <section id="expressions" data-include="expressions.md" data-include-format="markdown"></section>
@@ -106,6 +108,7 @@
 
 <section id="definitions" data-include="definitions.md" data-include-format="markdown"></section>
 
+<section id="rdfTerminology" class="appendix, informative" data-include="rdfTerminology.md" data-include-format="markdown"></section>
 
 </body>
 

spec/docs/introduction.md

@@ -1,9 +1,9 @@
 # Base IRIs
-The base IRI of the [=mapping document=] is used to resolve relative IRIs in the RML document following the specification of the Turtle serialisaiton.
+The base IRI of the [=mapping document=] is used to resolve relative [=IRIs=] in the RML document following the specification of the Turtle serialisaiton.
 
 ## Base IRI for mapping rules
 
-The [=base IRI=] of the [=Triples Map=] is used in resolving relative IRIs produced by the [=RML mapping=].
+The [=base IRI=] of the [=Triples Map=] is used in resolving relative [=IRIs=] produced by the [=RML mapping=].
 
 
 <pre class="ex-mapping nohighlight">
@@ -13,13 +13,13 @@ The [=base IRI=] of the [=Triples Map=] is used in resolving relative IRIs produ
     rml:baseIri <http://example.com/> .
 </pre>
 
-The [=base IRI=] MUST be a valid IRI. It SHOULD NOT contain question mark (“?”) or hash (“#”) characters and SHOULD end in a slash (“/”) character.
+The [=base IRI=] MUST be a valid [=IRI=]. It SHOULD NOT contain question mark ("`?`") or hash ("`#`") characters and SHOULD end in a slash ("`/`") character.
 
-To obtain an absolute IRI from a relative IRI, the term generation rules of RML use simple string concatenation, rather than the more complex algorithm for resolution of relative URIs defined in Section 5.2 of [RFC3986]. This ensures that the original database value can be reconstructed from the generated absolute IRI. Both algorithms are equivalent if all of the following are true:
+To obtain an absolute [=IRI=] from a relative [=IRI=], the term generation rules of RML use simple string concatenation, rather than the more complex algorithm for resolution of relative URIs defined in Section 5.2 of [RFC3986]. This ensures that the original database value can be reconstructed from the generated absolute [=IRI=]. Both algorithms are equivalent if all of the following are true:
 
     1. The base IRI does not contain question marks or hashes,
     2. the base IRI ends in a slash,
-    3. the relative IRI does not start with a slash, and
-    4. the relative IRI does not contain any “.” or “..” path segments.
+    3. the relative [=IRI=] does not start with a slash, and
+    4. the relative [=IRI=] does not contain any "`.`" or "`..`" path segments.
 
 

spec/docs/joins.md

@@ -19,7 +19,7 @@ as the [Referencing Term Map]()'s [Triples Map]() is known.
 
 The [Referencing Term Map]() (`rml:ReferencingTermMap`) can be
 * a [Referencing Subject Map]() (`rml:ReferencingSubjectMap`)
-if it constructs the subject of an RDF triple.
+if it constructs the subject of an [=RDF triple=].
 
 ```
 <#TM1> 
@@ -33,7 +33,7 @@ if it constructs the subject of an RDF triple.
 If the [Referencing Term Map]() (`rml:ReferencingTermMap`) is
 a [Referencing Subject Map]() (`rml:ReferencingSubjectMap`), then
 the [Parent Term Map]() (`rml:ParentTermMap`)
-should construct an IRI or Blank Node.
+should construct an [=IRI=] or [=blank node=].
 
 The aforementioned could be shortcutted by using the [parent subject map]() (`rml:parentSubjectMap`) property as follows:
 
@@ -48,7 +48,7 @@ The aforementioned could be shortcutted by using the [parent subject map]() (`rm
 ```
 
 * a [Referencing Predicate Map]() (`rml:ReferencingPredicateMap`)
-if it constructs the predicate of an RDF triple.
+if it constructs the predicate of an [=RDF triple=].
 
 ```
 <#TM1> 
@@ -67,7 +67,7 @@ if it constructs the predicate of an RDF triple.
 
 If the [Referencing Term Map]() (`rml:ReferencingTermMap`) is
 a [Referencing Predicate Map]() (`rml:ReferencingPredicateMap`) then
-the [Parent Term Map] should construct an IRI.
+the [Parent Term Map] should construct an [=IRI=].
 
 The aforementioned could be shortcutted using the [parent predicate map]() (`rml:parentPredicateMap`) property as follows:
 
@@ -87,7 +87,7 @@ The aforementioned could be shortcutted using the [parent predicate map]() (`rml
 ```
 
 * a [Referencing Object Map]() (`rml:ReferencingObjectMap`)
-if it constructs the object of an RDF triple.
+if it constructs the object of an [=RDF triple=].
 
 ```
 <#TM1> 
@@ -123,7 +123,7 @@ The aforementioned could be shortcutted using the [parent object map]() (`rml:pa
 ```
 
 * a [Referencing Graph Map]() (`rml:ReferencingGraphMap`)
-if it constructs the graph of an RDF triple.
+if it constructs the graph of an [=RDF triple=].
 
 ```
 <#TM1> 
@@ -240,7 +240,7 @@ The [Parent Term Map]() (`rml:parentTermMap`) can be
 ### Edge cases for Parent Term Maps
 
 **Alternative 1**:
-If the Referencing Term Map of the Parent Tiples Map could/should not construct any RDF triples, 
+If the Referencing Term Map of the Parent Tiples Map could/should not construct any [=RDF triples=], 
 the Triples Map should not have a Subject Map and/or the Predicate Object Map should not have a Predicate or an Object Map. 
 ```
 <#TM1> 
@@ -257,7 +257,7 @@ the Triples Map should not have a Subject Map and/or the Predicate Object Map sh
 ```
 
 **Alternative 2**:
-If the Referencing Term Map of the Parent Tiples Map could/should not construct any RDF triples, 
+If the Referencing Term Map of the Parent Tiples Map could/should not construct any [=RDF triple=], 
 the Triples Map should not have a Subject Map and the Predicate Object Map should only have a Term Map. 
 ```
 <#TM1> 
@@ -274,7 +274,7 @@ the Triples Map should not have a Subject Map and the Predicate Object Map shoul
 ```
 
 **Alternative 3**:
-If the Referencing Term Map of the Parent Tiples Map should not construct any RDF triples, 
+If the Referencing Term Map of the Parent Tiples Map should not construct any [=RDF triple=], 
 the Triples Map should only have a Logical Source and a Term Map. 
 ```
 <#TM1> 
@@ -296,14 +296,14 @@ has exactly one value for each of the following two properties:
 
 * a [child map]() (`rml:childMap`),
 whose value is an [Expression Map]() (`rml:ExpressionMap'), which
-MUST include references that exists in the [Logical Source]()
+MUST include references that exists in the [=logical source=]
 of the [Triples Map]() that contains the [Referencing Object Map]()
 or it should have a constant value.
 
 * a [parent map]() (`rml:parentMap`),
 whose value is an [Expression Map]() (`rml:ExpressionMap'), which,
 as the join condition's parent map, 
-MUST include references that exists in the [Logical Source]()
+MUST include references that exists in the [=logical source=]
 of the [Referencing Object Map]()'s [Parent Triples Map]()
 or it should have a constant value.
 

spec/docs/logicalSource.md

@@ -0,0 +1,15 @@
+# Defining Logical Sources
+
+A <dfn>logical source</dfn> is an abstract construct to describe data access and iteration for a [=data source=] such that it can be mapped to [=RDF triples=].
+
+A [=logical source=] (`rml:LogicalSource`) MUST have:
+* exactly one `rml:referenceFormulation` property, whose value is a <dfn>reference formulation</dfn> which defines how the underlying [=data source=] is to be accessed, and which [=expressions=] can be evaluated on [=logical iterations=],
+* zero or one `rml:iterator` property, whose value is a <dfn data-lt="iterator">logical iterator</dfn> that defines a sequence of [=logical iterations=] on the [=data source=]. If no [=iterator=] is provided, a <dfn class="lint-ignore">default iterator</dfn> MUST be associated with the [=reference formulation=].
+
+A <dfn data-lt="iteration">logical iteration</dfn> is an item in the sequence produced by the [=logical source=], on which [=expressions=] can be evaluated.
+
+A <dfn>data source</dfn> is an abstract concept that represents a source of data that can be accessed via a [=logical source=]. A [=data source=] can be a file, a database, a web service, or any other source of data.
+
+<aside class="note">
+There can be many different types of [=reference formulation=]. The known types, and the details of how a reference formulation is handled and implemented for each data format, are specified in [[RML-IO-Registry]].
+</aside>

spec/docs/mapping.md

@@ -1,93 +1,71 @@
 # Mapping to RDF with Triples Maps
 
-A <dfn>triples map</dfn> specifies a set of rules for translating
-each iteration of a [=logical source=] to zero or more RDF triples.
+A <dfn>triples map</dfn> specifies a set of rules for translating each [=iteration=] of a [=logical source=] to zero or more [=RDF triple=].
 
-All RDF triples generated from one [=logical iteration=] in the [=logical source=] share the same subject.
+All [=RDF triples=] generated from one [=logical iteration=] in the [=logical source=] share the same [=subject=].
 
-A [=triples map=] is represented by a resource that references the following other resources:
+A [=triples map=] is represented by a [=resource=] that references the following other [=resources=]:
 
-* It MUST have zero or one [=logical source=] (`rml:logicalSource`) property.  The [=logical source=] property MAY only be omitted if all of the [=term maps=] of the [=triples map=] are [=constant-valued term maps=].
-* It MUST have exactly one [=subject map=] (`rml:SubjectMap`) that specifies
-how to generate a subject for each iteration of the [=Logical Source=].
+* It MUST have zero or one [=logical source=] (`rml:logicalSource`) property.
+* It MUST have exactly one [=subject map=] (`rml:SubjectMap`) that specifies how to generate a subject for each [=iteration=] of the [=logical source=].
 It may be specified in two ways:
-    1. using the subject map `rml:subjectMap` property, 
-  whose value MUST be the [=subject map=], or
-    2. using the constant shortcut property (``rml:subject``),
-  followed by a constant IRI.
-* It MUST have zero or more predicate-object maps (`rml:predicateObjectMap`) properties,
-whose values MUST be [=predicate-object maps=].
-They specify pairs of [=predicate maps=] and [=object maps=] that,
-together with the subjects generated by the [=subject map=],
-may form one or more [=RDF triples=] for each iteration.
-
-```
-<#TM> 
-  rml:LogicalSource <#LS> ;
-  rml:subjectMap <#SM> ;
-  rml:predicateObjectMap <#POM1>, <#POM2>, ..., <#POMn> . 
-```
+    1. using the subject map `rml:subjectMap` property,  whose value MUST be the [=subject map=], or
+    2. using the [=constant shortcut property=] (`rml:subject`).
+* It MUST have zero or more predicate-object map (`rml:predicateObjectMap`) properties, whose values MUST be [=predicate-object maps=].
+They specify pairs of [=predicate maps=] and [=object maps=] that, together with the [=subjects=] generated by the [=subject map=], may form one or more [=RDF triples=] for each [=iteration=].
 
 <aside class="note">
 The [=logical source=] on a [=triples map=] can be omitted if all its [=term maps=] produce values irrespective of a logical source. This is the case if all its [=term maps=] are [=constant-valued expression maps=], or have `rml:BlankNode` as [=term type=] and no declared [=expression=].
 </aside>
 
-# Term Maps
+<aside class="example" id="example-triples-map" title="usage of triples map">
 
-<aside class="issue">
-Pano: this seems a bit out of place here. I would expect to then get an overview of all term maps, but that doesnt happen here. It does happen in [[[#termmap]]].
-So seems like these sections can be merged.
-</aside>
+<aside class="ex-mapping">
 
-The referenced data of all [=term maps=] of a [=triples map=]
-([=subject map=], [=predicate maps=], [=object maps=], [=graph maps=])
-MUST be references that exist in the [=term map=]'s logical source.
+```turtle
+<#TM>
+  rml:logicalSource <#LS> ;
+  rml:subjectMap <#SM> ;
+  rml:predicateObjectMap <#POM1>, <#POM2>, ..., <#POMn> .
+```
+
+</aside>
 
-<aside class="issue">
-Pano: what does it mean for a reference (for example an xpath query) to exist in a logical source?
 </aside>
 
-# Subject Maps
+## Creating Resources with Subject Maps
 
-A <dfn>subject map</dfn> is a [=term map=]. 
-It specifies a rule for generating the subjects of the [=RDF triples=]
-generated by a [=triples map=].
+A <dfn>subject map</dfn> is a [=term map=]. It specifies a rule for generating the [=subjects=] of the [=RDF triples=] generated by a [=triples map=].
 
 ## Typing Resources (rml:class)
 
-A [=subject map=] MAY have one or more _**class IRIs**_.
-They are represented by the `rml:class` property.
+A [=subject map=] MAY have one or more _**class IRIs**_. They are represented by the `rml:class` property.
 The values of the `rml:class` property MUST be [=IRIs=].
-For each [=RDF term=] generated by the [=subject map=],
-[=RDF triples=] with predicate `rdf:type` and the class IRI as object will be generated.
+For each [=RDF term=] generated by the [=subject map=], [=RDF triples=] with [=predicate=] `rdf:type` and the class [=IRI=] as [=object=] will be generated.
 
 <aside class="note">
-Mappings where the class IRI is not constant,
+Mappings where the class [=IRI=] is not constant,
 but needs to be computed based on the contents of the database,
 can be achieved by defining a [=predicate-object map=] with predicate `rdf:type`
 and a non-constant [=object map=].
 </aside>
 
 ## Creating Properties and Values with Predicate-Object Maps
 
-A <dfn>predicate-object map</dfn> is a function
-that creates one or more predicate-object pairs
-for each logical iteration of a logical data source.
-It is used in conjunction with a [=subject map=]
-to generate [=RDF triples=] in a [=triples map=].
+A <dfn>predicate-object map</dfn> is a function that creates one or more [=predicate=]-[=object=] pairs for each [=logical iteration=] of a [=logical source=].
+It is used in conjunction with a [=subject map=] to generate [=RDF triples=] in a [=triples map=].
 
-A [=predicate-object map=] is represented by a resource
-that references the following other resources:
+A [=predicate-object map=] is represented by a [=resource=] that references the following other [=resources=]:
 
 * One or more [=predicate maps=]. Each of them may be specified in one of two ways:
     1. using the `rml:predicateMap` property, whose value MUST be a [=predicate map=], or
-    2. using the constant shortcut property `rml:predicate`.
+    2. using the [=constant shortcut property=] `rml:predicate`.
 
 * One or more [=object maps=] or referencing [=object maps=].
 Each of them may be specified in one of two ways:
     1. using the `rml:objectMap` property,
     whose value MUST be either an [=object map=], or a [=referencing object map=].
-        using the constant shortcut property `rml:object`.
+        using the [=constant shortcut property=] `rml:object`.
 
 A <dfn>predicate map</dfn> is a [=term map=].