diff --git a/spec/docs/logicalSource.md b/spec/docs/logicalSource.md index 3e387a6..627db67 100644 --- a/spec/docs/logicalSource.md +++ b/spec/docs/logicalSource.md @@ -11,5 +11,63 @@ A logical iteration is an item in the sequence pr A data source 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. + +## Reference Formulations + +RML-Core covers `rml:CSV` and `rml:JSONPath` as the minimum reference formulations to be supported by any implementation for referencing data in CSV and JSON documents. + +Each Logical Source has a reference formulation to define how to reference +to elements of the data of the input source. +Several reference formulations (`rml:ReferenceFormulation`) +are defined in this specification: + +- `rml:CSV`: CSV documents +- `rml:JSONPath`: JSON documents + +See [[RML-IO-Registry]] for a detailed specification of these reference formulations. + +## Access descriptions + +RML-Core requires the `rml:PathFile` access description to be supported by any implementation to access files with an absolute or relative path. +This access description allows accessing files with relative and absolute paths from: + +- `rml:CurrentWorkingDirectory`: relative to the current working directory of the RML processor. +- `rml:MappingDirectory`: relative to the location of the RML mapping. +- A string Literal: a string describing an absolute path against which relative paths are resolved, similar to the Base URI in [RFC3986](https://www.rfc-editor.org/rfc/rfc3986). + +If `rml:root` is not specified, it defaults to `rml:CurrentWorkingDirectory`. + +| Property | Domain | Range | +| ----------- | ------------------------- | ------------------------------------------------------------------ | +| `rml:root` | `rml:FilePath` | `rml:CurrentWorkingDirectory`, `rml:MappingDirectory` or `Literal` | +| `rml:path` | `rml:FilePath` | `Literal` | + +Example of accessing a CSV file relative to the current working directory. +The file's absolute path is `$CURRENT_WORKING_DIR/file.csv` where `$CURRENT_WORKING_DIR` is +the location of the RML mapping. + +
+<#RelativePathCWD> a rml:LogicalSource;
+  rml:source [ a rml:FilePath;
+    rml:root rml:CurrentWorkingDirectory;
+    rml:path "./file.csv";
+  ];
+.
+
+ +Example of accessing a JSON file relative to the path of the mapping. +The file's absolute path is `$MAPPING_DIR/file.json` where `$MAPPING_DIR` is +the location of the RML mapping. + +
+<#RelativePathMapping> a rml:LogicalSource;
+  rml:source [ a rml:FilePath;
+    rml:root rml:MappingDirectory;
+    rml:path "./file.json";
+  ];
+  rml:referenceFormulation rml:JSONPath;
+  rml:iterator "$";
+.
+