Describing Federations

This page explains how to describe data sources (federation members) and their access interfaces using the HeFQUIN Federation Description Vocabulary. These descriptions are used by the HeFQUIN query engine to understand how to access and integrate the data sources that should be made available to a given engine instance.

1. Basic Concepts

• fd:RDFBasedFederationMember - Represents a federation member (data source) whose interface provides access to RDF data.
• fd:WrappedFederationMember - Represents a federation member (data source) that provides access to non-RDF data.
• fd:Wrapper - Represents the wrapper of a wrapped federation member, defining an RDF view of the data.
• fd:Interface - Represents the access mechanism used to query a federation member.
• fd:DataRetrievalProtocol - Represents the protocol to be used when interacting with the interface of a federation member.

2. Interface Types

Use one of the concrete subclasses of fd:Interface:

• fd:FixedEndpointInterface - For interfaces that can be accessed via a single, fixed endpoint address.
• fd:TemplateBasedInterface - For interfaces that can be accessed via request URIs that can be created based on a URI template.
• fd:FragmentInterface - For interfaces that can be accessed via URIs that denote fragments (i.e., specific subsets) of the dataset of the federation member.

3. Retrieval Protocols

The fd:DataRetrievalProtocol can be one of the following:

• fd:SPARQLProtocol - The protocol to be used for SPARQL endpoints.
• fd:TPFProtocol - The protocol to be used when interacting with a TPF server.
• fd:brTPFProtocol - The protocol to be used when interacting with a brTPF server.
• fd:GenericWebAPIProtocol - The protocol to be used when interacting with a generic Web
• fd:BoltProtocol - The protocol to be used when interacting with a Neo4j server.
• fd:GraphQLProtocol - The protocol to be used when interacting with a GraphQL server.
API.

4. Key Properties

• fd:serviceURI - An xsd:anyURI literal with a URI to be used to refer to the corresponding federation member in SERVICE clauses.
• fd:interface - Links a federation member to its interface.
• fd:wrapper - Links a wrapped federation member to its wrapper.
• fd:supportedProtocol - Links an interface to the fd:DataRetrievalProtocol that it supports.
• fd:endpointAddress - An xsd:anyURI literal with the URI of an fd:FixedEndpointInterface.
• fd:uriTemplate - Links an fd:TemplateBasedInterface to a definition of its URI template.
• fd:exampleFragmentAddress - An xsd:anyURI literal with an example URL of an fd:FragmentInterface.
• fd:vocabularyMappingsFile - Link to an RDF file aligning different vocabularies

4. Example Descriptions

SPARQL Endpoint

PREFIX xsd:  <http://www.w3.org/2001/XMLSchema#>
PREFIX fd:   <http://w3id.org/hefquin/feddesc#>
PREFIX ex:   <http://example.org/>

ex:dbpediaSPARQL a fd:RDFBasedFederationMember ;
    fd:serviceURI "http://dbpedia.org/sparql"^^xsd:anyURI ;
    fd:interface [
        a fd:FixedEndpointInterface ;
        fd:supportedProtocol fd:SPARQLProtocol ;
        fd:endpointAddress "http://dbpedia.org/sparql"^^xsd:anyURI
    ] .

TPF Server

PREFIX xsd:  <http://www.w3.org/2001/XMLSchema#>
PREFIX fd:   <http://w3id.org/hefquin/feddesc#>
PREFIX ex:   <http://example.org/>

ex:dbpediaTPF a fd:RDFBasedFederationMember ;
    fd:serviceURI "http://fragments.dbpedia.org/2016-04/en"^^xsd:anyURI ;
    fd:interface [
        a fd:FragmentInterface ;
        fd:supportedProtocol fd:TPFProtocol ;
        fd:exampleFragmentAddress "http://fragments.dbpedia.org/2016-04/en"^^xsd:anyURI
    ] .

RML-Wrapped REST Endpoint (with URI Template and RML Mapping)

PREFIX xsd:    <http://www.w3.org/2001/XMLSchema#>
PREFIX fd:     <http://w3id.org/hefquin/feddesc#>
PREFIX rml:    <http://w3id.org/rml/>
PREFIX hydra:  <http://www.w3.org/ns/hydra/core#>
PREFIX ex:     <http://example.org/>

ex:openMeteo a fd:WrappedFederationMember ;
    fd:serviceURI "http://example.org/OpenMeteoWrapper"^^xsd:anyURI ;
    fd:interface _:openMeteoRestEndpoint ;
    fd:wrapper _:openMeteoWrapper .

_:openMeteoRestEndpoint a fd:TemplateBasedInterface ;
      fd:supportedProtocol fd:GenericWebAPIProtocol ;
      fd:uriTemplate [
            hydra:template "https://api.open-meteo.com/v1/forecast{?latitude,longitude,current,hourly}" ;
            hydra:mapping [ hydra:variable "latitude" ;
                            hydra:required true ;
                            fd:paramType xsd:float
                          ] ;
            hydra:mapping [ hydra:variable "longitude" ;
                            hydra:required true ;
                            fd:paramType xsd:float
                          ] ;
            hydra:mapping [ hydra:variable "current" ;
                            fd:paramType xsd:string
                          ] ;
            hydra:mapping [ hydra:variable "hourly" ;
                            fd:paramType xsd:string
                          ]
          ] .

# the corresponding wrapper with two RML triples maps
_:openMeteoWrapper
      fd:rmlTriplesMaps ( _:openMeteoTM1 _:openMeteoTM2 ) .

_:openMeteoTM1
      rml:logicalSource [ rml:source _:openMeteoRestEndpoint ;
                          rml:referenceFormulation rml:JSONPath ;
                          rml:iterator "$.current" ] ;
      rml:subjectMap [ rml:termType rml:BlankNode ;
                       rml:reference "time" ];
      rml:predicateObjectMap [ rml:predicateMap [ rml:constant ex:temperature ] ;
                               rml:objectMap [ rml:reference "temperature_2m" ; rml:datatype xsd:double ] ] .

_:openMeteoTM2
      rml:logicalSource [ rml:source _:openMeteoRestEndpoint ;
                          rml:referenceFormulation rml:JSONPath ;
                          rml:iterator "$.current" ] ;
      rml:subjectMap [ rml:termType rml:BlankNode ;
                       rml:reference "time" ];
      rml:predicateObjectMap [ rml:predicateMap [ rml:constant ex:windSpeed ] ;
                               rml:objectMap [ rml:reference "wind_speed_10m" ; rml:datatype xsd:double ] ] .