Solving spec problems

spec/dev.html

@@ -194,9 +194,9 @@
 
 <section id="definitions" data-include="section/definitions.md" data-include-format="markdown"></section>
 
-<section id="rdfTerminology" class="informative" data-include="section/rdfTerminology.md" data-include-format="markdown"></section>
+<section id="rdfTerminology" class="informative" data-include="section/terminology.md" data-include-format="markdown"></section>
 
-<section id="xsdTerminology" class="informative" data-include="section/xsdTerminology.md" data-include-format="markdown"></section>
+<!--<section id="xsdTerminology" class="informative" data-include="section/xsdTerminology.md" data-include-format="markdown"></section>-->
 
 </body>
 

spec/section/graphmap.md

@@ -7,7 +7,7 @@ Any [=subject map=] or [=predicate-object map=] MUST have zero or more associate
 1. using the `rml:graphMap` property, whose value MUST be a [=graph map=],
 2. using the [=constant shortcut property=] `rml:graph`.
 
-[=Graph maps=] are themselves [=term maps=]. When [=RDF triples are generated=], the set of target graphs is determined by taking into account any [=graph maps=] associated with the [=subject map=] or [=predicate-object map=].
+[=Graph maps=] are themselves [=term maps=]. When [=RDF triples=] are generated, the set of target graphs is determined by taking into account any [=graph maps=] associated with the [=subject map=] or [=predicate-object map=].
 
 If a [=graph map=] generates the special IRI `rml:defaultGraph`, then the target graph is the [=default graph=] of the [=output dataset=].
 

spec/section/introduction.md

@@ -1,25 +0,0 @@
-# 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.
-
-## Base IRI for mapping rules
-
-The [=base IRI=] of the [=Triples Map=] is used in resolving relative [=IRIs=] produced by the [=RML mapping=].
-
-
-<pre class="ex-mapping nohighlight">
-# Triples Map that has a declared base IRI
-<#TriplesMap>
-    a rml:TriplesMap;
-    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.
-
-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.
-
-

spec/section/joinconditions.md

@@ -55,9 +55,9 @@ The following RDF triples are generated by the [=RML mapping=] above.
 
 A <dfn data-lt="join">join condition</dfn> is represented by a resource that has exactly one value for each of the following two properties:
 
-* a child map (`rml:childMap`) property, whose value is a [=child map=].<br> A <dfn>child map</dfn> (`rml:ChildMap`) is an [=expression map=] which MUST be evaluated against the [=logical source=] of the [=triples map=] that contains the [=referencing object map=], i.e. the current [=triples map=], or it should have a [=constant value=].
+* a child map (`rml:childMap`) property, whose value is a [=child map=], or a [=constant-valued expression map=].<br> A <dfn>child map</dfn> (`rml:ChildMap`) is an [=expression map=] which MUST be evaluated against the [=child logical source=]. The <dfn>child logical source</dfn> is the [=logical source=] of the [=triples map=] that contains the [=referencing object map=], i.e. the current [=triples map=]..
 
-* a parent map (`rml:parentMap`) property, whose value is a [=parent map=].<br> A <dfn>parent map</dfn> (`rml:ParentMap`) is an [=expression map=], which MUST be evaluated against the [=logical source=] of the [=referencing object map=]'s [=parent triples map=], i.e. the referenced [=triples map=], or it should have a [=constant value=].
+* a parent map (`rml:parentMap`) property, whose value is a [=parent map=], or a [=constant-valued expression map=].<br> A <dfn>parent map</dfn> (`rml:ParentMap`) is an [=expression map=], which MUST be evaluated against the [=parent logical source=]. The <dfn>parent logical source</dfn> is the [=logical source=] of the [=referencing object map=]'s [=parent triples map=], i.e. the referenced [=triples map=].
 
 If the the [=logical source=] of the [=triples map=] that contains the [=referencing object map=] and the [=logical source=] of the [=referencing object map=]'s [=parent triples map=] are not [=effectively equal=], then the referencing object map MUST have one or more [=join conditions=].
 

spec/section/overview.md

@@ -72,7 +72,7 @@ Input source: album.json
     "Description": "A collection of stunning cityscape images.",
     "CreatedDate": "2023-10-01",
     "DateFormat": "date",
-    "Author": "John Doe",
+    "Author": "Zoë Krüger",
     "Images": [
       {
         "ID": 116,

spec/section/rdfTerminology.md → spec/section/terminology.md

@@ -1,4 +1,6 @@
-# RDF Terminology
+# Terminology
+
+## RDF Terminology
 
 This section lists some terms normatively defined in [[RDF11-CONCEPTS]] and used in RML:
 
@@ -24,3 +26,20 @@ This section lists some terms normatively defined in [[RDF11-CONCEPTS]] and used
 - <dfn><a data-cite="RDF11-CONCEPTS#dfn-property">property</a></dfn>
 - <dfn><a data-cite="RDF11-CONCEPTS#dfn-resource">resource</a></dfn>
 - <dfn><a data-cite="RDF11-CONCEPTS#dfn-subject">subject</a></dfn>
+
+
+# XML Schema Definition Language (XSD) Terminology
+
+This section lists some terms normatively defined in [[XMLSCHEMA11-2]] and used in RML:
+
+- <dfn><a data-cite="XMLSCHEMA11-2#datatype">XSD Datatype</a></dfn>
+- <dfn data-lt="XSD Canonical mapping"><a data-cite="XMLSCHEMA11-2#canonical-lexical-representation">Canonical mapping</a></dfn>
+
+
+# Uniform Resource Identifier Terminology 
+
+This section lists some terms normatively defined in [[RFC3986]] and used in RML:
+
+- <dfn><a data-cite="RFC3986#section-1.1.3">URI</a></dfn>
+- <dfn><a data-cite="RFC3986#section-5.2">relative URIs</a></dfn>
+- <dfn><a data-cite="RFC3986#section-2.1">Percent-encode</a></dfn>

spec/section/termmap.md

@@ -1,6 +1,6 @@
 # Term Maps
 
-An <dfn>RDF term</dfn> is either an [=IRI=], or a [=blank node=], or a [=literal=].
+An <dfn>RDF term</dfn> is either an [=IRI=], a [=blank node=], or a [=literal=].
 
 A <dfn>term map</dfn> (`rml:TermMap`) is a rule that defines how to generate an [=RDF term=] from a [=logical iteration=].
 The result of the execution of that rule is the <dfn>generated RDF term</dfn>.
@@ -20,22 +20,25 @@ if it is a rule that specifies how the [=RDF triple=]'s predicate is generated;
 if it is a rule that specifies how the [=RDF triple=]'s object is generated; and
 * a [=graph map=] (`rml:GraphMap`),
 if it is a rule that specifies how the [=RDF triple=]'s [=named graph=] is generated.
+* a [=datatype map=] (`rml:DatatypeMap`),
+if it is a rule that specifies how the [=datatype IRI=]'s of an object is generated.
 
 A [=term map=] generates different types of [=RDF terms=] depending on the position of the [=term map=] in the [=RDF triple=]:
 * a [=subject map=] (`rml:SubjectMap`)
-is a rule that MUST generate either an [=IRI=] or a [=blank node=];
-* a [=predicate map=] (`rml:PredicateMap`)
+is a rule that MUST generate either an [=IRI=], or a [=blank node=];
+* a [=predicate map=] (`rml:PredicateMap`) 
 is a rule that MUST generate an [=IRI=];
 * an [=object map=] (`rml:ObjectMap`)
-is a rule that MUST generate an [=IRI=], a [=blank node=] or a [=literal=];
+is a rule that MUST generate an [=IRI=],  a [=blank node=] or a [=literal=];
 * a [=graph map=] (`rml:GraphMap`)
 is a rule that SHOULD generate an [=IRI=].
+* a [=datatype map=] (`rml:DatatypeMap`)
+is a rule that MUST generate an [=IRI=].
 
 A [=term map=] MUST have
 * 0 or 1 [=datatype map=] or 0 or 1 [=language map=];
 * 0 or 1 [=term type=].
 
-
 ### Constant RDF Terms (`rml:constant`)
 
 A <dfn>constant-valued term map</dfn> is a term map that ignores the [=logical iteration=] and always generates the same [=RDF term=]. A [=constant-valued term map=] is a [=constant-valued expression map=], and is thus represented by a resource that has exactly one `rml:constant` property. The [=constant expression=] MUST be a valid [=RDF term=].
@@ -123,8 +126,8 @@ If the [=term type=] of the [=template-valued term map=] is `rml:IRI`, then a [=
 The <dfn data-lt="IRI-safe">IRI-safe version</dfn> of a string is obtained by applying the following transformation
 to any character that is not in the [`iunreserved` production](http://tools.ietf.org/html/rfc3987#section-2.2) in [[RFC3987]]:
 
-1. Convert the character to a sequence of one or more octets using [UTF-8](http://tools.ietf.org/html/rfc3629) [[RFC3629]]
-2. [Percent-encode](http://tools.ietf.org/html/rfc3986#section-2.1) each octet [[RFC3986]]
+1. Convert the character to a sequence of one or more octets using [UTF-8](http://tools.ietf.org/html/rfc3629) in [[RFC3629]]
+2. [=Percent-encode=] each octet
 
 The following table shows examples of strings and their IRI-safe versions:
 
@@ -138,12 +141,13 @@ The following table shows examples of strings and their IRI-safe versions:
 
 <aside class="note">
 RML always performs percent-encoding when [=IRIs=] are generated from [=string templates=].
-If [=IRIs=] need to be generated without percent-encoding, then `rml:reference` should be used instead of `rml:template`, with a [=logical source=] that performs the string concatenation.
+If [=IRIs=] need to be generated without percent-encoding, then the [=term map=] MUST use
+`rml:UnsafeIRI` as [=term type=].
 </aside>
 
 <aside class="note">
 Term maps with [=term type=] `rml:IRI` cause [=data errors=] if the value is not a valid [=IRI=] (see [=generated RDF term=] for details).
-Data values from the input database may require percent-encoding before they can be used in [=IRIs=].
+Data values from the [=input data source=] may require percent-encoding before they can be used in [=IRIs=].
 [=Template-valued term maps=] are a convenient way of percent-encoding data values.
 </aside>
 
@@ -195,7 +199,7 @@ Using the [=logical iteration=], the [=template value=] of the [=subject map=] w
 <aside class="ex-output">
 
 ```turtle
-<http://data.example.com/author/John%20Doe>
+<http://data.example.com/author/Zoë%20Krüger>
 ```
 
 </aside>
@@ -204,6 +208,35 @@ The space character is not in the [`iunreserved` production](http://tools.ietf.o
 
 </aside>
 
+<aside class="example" id="example-template-iri-safe" title="IRI unsafe template values">
+
+The following example shows how an [=IRI=] unsafe template value is created.
+Here the `album.json` [=input data source=] is used to generate an [=IRI=] using the `Author` name.
+
+<aside class="ex-mapping">
+
+```turtle
+
+<#AuthorTriplesMap>
+  rml:subjectMap [
+    rml:template "http://data.example.com/author/{$.Author}" ;
+    rml:termType rml:UnsafeIRI
+  ] .
+```
+
+</aside>
+
+Using the [=logical iteration=], the [=template value=] of the [=subject map=] would be:
+
+<aside class="ex-output">
+
+```turtle
+<http://data.example.com/author/Zoë Krüger>
+```
+</aside>
+</aside>
+
+
 <aside class="example" id="example-template-backslash-escape" title="Backslash escapes in templates">
 
 The following example shows the use of backslash escapes in string templates. The template will generate a fancy title such as
@@ -235,39 +268,44 @@ Note that because
 
 </aside>
 
-## IRIs, Literal, Blank Nodes (rml:termType)
+## IRIs, URIs, Literal, Blank Nodes (rml:termType)
 
 The <dfn>term type</dfn> of a [=reference-valued term map=] or [=template-valued term map=]
-determines the kind of [=generated RDF term=] ([=IRIs=], [=blank nodes=] or [=literals=]).
+determines the kind of [=generated RDF term=] ([=IRIs=], [=URI=], [=blank nodes=] or [=literals=]).
 
 If the term map has an optional `rml:termType` property,
 then its [=term type=] is the value of that property.
 The value MUST be an [=IRI=] and MUST be one of the following options:
 
-* If the term map is a [=subject map=]: `rml:IRI` or `rml:BlankNode`
-* If the term map is a [=predicate map=]: `rml:IRI`
-* If the term map is an [=object map=]: `rml:IRI`, `rml:BlankNode`, or `rml:Literal`
-* If the term map is a [=graph map=]: `rml:IRI`
+* If the term map is a [=subject map=]: `rml:IRI`, `rml:URI` or `rml:BlankNode`
+* If the term map is a [=predicate map=]: `rml:IRI`, `rml:URI`
+* If the term map is an [=object map=]: `rml:IRI`, `rml:URI`, `rml:BlankNode`, or `rml:Literal`
+* If the term map is a [=graph map=]: `rml:IRI`, `rml:URI`
+
+<aside class="note">
+When [=URIs=] are generated from [=string templates=], RML performs percent-encoding in the same way as for [=IRIs=].
+To generate [=URIs=] without applying percent-encoding, the [=term map=] MUST have a [=term type=] of rml:UnsafeURI.
+</aside>
 
 ### Default Term Types
 
 If the [=term map=] does not have a `rml:termType` property, then its [=term type=] is:
 
 * `rml:IRI`, if it is a [=subject map=], [=predicate map=] or [=graph map=]
-* `rml:Literal`, if it is an [=object map=]
-and at least one of the following conditions is true:
-* It is a [=reference-valued term map=].
-    * It has a `rml:languageMap` property (and thus a specified [=language tag=]).
-    * It has a `rml:datatypeMap` property (and thus a specified [=datatype=]).
-* `rml:IRI`, otherwise.
+* `rml:Literal`, if it is an [=object map=] and at least one of the following conditions is true (`rml:IRI`, otherwise):
+  * It is a [=reference-valued term map=].
+  * It has a `rml:languageMap` property (and thus a specified [=language tag=]).
+  * It has a `rml:datatypeMap` property (and thus a specified [=datatype=]).
+
 
 ### Explicitly Defined Term Types
 
 To change the default [=term type=] of a [=subject map=] or [=graph map=]
-to a [=blank node=], the [=term type=] MUST be explicitly defined to be a `rml:BlankNode`.
+to a [=blank node=], the [=term type=] MUST be explicitly defined to be a `rml:BlankNode` or `rml:URI.
 
 To change the default [=term type=] of an [=object map=], the [=term type=] MUST be explicitly defined:
-* If the [=term type=] is `rml:IRI`, an [=IRI=] will be generated;
+* If the [=term type=] is `rml:IRI`, an [=IRI=] will be generated`;`
+* If the [=term type=] is `rml:URI`, a [=URI=] will be generated`;`
 * If the [=term type=] is `rml:BlankNode`, a [=blank node=] will be generated.
 
 If the [=term type=] is explicitly defined to be a `rml:BlankNode`,
@@ -334,13 +372,23 @@ This creates the following [=RDF triples=].
 
 </aside>
 
+
+<aside class="note">
+The generation of [=language-taggable term map=] in cases where the [=language map=] and its associated [=term map=] 
+require correlated or non-trivial iteration patterns (e.g., alignment of multiple references or nested structures) falls 
+outside the scope of this specification.  
+
+Such advanced iteration behaviour SHOULD be handled using the mechanisms defined in the [RML-LV](https://w3id.org/rml/lv/spec/), 
+which extends RML-Core with logical views and fine-grained control over iteration and data correlation.
+</aside>
+
 ## Datatypes of Literals (`rml:datatypeMap` and `rml:datatype`)
 
-A <dfn>datatypeable term map</dfn> is a [=term map=] with a [=term type=] of `rml:Literal` that does not have a [specified language map](#language-tags-rml-languagemap-and-rml-language).
+A <dfn>datatypeable term map</dfn> is a [=term map=] with a [=term type=] of `rml:Literal` that does not have a specified [=language map=].
 
 [=Datatypeable term maps=] MUST generate zero or more [=literals=]. The [=datatype=] of these [=literals=] can be automatically determined with a [=natural mapping=] (producing a [=natural RDF literal=]), or it can be explicitly specified using a [=datatype map=] (producing a [=datatype-override RDF literal=]).
 
-A <dfn>datatype map</dfn> (`rml:DatatypeMap`) is an [=expression map=]. It specifies a rule for generating one or more [=datatypes=] of a [=datatypeable term map=]. A [=datatype map=] MUST generate a list of [=IRI=] values, in which the [=IRIs=] are the [=datatype IRIs=] of the [=datatypeable term map=].
+A <dfn>datatype map</dfn> (`rml:DatatypeMap`) is a [=term map=]. It specifies a rule for generating one or more [=datatypes=] for a [=datatypeable term map=]. A [=datatype map=] MUST generate a list of [=IRI=] values, in which the [=IRIs=] are the [=datatype IRIs=] of the [=datatypeable term map=].
 
 Given the list of values resulting from a [=datatypeable term map=] `T`, and the list of values resulting from its [=datatype map=] `D`, the resulting terms are generated by the [=n-ary Cartesian product=] combination of `T × D`, where the values in `T` are the [=literal=] values, and the values in `D` are the [=datatype IRIs=].
 

spec/section/tooling.md

@@ -16,21 +16,71 @@ or offer any other means of providing access to the [=output dataset=].
 
 An [=RML processor=] also has access to an execution environment consisting of:
 * A [=logical source=]
-* A base IRI used in resolving relative [=IRIs=] produced by the RML mapping.
+* A [=base IRI=] 
 
 How the [=logical source=] is accessed,
 or how users are authenticated against the database,
 is outside of the scope of this document.
 
-The [=base IRI=] MUST be a valid [=IRI=].
-It SHOULD NOT contain question mark ("`?`") or hash ("`#`") characters and
+#### Base IRI
+A [=base IRI=] is used in resolving relative [=IRIs=] produced by the RML mapping. The [=base IRI=] MUST be 
+defined within the mapping document for each [=Triples Map=] or as execution environment for the [=mapping document=]. 
+
+<aside class="example" id="example-baseIRI-mappings" title="Base IRI example">
+The following [=RML Mapping Document=] maps the album.json input source to [=RDF Triples=] with a base IRI.
+
+<aside class="ex-mapping">
+
+```turtle
+# Triples Map that has a declared base IRI
+<#TriplesMap> a rml:TriplesMap;
+    rml:baseIRI <http://example.com/baseIRI/> ;
+    rml:source [
+      a rml:RelativePathSource ;
+      rml:root rml:MappingDirectory ;
+      rml:path "album.json" ;
+    ] ;
+    rml:iterator "$.Album" ;
+    rml:referenceFormulation rml:JSONPath ;
+  ] ;
+  rml:subjectMap [
+    rml:template "{$.ID}" ;
+    rml:class ex:Album ;
+  ] ;
+  rml:predicateObjectMap [
+    rml:predicate ex:title ;
+    rml:objectMap [
+      rml:reference "$.Title" ;
+    ] ;
+  ] .
+```
+</aside>
+
+The following RDF triples are generated by the [=RML mapping=] above.
+
+<aside class="ex-output">
+
+```turtle
+<http://example.com/baseIRI/43> a ex:Album .
+<http://example.com/baseIRI/43> ex:title "City Views" .
+
+```
+
+</aside>
+
+</aside>
+
+<aside class="note">
+The base IRI of the [=mapping document=] is used to resolve relative [=IRIs=] in the RML document following the specification of the Turtle serialisaiton.
+</aside>
+
+The [=base IRI=] MUST be a valid [=IRI=]. It SHOULD NOT contain question mark ("`?`") or hash ("`#`") characters and 
 SHOULD end in a slash ("`/`") character.
 
 <aside class="note">
 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](https://www.rfc-editor.org/rfc/rfc3986#section-5.2) of [[RFC3986]].
+the term generation rules of RML use simple string concatenation,
+rather than the more complex algorithm for resolution of [=relative URIs=].
 This ensures that the original [=expression evaluation result=] can be reconstructed from the generated absolute [=IRI=].
 Both algorithms are equivalent if all of the following are true:
 
@@ -40,6 +90,9 @@ Both algorithms are equivalent if all of the following are true:
 4. the relative [=IRI=] does not contain any “.” or “..” path segments.
 </aside>
 
+If no specific [=base IRI=] is provided and the [=mapping process=] needs to generate absolute [=IRIs=] from relative ones, 
+the default base IRI to be used by the [=RML Processor=] MUST be http://example.org/.
+
 ### RML Validator
 
 An <dfn>RML data validator</dfn> is a system that takes as its input