From ac44c1e6864043d77e1754abe4c306d82312a1c6 Mon Sep 17 00:00:00 2001
From: elsdvlee <93709574+elsdvlee@users.noreply.github.com>
Date: Tue, 3 Dec 2024 07:16:54 +0100
Subject: [PATCH] introduction of logical iterable (#40)

## What's changed
<!-- Give a concise description of the change -->
Introduction of the logical iterable and logical source as defined in
RML-Core
## Change checklist
- [x] updated ontology, where necessary
- [x] updated shapes, where necessary
- [x] added or updated test cases, where necessary
- [x] any TODOs have been turned into trackable issues and referenced
where necessary

## Issue reference
<!-- For example: -->
<!-- Fixes #{ISSUE}. -->
<!-- Resolves #{ISSUE}. -->
Resolves #34
---
 ontology/documentation/ontology.ttl |  2 +-
 spec/section/fields.md              | 17 ++++++++---------
 spec/section/records.md             |  2 +-
 spec/section/views.md               | 16 ++++++++--------
 4 files changed, 18 insertions(+), 19 deletions(-)

diff --git a/ontology/documentation/ontology.ttl b/ontology/documentation/ontology.ttl
index be08dfb..3c789b2 100644
--- a/ontology/documentation/ontology.ttl
+++ b/ontology/documentation/ontology.ttl
@@ -104,7 +104,7 @@ rml:fieldName rdf:type owl:DatatypeProperty ;
 
 ###  http://w3id.org/rml/Field
 rml:Field rdf:type owl:Class ;
-          rdfs:subClassOf rml:ExpressionMap, rml:LogicallyIterable ;
+          rdfs:subClassOf rml:ExpressionMap, rml:LogicalIterable ;
           rdfs:isDefinedBy <http://w3id.org/rml/lv/> .
 
 
diff --git a/spec/section/fields.md b/spec/section/fields.md
index 17f3c0f..aec99d7 100644
--- a/spec/section/fields.md
+++ b/spec/section/fields.md
@@ -2,16 +2,15 @@
 
 A <dfn>field</dfn> is a type of <a data-cite="RML-Core#dfn-expression-map">expression map</a>, that gives a name to an <a data-cite="RML-Core#dfn-expressions">expression</a>. Consequently, a [=field=] MUST have an <a data-cite="RML-Core#dfn-expressions">expression</a>.
 
-A [=field=] is also a type of <!-- TODO reference to core logically iterable when available-->[logically iterable](). Consequently, a [=field=] MUST have a <!-- TODO reference to core reference formulation when available-->[reference formulation]() and an <!-- TODO reference to core iterator when available-->[iterator](). 
+A [=field=] is also a type of <a data-cite="RML-Core#dfn-logical-iterable">logical iterable</a>. Consequently, a [=field=] MUST have exactly one <a data-cite="RML-Core##dfn-reference-formulation">reference formulation</a> and exactly one <a data-cite="RML-Core#dfn-iterator">logical iterator</a>. 
 
 A [=field=] (`rml:Field`) MUST have the following additional properties:
 - exactly one field name property (`rml:fieldName`), that specifies the [=name=] of the field
 - zero or more field properties (`rml:field`), to describe nested [=field=], also of the type `rml:Field`
 
-
-| Property                     | Domain                         | Range                      |
-|------------------------------|--------------------------------|----------------------------|
-| `rml:fieldName`              | `rml:Field`                    | `rml:LogicalSource`        |
+| Property                     | Domain                           | Range                      |
+|------------------------------|----------------------------------|----------------------------|
+| `rml:fieldName`              | `rml:Field`                      | `rml:LogicalSource`        |
 | `rml:field`                  | `rml:LogicalView` or `rml:Field` | `rml:Field`                |
 
 ### Field parents {#fieldparents}
@@ -23,7 +22,7 @@ A [=field=] MUST have a <dfn>declared name</dfn> that is an alphanumerical strin
 
 <aside class=example id=ex-field>
 
-In this example a [=field=] with [=declared name=] "name" is declared on the <!-- TODO reference to core, dependent on https://github.com/kg-construct/rml-core/issues/127-->[logical source]() from [[[#ex-record-sequence]]] and added to the [=logical view=]. The parent of the field with [=declared name=] "name" is the <!-- TODO reference to core, dependent on https://github.com/kg-construct/rml-core/issues/127-->[logical source]() `:jsonSource`.
+In this example a [=field=] with [=declared name=] "name" is declared on the <a data-cite="RML-Core##dfn-logical-source">logical source</a> from [[[#ex-record-sequence]]] and added to the [=logical view=]. The parent of the field with [=declared name=] "name" is the <a data-cite="RML-Core##dfn-logical-source">logical source</a> `:jsonSource`.
 
 <aside class=ex-mapping>
 
@@ -240,7 +239,7 @@ Note some columns in the table below have been shortened for brevity.
 
 ### Field reference formulations and iterators {#fieldreferenceformulations}
 
-A [=field=] MUST have a <!-- TODO reference to core reference formulation when available-->[reference formulation]() and an <!-- TODO reference to core iterator when available-->[iterator]() . 
+A [=field=] MUST have a <a data-cite="RML-Core#dfn-reference-formulation">reference formulation</a> and a <a data-cite="RML-Core#dfn-iterator">logical iterator</a> . 
 If no reference formulation is declared for a field, the reference formulation of the [=field parent=] is implied.
 If no iterator is declared for a field, the default iterator of the field's reference formulation is implied.
 
@@ -248,8 +247,8 @@ For the application of the <a data-cite="RML-Core#dfn-expressions">expression</a
 
 <aside class=example id=ex-mixed-format-json-csv>
 
-In this example a [=logical view=] is defined on a <!-- TODO reference to core, dependent on https://github.com/kg-construct/rml-core/issues/127-->[logical source]() with reference formulation `rml:JSONPath`.
-The [=field=] with [=declared name=] "item" has a declared <!-- TODO reference to core reference formulation when available-->[reference formulation]() `rml:CSV` and CSV row as implicit iterator. 
+In this example a [=logical view=] is defined on a <a data-cite="RML-Core#dfn-logical-source">logical source</a> with reference formulation `rml:JSONPath`.
+The [=field=] with [=declared name=] "item" has a declared <a data-cite="RML-Core#dfn-reference-formulation">reference formulation</a> `rml:CSV` and CSV row as implicit iterator. 
 First the expression "$.items" is evaluated using the reference formulation of the [=field parent=]. Second, the implicit iterator of the field is applied on the resulting records.
 The nested fields with [=declared name=] "type" and "weight" are evaluated using the reference formulation `rml:CSV` from their parent field  with [=declared name=] "item".
 
diff --git a/spec/section/records.md b/spec/section/records.md
index 8f3cfb5..243b751 100644
--- a/spec/section/records.md
+++ b/spec/section/records.md
@@ -79,7 +79,7 @@ tobias,2005
 
 </aside>
 
-In this example, the XPath expression `/People/Person` is used as <!-- TODO core or io, dependent on https://github.com/kg-construct/rml-lv/issues/7 and https://github.com/kg-construct/rml-lv/issues/14-->[iterator](http://w3id.org/rml/core/spec#dfn-iterator). The sequence of [=records=] it defines are the `Person` nodes on the first level in the document that have string representations
+In this example, the XPath expression `/People/Person` is used as <a data-cite="RML-Core#dfn-iterator>logical iterator</a>. The sequence of [=records=] it defines are the `Person` nodes on the first level in the document that have string representations
 
 ```xml
 <Person name="cindy">
diff --git a/spec/section/views.md b/spec/section/views.md
index d96cb22..b6d8a50 100644
--- a/spec/section/views.md
+++ b/spec/section/views.md
@@ -1,17 +1,17 @@
 ## Logical views {#logicalviews}
 
-A <dfn>logical view</dfn> (`rml:LogicalView`) is a type of <!-- TODO link to logical source definition in IO? raise issue -->logical source that is derived from another <!-- TODO core or io, dependent on https://github.com/kg-construct/rml-lv/issues/7 and https://github.com/kg-construct/rml-lv/issues/14-->logical source by defining [=fields=] with data from said <!-- TODO io -->logical source.
+A <dfn>logical view</dfn> (`rml:LogicalView`) is a type of <a data-cite="RML-Core##dfn-logical-source">logical source</a> that is derived from another <a data-cite="RML-Core##dfn-logical-source">logical source</a> by defining [=fields=] with data from said <a data-cite="RML-Core##dfn-logical-source">logical source</a>.
 
 A [=logical view=] (`rml:LogicalView`) is represented by a resource that MUST contain:
-- exactly one view on property (`rml:viewOn`), whose value is a <!-- TODO reference to core, dependent on https://github.com/kg-construct/rml-core/issues/127-->[logical source](https://kg-construct.github.io/rml-io/spec/docs/#source-vocabulary) (`rml:LogicalSource`),
+- exactly one view on property (`rml:viewOn`), whose value is a <a data-cite="RML-Core##dfn-logical-source">logical source</a> (`rml:LogicalSource`),
 - at least one field property (`rml:field`), whose value is a [=field=] (`rml:Field`).
 - zero or more join properties (`rml:leftJoin`, `rml:innerJoin`), whose value is a [=logical view join=](`rml:LogicalViewJoin`).
 
-A [=logical view=] (`rml:LogicalView`) has an implicit default <!-- TODO reference to core, dependent on https://github.com/kg-construct/rml-core/issues/127-->reference formulation (`rml:referenceFormulation`) and logical iterator (`rml:iterator`), which MUST not be overwritten. 
+A [=logical view=] (`rml:LogicalView`) has an implicit default <a data-cite="RML-Core##dfn-reference-formulation">reference formulation</a>(`rml:referenceFormulation`) and <a data-cite="RML-Core##dfn-iterator">logical iterator</a>  (`rml:iterator`), which MUST not be overwritten. 
 
-| Property        | Domain                         | Range                 |
-|-----------------|--------------------------------|-----------------------|
-| `rml:viewOn`    | `rml:LogicalView`              | `rml:LogicalSource`   |
+| Property        | Domain                           | Range                 |
+|-----------------|----------------------------------|-----------------------|
+| `rml:viewOn`    | `rml:LogicalView`                | `rml:LogicalSource`   |
 | `rml:field`     | `rml:LogicalView` or `rml:Field` | `rml:Field`           |
-| `rml:leftJoin`  | `rml:LogicalView`              | `rml:LogicalViewJoin` |
-| `rml:innerJoin` | `rml:LogicalView`              | `rml:LogicalViewJoin` |
+| `rml:leftJoin`  | `rml:LogicalView`                | `rml:LogicalViewJoin` |
+| `rml:innerJoin` | `rml:LogicalView`                | `rml:LogicalViewJoin` |