RML+FnO is an approach to provide for data transformations when generating knowledge graphs
+from (semi-)structured data using the RDF Mapping Language (RML).
+
In RML+FnO, data transformations are defined declaratively,
+supporting the Function Ontology (FnO).
+
This approach is not case-specific:
+data transformations are independent of their implementation and thus interoperable,
+while the functions are decoupled and reusable.
+This allows developers to improve the generation framework
+independent from the contributors that focus on generating the knowledge graphs.
+ GitHub Issues are preferred for
+ discussion of this specification.
+
+
+
+
+
1. Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
+ The key words MAY and MUST in this document
+ are to be interpreted as described in
+ BCP 14
+ [RFC2119] [RFC8174]
+ when, and only when, they appear in all
+ capitals, as shown here.
+
+
+
2. The Problem
+
Mapping languages allow us to define how knowledge graphs are generated from (semi-)structured data,
+but only if the original data values can be used as-is.
+Complex data transformations in mapping languages typically are
+either implemented as custom solutions,
+or are done by systems separate from the mapping process.
+The former data transformations remain case-specific, often coupled with the mapping,
+whereas the latter is not reusable across systems.
+
For example, we have a data source where all names are lowercase,
+but we want the resulting knowledge to have uppercase values.
+The following RML Mapping contains the descriptions to generate a knowledge graph from a data source,
+but no data transformations.
A Function: an implementation-independent declaration of a function,
+specified using multiple parameters and multiple returns.
+For example, a Function can be declared as follows: function int sum(int a, int b) throws StackOverFlowException, namely,
+the Functionsum has two input parameters, int a and int b, and returns an int or throws a StackOverFlowException.
An Execution: an invocation of a Function.
+Concrete values are bound to the input Parameters,
+and concrete values are bound to the Returns after execution.
+For example, sum(2, 4) = 6 is an execution,
+where 2 is bound to the aParameter, 4 is bound to the bParameter, and 6 is bound as Return value.
Within this specification, the Expression Map definition is extended by adding new possible properties and thus also a new type of Expression Map.
+The change is included below with changes highlighted in bold.
If an execution returns multiple returning outputs (eg, a result and a status code),
+by referring to the same execution,
+you can use both outputs in different locations of the same mapping.
+If you leave out the intermediate Function-valued Expression Map, you don't allow for reuse,
+which means that you cannot specify the difference between
+'using 2 outputs from one execution' vs 'use a different output from 2 different executions'.
+
+
+
4.1 Function Example
+
We use Example 1,
+where we want to perform an uppercase operation to a set of fields.
+
The FnO description of the function toUppercase is as follows:
+
+
+
The execution of such a function converts a string to its uppercase sibling,
+so test becomes TEST and This is an input STRING. becomes THIS IS AN INPUT STRING..
+The latter would be described as follows using an FnO Execution description:
+
+
+
4.2 FNML Example - shortcuts
+
To connect this function with the RML mapping document, we make use of FNML, see below for an example, which makes maximal use of shortcuts.
The name-value is not referenced directly,
+instead, its value is used as grel:valueParam-parameter
+for the grel:toUppercase-function.
+After execution, the grel:stringOut result of that function is returned to generate the object
+within the <#NameMapping>.
+We make use of an intermediate Function-valued Expression Map so that we can reuse the returning output of an execution in multiple TermMaps.
+
4.3 FNML Example - no shortcuts
+
The same example, but written without shortcuts, is as follows:
+
+
+
5. FNML
+
We use terms defined in the FNML ontology to link [RML] with [FNO].
+
The ontology namespace is http://w3id.org/rml/,
+the preferred prefix is rml:.
+See below for how FNML introduced terms align with RML Core.
+
+
+ Figure 2Visual overview of how FNML introduced terms align with RML Core
+
+
+
rml:return: this relationship MUST refer to exactly one of the Returns as specified by the Function. This signifies which result of the execution to use. The default value is the first Return value as specified by the Function.
+
+
Issue
A proper term map definition in RML is pending.
+For now, we refer to the R2RML spec, but it is assumed these references will be updated based on the evolution of RML.
+This also means that all changes to existing definitions such as term type etc. are complementary to this specification.
When you specifically want to have join conditions, you should use functions within rml:joinCondition,
+see, e.g. test case RMLFNOTC0019.
+
+
+
+
6. Advanced usage
+
6.1 Nested functions
+
As the values of a function are represented using Expression Maps,
+it is possible to nest functions: you generate a term in a first function, and that term is used as an parameter value in a second function.
Issue 3: Feature: how to nest a joincondition inside a function?
For now, it is unclear how to handle a nested function where that nested Triples Map contains a join condition.
+
+
+
+
+
6.2 Conditions
+
Conditions are a shortcut to make RML mappings more intuitive, but rely on existing FNML functionality.
+It is a shortcut that is applied using the rml:condition: an additional ExpressionMap predicate.
+To be able to use this shortcut, conforming mapping engines MUST support following functions:
+
+
isNull
+
isNotNull
+
equals
+
noEquals
+
IF
+
+
Note: Condition function definitions
+ isNotNull and IF are defined below, rest is an excercise for the reader.
+ The actual FnO definitions are TODO.
+
RML+FnO is an approach to provide for data transformations when generating knowledge graphs
+from (semi-)structured data using the RDF Mapping Language (RML).
+
In RML+FnO, data transformations are defined declaratively,
+supporting the Function Ontology (FnO).
+
This approach is not case-specific:
+data transformations are independent of their implementation and thus interoperable,
+while the functions are decoupled and reusable.
+This allows developers to improve the generation framework
+independent from the contributors that focus on generating the knowledge graphs.
+ GitHub Issues are preferred for
+ discussion of this specification.
+
+
+
+
+
1. Conformance
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
+ The key words MAY and MUST in this document
+ are to be interpreted as described in
+ BCP 14
+ [RFC2119] [RFC8174]
+ when, and only when, they appear in all
+ capitals, as shown here.
+
+
+
2. The Problem
+
Mapping languages allow us to define how knowledge graphs are generated from (semi-)structured data,
+but only if the original data values can be used as-is.
+Complex data transformations in mapping languages typically are
+either implemented as custom solutions,
+or are done by systems separate from the mapping process.
+The former data transformations remain case-specific, often coupled with the mapping,
+whereas the latter is not reusable across systems.
+
For example, we have a data source where all names are lowercase,
+but we want the resulting knowledge to have uppercase values.
+The following RML Mapping contains the descriptions to generate a knowledge graph from a data source,
+but no data transformations.
A Function: an implementation-independent declaration of a function,
+specified using multiple parameters and multiple returns.
+For example, a Function can be declared as follows: function int sum(int a, int b) throws StackOverFlowException, namely,
+the Functionsum has two input parameters, int a and int b, and returns an int or throws a StackOverFlowException.
An Execution: an invocation of a Function.
+Concrete values are bound to the input Parameters,
+and concrete values are bound to the Returns after execution.
+For example, sum(2, 4) = 6 is an execution,
+where 2 is bound to the aParameter, 4 is bound to the bParameter, and 6 is bound as Return value.
Within this specification, the Expression Map definition is extended by adding new possible properties and thus also a new type of Expression Map.
+The change is included below with changes highlighted in bold.
If an execution returns multiple returning outputs (eg, a result and a status code),
+by referring to the same execution,
+you can use both outputs in different locations of the same mapping.
+If you leave out the intermediate Function-valued Expression Map, you don't allow for reuse,
+which means that you cannot specify the difference between
+'using 2 outputs from one execution' vs 'use a different output from 2 different executions'.
+
+
+
4.1 Function Example
+
We use Example 1,
+where we want to perform an uppercase operation to a set of fields.
+
The FnO description of the function toUppercase is as follows:
+
+
+
The execution of such a function converts a string to its uppercase sibling,
+so test becomes TEST and This is an input STRING. becomes THIS IS AN INPUT STRING..
+The latter would be described as follows using an FnO Execution description:
+
+
+
4.2 FNML Example - shortcuts
+
To connect this function with the RML mapping document, we make use of FNML, see below for an example, which makes maximal use of shortcuts.
The name-value is not referenced directly,
+instead, its value is used as grel:valueParam-parameter
+for the grel:toUppercase-function.
+After execution, the grel:stringOut result of that function is returned to generate the object
+within the <#NameMapping>.
+We make use of an intermediate Function-valued Expression Map so that we can reuse the returning output of an execution in multiple TermMaps.
+
4.3 FNML Example - no shortcuts
+
The same example, but written without shortcuts, is as follows:
+
+
+
5. FNML
+
We use terms defined in the FNML ontology to link [RML] with [FNO].
+
The ontology namespace is http://w3id.org/rml/,
+the preferred prefix is rml:.
+See below for how FNML introduced terms align with RML Core.
+
+
+ Figure 2Visual overview of how FNML introduced terms align with RML Core
+
+
+
rml:return: this relationship MUST refer to exactly one of the Returns as specified by the Function. This signifies which result of the execution to use. The default value is the first Return value as specified by the Function.
+
+
Issue
A proper term map definition in RML is pending.
+For now, we refer to the R2RML spec, but it is assumed these references will be updated based on the evolution of RML.
+This also means that all changes to existing definitions such as term type etc. are complementary to this specification.
When you specifically want to have join conditions, you should use functions within rml:joinCondition,
+see, e.g. test case RMLFNOTC0019.
+
+
+
+
6. Advanced usage
+
6.1 Nested functions
+
As the values of a function are represented using Expression Maps,
+it is possible to nest functions: you generate a term in a first function, and that term is used as an parameter value in a second function.
Issue 3: Feature: how to nest a joincondition inside a function?
For now, it is unclear how to handle a nested function where that nested Triples Map contains a join condition.
+
+
+
-
+
6.2 Conditions
+
Conditions are a shortcut to make RML mappings more intuitive, but rely on existing FNML functionality.
+It is a shortcut that is applied using the rml:condition: an additional ExpressionMap predicate.
+To be able to use this shortcut, conforming mapping engines MUST support following functions:
+
+
isNull
+
isNotNull
+
equals
+
noEquals
+
IF
+
+
Note: Condition function definitions
+ isNotNull and IF are defined below, rest is an excercise for the reader.
+ The actual FnO definitions are TODO.
+
+ 
+