Abstract

This document discusses the Function Ontology, a way to semantically declare and describe function. It uses SKOS to define relations between functions, problems, and algorithms.

A list of the publications concerning the Function Ontology can be viewed at https://fno.io

There exist many specifications that define Web services, both non-semantically (e.g., WSDL and WADL) and semantically (e.g., OWL-S and Hydra) These specifications target different facets (e.g., HTTP-based vs SOAP-based access, defining RESTful APIs, etc.), but have in common that they define Web services. Thus, they clearly specify, e.g., which HTTP method to invoke with which parameter to correctly call the Web service. The big drawback of these specifications is thus that they are very coupled with the technology stack. However, not all actions can be executed using Web APIs, either because of performance or practicality reasons. For example, the nurse call system is a near real-time system, which implies that unnecessary HTTP connections should be avoided.

In this specification, we present a more general vocabulary as a data model, specification, and ontology to semantically declare and describe functions. Instead of defining technology-specifics, the functions are described independent of the technology that implements them. By semantically defining these functions using an ontology, we provide a uniform and unambiguous solution, and thus, we can close the gap between semantic data and any real-world action, and enable semantic applications to be used in real-world scenarios.

Namespace

The Function Ontology's namespace is https://w3id.org/function/ontology#

The preferred prefix is fno:

The discussed ontology's version is 0.6.0.

The used vocabularies are the FnO mapping vocabulary (fnom:) and the FnO implementation vocabulary (fnoi:).

Status of This Document

This document is merely a public working draft of a potential specification. It has no official standing of any kind and does not represent the support or consensus of any standards organisation.

This is an early draft, expect this document to change much and often.

1. The Problem

Applications built on top of Linked Data and the Semantic Web are emerging as a novel solution in many different areas, such as -- among others -- decision making and route planning. However, to connect results of these solutions (i.e., the semantic data) with real-world applications, we need a generic way to connect actionable events to semantic data.

This specification (and accompanying ontology) explains how to semantically declare and describe functions, their input parameters, and possible outputs.

2. Definitions

The following document makes a clear distinction between following concepts:

Furthermore, we define following concepts:

3. The Function Ontology

The Function Ontology distinguishes between the (abstract) function and the (concrete) implementation. The two can be used together, but are complementary.

3.1 Function (abstract)

The Function Ontology
Fig. 1 The Function Ontology

The Function Ontology follows the Content Ontology Design Pattern and consists of a couple of base classes that need to be instantiated for real world use cases. Input parameters and output values are connected to functions via executions, using a reification paradigm.

To be consistent with the paradigms used in SKOS, axioms need to be made instead of subclassing the base classes of the Function Ontology. The reification paradigm allows to define the connection between an execution and the input parameters and output values. This allows for re-use of these connection definitions, and more meaningful connections between input parameter and execution.

No cardinalities are defined in the Function Ontology, as there are no hard limits on cardinality to be defined. A function can implement multiple algorithms, solve multiple problems, and have multiple executions. All executions can have multiple input parameters and output values. Vice versa, input parameters and output values can be linked to multiple executions, and an execution (i.e., a set of input values and output values) can be linked to multiple functions.

3.1.1 fno:Function

Example 1
ex:sumFunction a fno:Function;
    fno:name "The sum function"^^xsd:string;
    dcterms:description "This function can do the sum of two integers."^^xsd:string;

3.1.2 fno:Problem

Example 2
ex:sumFunction a fno:Function;
    fno:solves ex:sumProblem.

ex:sumProblem a fno:Problem;
    fno:name "The sum problem"^^xsd:string;
    dcterms:description "This handles the problem of adding two integers to each other."^^xsd:string;
    skos:broader ex:mathProblem.
Note

skos terms can be used to relate problems with each other. This can also be done for algorithms and functions.

3.1.2.1 fno:solves

Domain fno:Function

Range fno:Problem

3.1.3 fno:Algorithm

Example 3
ex:sumFunction a fno:Function;
    fno:implements ex:sumAlgorithm.

ex:sumAlgorithm a fno:Algorithm;
    fno:name "The sum algorithm"^^xsd:string;
    dcterms:description "About how to add two integers to each other."^^xsd:string;
3.1.3.1 fno:implements

Domain fno:Function

Range fno:Algorithm

3.1.4 fno:Parameter

Example 4
ex:sumFunction a fno:Function;
    fno:expects ( ex:intParameterA ex:intParameterB ).
    
ex:intParameterA a fno:Parameter;
    fno:predicate ex:startValue;
    fno:required "true"^^xsd:boolean.
    
ex:startValue fno:type xsd:integer.
    
ex:intParameterB a fno:Parameter;
    fno:predicate ex:sumValue;
    fno:required "true"^^xsd:boolean.  
    
ex:sumValue fno:type xsd:integer.

This description actually defines which predicates to use when binding the values to the execution of the function (using the fno:predicate predicate). All predicates are allowed, except for rdf:type and fno:executes.

In the example ex:intParameterA and ex:intParameterB can be reused across function descriptions. As they only describe the parameters, and not the actual values, they can be reused. For example, the function function match(str, regex) and function split(str, regex) could reuse the same parameter instantiatons.

The fno:expects has as range an rdf:List. This could be used to hint applications how many parameters are used, and in what order, however, this is not enforced. This to accommodate technologies where the order of parameters is not of importance.

Note

The range of the predicates used by the parameters don't have to be defined. However, by do defining them, we achieve type hinting.

3.1.4.1 fno:expects

Domain fno:Function

Range rdf:List of fno:Parameter

3.1.4.2 fno:predicate

Domain fno:Function

Range rdf:Property

3.1.5 fno:Execution

Example 5
ex:sumExecution a fno:Execution;
    fno:executes ex:sumFunction;
    ex:startValue "2"^^xsd:integer;
    ex:sumValue "4"^^xsd:integer.

As can be seen here, are the predicates used as described as parameters of the function. rdf:type and fno:executes cannot be used as parameter predicates, as this would conflict with the description of the execution.

3.1.5.1 fno:executes

Domain fno:Execution

Range fno:Function

3.1.6 fno:Output

Example 6
ex:sumFunction a fno:Function;
    fno:returns ( ex:sumOutput ).
    
ex:sumOutput a fno:Output;
    fno:predicate ex:sumResult;
    fno:required "true"^^xsd:boolean.
    
ex:sumResult fno:type xsd:integer.

Similar as with fno:Parameter, the connecting predicate is described for fno:Output. After the execution of the function with the correct parameter values, we could return the following turtle:

Example 7
ex:sumExecution a fno:Execution;
    ex:sumResult "6"^^xsd:integer.

Similarly as with the parameter descriptions, the output descriptions can be reused across functions.

3.1.6.1 fno:returns

Domain fno:Execution

Range fno:Output

3.1.7 Complete example

Declaration and description of the function and one execution:

Example 8
ex:sumFunction a fno:Function;
    fno:name "The sum function"^^xsd:string;
    dcterms:description "This function can do the sum of two integers."^^xsd:string;
    fno:solves ex:sumProblem;
    fno:implements ex:sumAlgorithm;
    fno:expects ( ex:intParameterA ex:intParameterB );
    fno:returns ( ex:sumOutput ).
    
ex:intParameterA a fno:Parameter;
    fno:predicate ex:startValue;
    fno:required "true"^^xsd:boolean.
    
ex:startValue fno:type xsd:integer.
    
ex:intParameterB a fno:Parameter;
    fno:predicate ex:sumValue;
    fno:required "true"^^xsd:boolean.  
    
ex:sumValue fno:type xsd:integer.

ex:sumOutput a fno:Output;
    fno:predicate ex:sumResult;
    fno:required "true"^^xsd:boolean.
    
ex:sumResult fno:type xsd:integer.

ex:sumProblem a fno:Problem;
    fno:name "The sum problem"^^xsd:string;
    dcterms:description "This handles the problem of adding two integers to each other."^^xsd:string;
    skos:broader ex:mathProblem;

ex:sumAlgorithm a fno:Algorithm;
    fno:name "The sum algorithm"^^xsd:string;
    dcterms:description "About how to add two integers to each other."^^xsd:string;
    
ex:sumExecution a fno:Execution;
    fno:executes ex:sumFunction;
    ex:startValue "2"^^xsd:integer;
    ex:sumValue "4"^^xsd:integer.

Resulting output triples:

Example 9
ex:sumExecution a fno:Execution;
    ex:sumResult "6"^^xsd:integer.

3.2 Implementation (concrete)

The Function Ontology
Fig. 2 The Function Ontology, linked to implementations

3.2.1 fno:Implementation

Example 10
ex:leftPadImplementation a fnoi:NpmPackage ;
    doap:name "left-pad" .
3.2.1.1 Example: Hydra

Link with the Hydra specification

The Hydra specification defines Web services semantically. A hydra:ApiDocumentation can thus be seen as a fno:Implementation.

3.2.2 fno:Mapping

A fno:Mapping maps a fno:Function to a (part) of an fno:Implementation. For example: a left-pad function is mapped to a specific method in an NPM package. This requires the combination of 3 types of mappings: the mapping of the method name (so that, e.g., a ex:leftPad function is mapped to method doLeftPadding()), the mapping of the parameters (so that, e.g., the argument with predicate ex:inputString of the function is mapped to the second parameter of the doLeftPadding() method), and the mapping of the outputs (so that, e.g., both the return value and the thrown exception of the method are mapping to the outputs of the function). To link to the function and implementation, predicates fno:function and fno:implementation are used, respectively.

Note that the actual implementations and mappings are not part of the Function Ontology. Specific development contexts can be further catered to.

Example 11
ex:leftPadMapping a fno:Mapping ;
    fno:function ex:leftPad ;
    fno:implementation ex:leftPadImplementation .
3.2.2.1 fno:MethodMapping

Maps the method name. For source code, this can be done using a fnom:StringMethodMapping. The method name is an attribute of a fnom:StringMethodMapping, linked using the fnom:method-name predicate.

Example 12
ex:leftPadMapping a fno:Mapping ;
    fno:methodMapping [
        a fnom:StringMethodMapping ;
        fnom:method-name "doLeftPadding"
    ] .
3.2.2.2 fno:ParameterMapping

Maps the different parameters. For source code, this is typically specified by the position, using fnom:PositionParameterMapping: each fno:ParameterMapping gets linked to a parameter using the fnom:functionParameter predicate, and to a position using the fnom:implementationParameterPosition predicate.

Example 13
ex:leftPadMapping a fno:Mapping ;
    fno:parameterMapping [
        a fnom:PositionParameterMapping ;
        fnom:functionParameter ex:inputStringParameter ;
        fnom:implementationParameterPosition "2"^^xsd:int
    ] .

For a Web service, this is typically specified by a name, e.g., a POST using property "password" in the form body. A fnom:PropertyParameterMapping is used. Each fno:ParameterMapping gets linked to a parameter using the fnom:functionParameter predicate, and to a property using the fnom:implementationProperty predicate.

3.2.2.3 fno:ReturnMapping

Maps the different outputs. For source code, this is typically specified by the return value, and (optionally) thrown exceptions, using fnom:DefaultReturnMapping and fnom:ExceptionReturnMapping, respectively: each fno:ReturnMapping gets linked to an output using the fnom:functionOutput predicate.

Example 14
ex:leftPadMapping a fno:Mapping ;
    fno:returnMapping [
        a fnom:DefaultReturnMapping ;
        fnom:functionOutput ex:outputStringOutput
    ] .

3.2.3 Full example

Example 15
ex:leftPad a fno:Function ;
    fno:expects ( ex:inputStringParameter ex:paddingParameter ) ;
    fno:returns ( ex:outputStringOutput ) .

ex:inputStringParameter a fno:Parameter ;
    fno:predicate ex:inputString ;
    fno:type xsd:string ;
    fno:required "true"^^xsd:boolean .

ex:paddingParameter a fno:Parameter ;
    fno:predicate ex:padding ;
    fno:type xsd:int ;
    fno:required "false"^^xsd:boolean .

ex:leftPadImplementation a fnoi:NpmPackage ;
    doap:name "left-pad" .

ex:leftPadMapping a fno:Mapping ;
    fno:function ex:leftPad ;
    fno:implementation ex:leftPadImplementation ;
    fno:methodMapping [
        a fnom:StringMethodMapping ;
        fnom:method-name "doLeftPadding"
    ] ;
    fno:parameterMapping [
        a fnom:PositionParameterMapping ;
        fnom:functionParameter ex:inputStringParameter ;
        fnom:implementationParameterPosition "2"^^xsd:int
    ] ;
    fno:parameterMapping [
        a fnom:PositionParameterMapping ;
        fnom:functionParameter ex:paddingParameter ;
        fnom:implementationParameterPosition "1"^^xsd:int
    ] ;
    fno:returnMapping [
        a fnom:DefaultReturnMapping ;
        fnom:functionOutput ex:outputStringOutput
    ] .

4. Examples

The following sections are a set of FAQs and How-to's regarding the Function Ontology.

4.1 Array of parameters

The model allows for arrays of parameters. For example, the following function function findInString(str, [searchValues...]) could be described as follows:

Example 16
ex:findInString a fno:Function;
    fno:name "Finding multiple values in a string function"^^xsd:string;
    dcterms:description "This function returns true if any of the input values is found in the string."^^xsd:string;
    fno:expects (
        [
            fno:predicate ex:body;
            fno:required "true"^^xsd:boolean
        ]
        [
            fno:predicate ex:searchValues;
            fno:required "true"^^xsd:boolean
        ]
        [
            fno:predicate ex:found;
            fno:required "true"^^xsd:boolean
        ]
    ).

ex:findExecution a fno:Execution;
    fno:executes ex:findInString;
    ex:body "Try and find some values in this string."^^xsd:string;
    ex:searchValues ("Paris" "Brussels" "Tokyo" "Los Angeles") .

4.2 Required output

Output can be assigned required or not. For example, thrown errors are an example of optional output.

4.3 Reification explained

TODO

4.4 Reference model

TODO

4.5 System architecture example

TODO