overview section, examples and joins

spec/docs/graphmap.md

@@ -2,7 +2,7 @@
 
 Each triple generated from an [=RML mapping=] is placed into one or more graphs of the [=output dataset=]. Possible target graphs are the unnamed [=default graph=], the [=IRI=]-named [=named graphs=], and [=blank node=] named [=named graphs=]
 
-Any [=subject map=] or [=predicate-object=] map MUST have zero or more associated <dfn>graph maps</dfn>. They are specified in one of two ways:
+Any [=subject map=] or [=predicate-object map=] MUST have zero or more associated <dfn>graph maps</dfn>. They are specified in one of two ways:
 
 1. using the `rml:graphMap` property, whose value MUST be a [=graph map=],
 2. using the [=constant shortcut property=] `rml:graph`.
@@ -11,49 +11,71 @@ Any [=subject map=] or [=predicate-object=] map MUST have zero or more associate
 
 If a [=graph map=] generates the special IRI `rml:defaultGraph`, then the target graph is the [=default graph=] of the [=output dataset=].
 
-<aside class="example"  id="example-graph-map" title="Usage of graph map">
+<aside class="example"  id="example-graph-map" title="Usage of graph maps">
+
+In the following [=subject map=] example, all generated [=RDF triples=] will be stored in the [=named graph=] `ex:AlbumGraph`.
 
-In the following [=subject map=] example, all generated [=RDF triples=] will be stored in the [=named graph=] `ex:DepartmentGraph`.
 <aside class="ex-mapping">
+
 ```turtle
-[]  rml:subjectMap [
-      rml:template "http://data.example.com/department/{DEPTNO}";
-      rml:graphMap [ rml:constant ex:DepartmentGraph ];
-].
+<#ImageTriplesMap>
+  rml:subjectMap [
+    rml:template "http://data.example.com/image/{$.ID}" ;
+    rml:graphMap [ rml:constant ex:AlbumGraph ] ;
+  ] .
 ```
+
 </aside>
+
 This is equivalent to the following example, which uses a [=constant shortcut property=]:
+
 <aside class="ex-mapping">
+
 ```turtle
-[]  rml:subjectMap [
-      rml:template "http://data.example.com/department/{DEPTNO}";
-      rml:graph ex:DepartmentGraph;
-].
+<#ImageTriplesMap>
+  rml:subjectMap [
+    rml:template "http://data.example.com/image/{$.ID}" ;
+    rml:graph ex:AlbumGraph ;
+  ] .
 ```
+
 </aside>
-In the following example, [=RDF triples=] are placed into [=IRI=]-named [=named graphs=] according to the job title of employees:
+
+In the following example, [=RDF triples=] are placed into a [=IRI=]-named [=named graphs=] according to `ID` of the images:
+
 <aside class="ex-mapping">
+
 ```turtle
-[]  rml:subjectMap [
-      rml:template "http://data.example.com/employee/{EMPNO}";
-      rml:graphMap [ rml:template "http://data.example.com/jobgraph/{JOB}" ];
-].
+<#ImageTriplesMap>
+  rml:subjectMap [
+    rml:template "http://data.example.com/image/{$.ID}" ;
+    rml:graphMap [
+      rml:template "http://data.example.com/graph/{$.ID}" ;
+    ] ;
+  ] .
 ```
+
 </aside>
-However, in this example, RDF triples of the [=predicate-object=] `ex:name` are placed into a [=blank node=] named [=named graphs=] according to the job title of employees:
+
+However, in this example, RDF triples of the [=predicate=] `ex:title` are placed into [=blank node=] [=named graphs=] according to `ID` of the images:
+
 <aside class="ex-mapping">
+
 ```turtle
-[]  rml:subjectMap [
-      rml:template "http://data.example.com/employee/{EMPNO}";
-    ];
-    rml:predicateObjectMap [
-      rml:predicate ex:name;
-      rml:objectMap [ rml:reference "name"; ];
-      rml:graphMap [
-        rml:reference "JOB"
-        rml:termType rr:IRI
-      ];
-    ].
+<#ImageTriplesMap>
+  rml:subjectMap [
+    rml:template "http://data.example.com/image/{$.ID}" ;
+  ] ;
+  rml:predicateObjectMap [
+    rml:predicate ex:title ;
+    rml:objectMap [
+      rml:reference "$.Title.Value" ;
+    ] ;
+    rml:graphMap [
+      rml:reference "$.ID" ;
+      rml:termType rml:BlankNode ;
+    ] ;
+  ] .
 ```
 </aside>
 

spec/docs/index.html

@@ -90,7 +90,7 @@
 
 <!--<section id="introduction" data-include="introduction.md" data-include-format="markdown"></section>-->
 
-<!--<section id="overview" data-include="overview.md" data-include-format="markdown"></section>-->
+<section id="overview" class="informative" data-include="overview.md" data-include-format="markdown"></section>
 
 <section id="vocabulary" data-include="vocabulary.md" data-include-format="markdown"></section>
 

spec/docs/joinconditions.md

@@ -1,76 +1,109 @@
 # Joins
 
-A [=Referencing Object Map=] allows using the subject generated by the [=Subject Map=] (`rml:SubjectMap`) of the referenced [=Triples Map=] (`rml:TriplesMap`).
-Since the two [=triples maps=] may be based on different [=logical sources=] (`rml:LogicalSource`), this may require a [=join=] (`rml:Join`) between the [=logical sources=]. This is not restricted to 1:1 joins.
+A [=referencing object map=] allows using the subject generated by the [=subject map=] (`rml:SubjectMap`) of the referenced [=triples map=] (`rml:TriplesMap`).
+Since the two [=triples maps=] may be based on different [=logical sources=] (`rml:LogicalSource`), this may require a [=join=] between the [=logical sources=]. This is not restricted to 1:1 joins.
 
 ## Referencing Object Map
 
-A <dfn>Referencing Object Map</dfn> (`rml:ReferencingObjectMap`) is represented by a resource that:
+A <dfn>referencing object map</dfn> (`rml:ReferencingObjectMap`) is represented by a resource that MUST have:
 
-* has exactly one [=parent triples map=] (`rml:parentTriplesMap`) property,
+* exactly one [=parent triples map=] (`rml:parentTriplesMap`) property,
   whose value MUST be a [=triples map=], known as the referencing object map's <dfn>parent triples map</dfn>.
-* MUST have one or more [=join Conditions=] (`rml:joinCondition`) properties.
+* one or more join condition (`rml:joinCondition`) properties, whose values MUST be [=join conditions=].
 
-The [=referencing object map=] caused the generation of new [=object=] which is constructed with the [=subject=] generated by evaluating the [=parent triples map=].
+The [=referencing object map=] causes the generation of new [=object=] which is constructed with the [=subject=] generated by evaluating the [=parent triples map=].
 
-<aside class="example" id="example-referencing-object-map" title="usage of referencing object map">
+<aside class="example" id="example-referencing-object-map" title="Usage of referencing object map">
+
+This example shows a [=referencing object map=] as part of a [=predicate-object map=] in a [=triples map=] mapping the `ex:hasThumbnail` [=property=] of and `ex:Image` class.
+Since the source data for the thumbnail is part of the same [=logical iteration=] as for the image, the [=logical source=] is [=effectively equal=] to the [=logical source=] of the [=parent triples map=], and no [=join condition=] is needed.
 
 <aside class="ex-mapping">
 
 ```turtle
-<#TM1>
-  rml:logicalSource <#LS1> ;
-  rml:subjectMap <#SM1> ;
+<#ImageTriplesMap>
   rml:predicateObjectMap [
-    rml:predicateMap <#PM1> ;
+    rml:predicate ex:hasThumbnail ;
     rml:objectMap [
-      rml:parentTriplesMap <#TM2> ;
+      rml:parentTriplesMap <#ThumbnailTriplesMap> ;
     ] ;
   ] .
 
-<#TM2>
-  rml:logicalSource <#LS2> ;
-  rml:subjectMap <#SM2> ;
-  rml:predicateObjectMap [
-    rml:predicateMap <#PM2> ;
-    rml:objectMap <#OM2> ;
+<#ThumbnailTriplesMap>
+  rml:subjectMap [
+    rml:reference "$.Thumbnail.Url" ;
+    rml:termType rr:IRI ;
   ] .
 ```
 
 </aside>
 
+The following RDF triples are generated by the [=RML mapping=] above.
+
+<aside class="ex-output">
+
+```turtle
+<http://data.example.com/image/116> ex:hasThumbnail <http://data.example.com/image/116/thumbnail> .
+```
+
+</aside>
+
 </aside>
 
 ## Join Condition
 
-A <dfn>Join Condition</dfn> is represented by a resource that has exactly one value for each of the following two properties:
+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 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=].
+
+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=].
 
-* a child map (`rml:childMap`) property, whose value is a [=child map=]. A <dfn>child map</dfn> (`rml:ChildMap`) is an [=expression map=], which MUST include [=references=] that exist in the [=logical source=] of the [=parent triples map=] that contains the [=referencing object map=], or it should have a [=constant value=].
+A [=join condition=] is satisfied if the result of evaluating the [=child map=] against the [=logical source=] of the current [=triples map=] is equal to the result of evaluating the [=parent map=] against the [=logical source=] of the referenced [=triples map=].
 
-* a parent map (`rml:parentMap`) property, whose value is a [=parent map=]. A <dfn>parent map</dfn> (`rml:ParentMap`) is an [=expression map=], which MUST include references that exist in the [=logical source=] of the [=referencing object map=]'s [=parent triples map=], or it should have a [=constant value=].
+If a [=referencing object map=] has multiple [=join conditions=], then all of them MUST be satisfied for the referencing object map to be evaluated.
 
-<aside class="example" id="example-join-condition" title="usage of join condition">
+A [=mapping component=] is <dfn>effectively equal</dfn> to another [=mapping component=] if they are identical, or if all their corresponding [=effective properties=] have the same values, recursively comparing values that are [=resources=] that have [=properties=] as well.
+
+An <dfn>effective property</dfn> of a [=mapping component=] is a [=property=] that has an effect on the [=mapping process=].
+
+<aside class="note">
+The effective properties of a mapping component are the properties that are used in the mapping process, and are defined by this specification or other specifications that extend this specification.
+</aside>
+
+<aside class="example" id="example-join-condition" title="Usage of join condition">
+
+This example shows a [=referencing object map=] as part of a [=predicate-object map=], where the [=logical sources=] of the two [=triples maps=] are [=effectively equal=]. Therefore, a [=join condition=] is needed to join the two [=logical iterations=].
 
 <aside class="ex-mapping">
 
 ```turtle
-<#TM1>
-  rml:logicalSource <#LS1> ;
-  rml:subjectMap <#SM1> ;
+<#AlbumTriplesMap>
   rml:predicateObjectMap [
-    rml:predicateMap <#PM1> ;
+    rml:predicate ex:hasImage ;
     rml:objectMap [
-      rml:parentTriplesMap <#TM2> ;
+      rml:parentTriplesMap <#ImageTriplesMap> ;
       rml:joinCondition [
-        rml:childMap [ rml:reference "..."] ;
-        rml:parentMap [ rml:template "..."] ;
+        rml:childMap [
+          rml:reference "$.Images[*].ID" ;
+        ] ;
+        rml:parentMap [
+          rml:reference "$.ID" ;
+        ] ;
       ] ;
     ] ;
   ] .
+```
 
-<#TM2>
-  rml:logicalSource <#LS2> ;
-  rml:subjectMap <#SM2> .
+</aside>
+
+The following RDF triples are generated by the [=RML mapping=] above, since the first `ID` field in the `Images` array of the `album.json` input source is joined with the `ID` field in the `images.json` input source.
+
+<aside class="ex-output">
+
+```turtle
+<http://data.example.com/album/43> ex:hasImage <http://data.example.com/image/116> .
 ```
 
 </aside>
@@ -91,28 +124,22 @@ Occurrences of these properties MUST be treated exactly as if the following trip
 | `?x rml:parent ?y.`                          | `?x rml:parentMap [ rml:reference ?y ].` |
 
 
-<aside class="example" id="example-join-condition-shortcut-properties" title="usage of shortcut properties for child map and parent map">
+<aside class="example" id="example-join-condition-shortcut-properties" title="Usage of shortcut properties for child map and parent map">
 
 <aside class="ex-mapping">
 
 ```turtle
-<#TM1>
-  rml:logicalSource <#LS1> ;
-  rml:subjectMap <#SM1> ;
+<#AlbumTriplesMap>
   rml:predicateObjectMap [
-    rml:predicateMap <#PM1> ;
+    rml:predicate ex:hasImage ;
     rml:objectMap [
-      rml:parentTriplesMap <#TM2> ;
+      rml:parentTriplesMap <#ImageTriplesMap> ;
       rml:joinCondition [
-        rml:child "..." ;
-        rml:parent "..." ;
+        rml:child "$.Images[*].ID" ;
+        rml:parent "$.ID" ;
       ] ;
     ] ;
   ] .
-
-<#TM2>
-  rml:logicalSource <#LS2> ;
-  rml:subjectMap <#SM2> .
 ```
 
 </aside>

spec/docs/mapping.md

@@ -18,15 +18,38 @@ They specify pairs of [=predicate maps=] and [=object maps=] that, together with
 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>
 
-<aside class="example" id="example-triples-map" title="usage of triples map">
+<aside class="example" id="example-triples-map" title="Usage of triples map">
+
+The following example shows a [=triples map=] including its [=logical source=], [=subject map=] and two [=predicate-object maps=].
 
 <aside class="ex-mapping">
 
 ```turtle
 <#TM>
-  rml:logicalSource <#LS> ;
-  rml:subjectMap <#SM> ;
-  rml:predicateObjectMap <#POM1>, <#POM2>, ..., <#POMn> .
+  rml:logicalSource [
+    rml:source [
+      a rml:RelativePathSource ;
+      rml:root rml:MappingDirectory ;
+      rml:path "images.json" ;
+    ] ;
+    rml:iterator "$.Images[*]" ;
+    rml:referenceFormulation rml:JSONPath ;
+  ] ;
+  rml:subjectMap [
+    rml:template "http://data.example.com/image/{$.ID}" ;
+  ] ;
+  rml:predicateObjectMap [
+    rml:predicate ex:height ;
+    rml:objectMap [
+      rml:reference "$.Height" ;
+    ] ;
+  ] ;
+  rml:predicateObjectMap [
+    rml:predicate ex:width ;
+    rml:objectMap [
+      rml:reference "$.Width" ;
+    ] ;
+  ] .
 ```
 
 </aside>