Façade-X Engine vocabulary

Options for engines that build Façade-X representations of resources.

This document specifies the Façade-X Engine vocabulary: the terms used to configure an engine that builds the Façade-X representation of a resource. The vocabulary is independent of the Façade-X Schema vocabulary, which describes the representation itself, and of the language used to request it, such as SPARQL.

This is the editor's draft of this document. It changes with every update to the specification sources and is not a stable release. The latest release, version 0.1, is at https://w3c-facade-x.github.io/facade-x-specs/engine.html.

This document is currently in active development. The terms are derived from the configuration options of the reference implementation, SPARQL Anything.

Set of Documents

This document is one of seven Façade-X specification documents produced by the Data Façades Community Group:

  1. Façade-X Overview
  2. Façade-X Primer
  3. Façade-X Schema vocabulary
  4. Façade-X Engine vocabulary (this document)
  5. Façade-X Data Access in SPARQL
  6. Façade-X Concepts and Metamodel Specification
  7. Façade-X Mappings

Introduction

An engine takes a resource and a set of options and produces a Façade-X data source, as defined by the metamodel and the Schema vocabulary. This document names those options.

The Schema and Engine vocabularies are kept separate for three reasons:

Namespaces

Prefix Namespace Description
fxe http://sparql.xyz/facade-x/engine/ The Façade-X Engine vocabulary (this document)
fx http://sparql.xyz/facade-x/ns/ The Façade-X Schema vocabulary
xyz http://sparql.xyz/facade-x/data/ The default namespace for derived data
rdf http://www.w3.org/1999/02/22-rdf-syntax-ns# [rdf-schema]
rdfs http://www.w3.org/2000/01/rdf-schema# [rdf-schema]
xsd http://www.w3.org/2001/XMLSchema# [xmlschema-2]

Issues

The namespace http://sparql.xyz/facade-x/engine/ is a placeholder. The reference implementation currently uses the Schema namespace for options (e.g. fx:location). Until the namespace is settled, an implementation MAY accept each option both as fxe:[NAME] and as fx:[NAME].

Execution options (e.g. strategy, slice, ondisk), and options for HTTP and S3 access, are not yet covered.

Format-specific options (e.g. csv.headers, json.path, xml.path) are out of scope for this document and are expected to be specified with the format mappings.

Classes

Configuration

The class of engine configurations. A configuration is a set of option values applied to one invocation of an engine.

  • IRI: http://sparql.xyz/facade-x/engine/Configuration
  • Sub Class Of: rdfs:Resource
  • Predicates: ANY instance of fxe:Option

Option

The class of engine options. Every term in the Options section is an instance of this class.

  • IRI: http://sparql.xyz/facade-x/engine/Option
  • Sub Class Of: rdf:Property
  • Instances - Domain: http://sparql.xyz/facade-x/engine/Configuration

Options

All options are optional, except that exactly one source option (fxe:location, fxe:content, fxe:command, fxe:read-from-std-in, or fxe:query) MUST be given. Values are literals; an engine MUST accept the lexical form of the stated range as a plain string.

Source options

Options that identify the resource and how its bytes are read.

Term Range Default Description
fxe:location xsd:string — A URL, or an absolute or relative file-system path, of the resource to be interpreted.
fxe:content xsd:string — Inline content to be interpreted in place of a located resource. Without fxe:media-type the content is interpreted as plain text.
fxe:command xsd:string — An external command line whose standard output is interpreted according to fxe:media-type.
fxe:read-from-std-in xsd:boolean false Read the content from standard input and use it as the value of fxe:content.
fxe:query xsd:string — Location of a SPARQL query whose result (bindings, graph, or dataset) is used as the source. When set, other options are ignored.
fxe:from-archive xsd:string — Location of an archive; fxe:location is then resolved as an entry within it.
fxe:archive-format xsd:string Inferred from the archive location Format of the archive given in fxe:from-archive (e.g. zip, tar).
fxe:media-type xsd:string Inferred from the file extension The media type of the source, selecting the interpretation. Required when it cannot be inferred.
fxe:charset xsd:string UTF-8 The character encoding of the source.

Mapping options

Options that change the Façade-X representation produced for a resource. Two engines given the same resource and the same mapping options MUST produce isomorphic representations.

Term Range Default Description
fxe:root xsd:anyURI Location + #, or xyz: + md5(content or command) + # IRI of the root container; also the base for minting graph and container IRIs.
fxe:namespace xsd:anyURI http://sparql.xyz/facade-x/data/ Namespace used to mint string-slot properties and types from source keys and tags.
fxe:blank-nodes xsd:boolean true Represent containers as blank nodes. When false, container IRIs are minted from fxe:root.
fxe:trim-strings xsd:boolean false Trim leading and trailing whitespace from string values.
fxe:null-string xsd:string — Omit any triple whose object value would equal the given string.
fxe:use-rdfs-member xsd:boolean false Use rdfs:member in place of rdf:_1, rdf:_2, …
fxe:annotate-triples-with-slot-keys xsd:boolean false Annotate slot triples with their key using fx:slot-key (RDF 1.2 triple terms).
fxe:generate-predicate-labels xsd:boolean false Emit rdfs:label for minted properties and types.
fxe:metadata xsd:boolean false Extract resource metadata into the graph xyz:metadata.
fxe:audit xsd:boolean false Emit an audit graph xyz:audit describing each generated graph.

Using the vocabulary

In RDF

A configuration can be described in RDF as an instance of fxe:Configuration:

@prefix fxe: <http://sparql.xyz/facade-x/engine/> .

<#people> a fxe:Configuration ;
    fxe:location   "https://example.org/people.json" ;
    fxe:media-type "application/json" ;
    fxe:blank-nodes false .

In SPARQL

The SPARQL access document defines how options are supplied in a SERVICE clause, either in the service IRI (by local name) or as triples with the reserved subject fx:properties.

As key-value pairs

Outside RDF, an option MAY be written by its local name, e.g. media-type=application/json, as in command-line arguments or configuration files.

Security considerations

fxe:command executes a program on the engine host. fxe:location, fxe:query, and fxe:read-from-std-in may give access to the local file system or process input. An engine exposed to untrusted requests SHOULD allow these options to be disabled or restricted.

Vocabulary in Turtle

@prefix fxe:  <http://sparql.xyz/facade-x/engine/> .
@prefix rdf:  <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .

<http://sparql.xyz/facade-x/engine/> rdfs:label "Façade-X Engine vocabulary" .

fxe:Configuration a rdfs:Class ;
    rdfs:label "Configuration" ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

fxe:Option a rdfs:Class ;
    rdfs:label "Option" ;
    rdfs:subClassOf rdf:Property ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

# Source options
fxe:location a rdf:Property, fxe:Option ;
    rdfs:label "location" ;
    rdfs:comment "A URL, or an absolute or relative file-system path, of the resource to be interpreted." ;
    rdfs:domain fxe:Configuration ;
    rdfs:range xsd:string ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

fxe:content a rdf:Property, fxe:Option ;
    rdfs:label "content" ;
    rdfs:comment "Inline content to be interpreted in place of a located resource. Without fxe:media-type the content is interpreted as plain text." ;
    rdfs:domain fxe:Configuration ;
    rdfs:range xsd:string ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

fxe:command a rdf:Property, fxe:Option ;
    rdfs:label "command" ;
    rdfs:comment "An external command line whose standard output is interpreted according to fxe:media-type." ;
    rdfs:domain fxe:Configuration ;
    rdfs:range xsd:string ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

fxe:read-from-std-in a rdf:Property, fxe:Option ;
    rdfs:label "read-from-std-in" ;
    rdfs:comment "Read the content from standard input and use it as the value of fxe:content." ;
    rdfs:domain fxe:Configuration ;
    rdfs:range xsd:boolean ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

fxe:query a rdf:Property, fxe:Option ;
    rdfs:label "query" ;
    rdfs:comment "Location of a SPARQL query whose result (bindings, graph, or dataset) is used as the source. When set, other options are ignored." ;
    rdfs:domain fxe:Configuration ;
    rdfs:range xsd:string ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

fxe:from-archive a rdf:Property, fxe:Option ;
    rdfs:label "from-archive" ;
    rdfs:comment "Location of an archive; fxe:location is then resolved as an entry within it." ;
    rdfs:domain fxe:Configuration ;
    rdfs:range xsd:string ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

fxe:archive-format a rdf:Property, fxe:Option ;
    rdfs:label "archive-format" ;
    rdfs:comment "Format of the archive given in fxe:from-archive (e.g. zip, tar)." ;
    rdfs:domain fxe:Configuration ;
    rdfs:range xsd:string ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

fxe:media-type a rdf:Property, fxe:Option ;
    rdfs:label "media-type" ;
    rdfs:comment "The media type of the source, selecting the interpretation. Required when it cannot be inferred." ;
    rdfs:domain fxe:Configuration ;
    rdfs:range xsd:string ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

fxe:charset a rdf:Property, fxe:Option ;
    rdfs:label "charset" ;
    rdfs:comment "The character encoding of the source." ;
    rdfs:domain fxe:Configuration ;
    rdfs:range xsd:string ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

# Mapping options
fxe:root a rdf:Property, fxe:Option ;
    rdfs:label "root" ;
    rdfs:comment "IRI of the root container; also the base for minting graph and container IRIs." ;
    rdfs:domain fxe:Configuration ;
    rdfs:range xsd:anyURI ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

fxe:namespace a rdf:Property, fxe:Option ;
    rdfs:label "namespace" ;
    rdfs:comment "Namespace used to mint string-slot properties and types from source keys and tags." ;
    rdfs:domain fxe:Configuration ;
    rdfs:range xsd:anyURI ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

fxe:blank-nodes a rdf:Property, fxe:Option ;
    rdfs:label "blank-nodes" ;
    rdfs:comment "Represent containers as blank nodes. When false, container IRIs are minted from fxe:root." ;
    rdfs:domain fxe:Configuration ;
    rdfs:range xsd:boolean ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

fxe:trim-strings a rdf:Property, fxe:Option ;
    rdfs:label "trim-strings" ;
    rdfs:comment "Trim leading and trailing whitespace from string values." ;
    rdfs:domain fxe:Configuration ;
    rdfs:range xsd:boolean ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

fxe:null-string a rdf:Property, fxe:Option ;
    rdfs:label "null-string" ;
    rdfs:comment "Omit any triple whose object value would equal the given string." ;
    rdfs:domain fxe:Configuration ;
    rdfs:range xsd:string ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

fxe:use-rdfs-member a rdf:Property, fxe:Option ;
    rdfs:label "use-rdfs-member" ;
    rdfs:comment "Use rdfs:member in place of rdf:_1, rdf:_2, …" ;
    rdfs:domain fxe:Configuration ;
    rdfs:range xsd:boolean ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

fxe:annotate-triples-with-slot-keys a rdf:Property, fxe:Option ;
    rdfs:label "annotate-triples-with-slot-keys" ;
    rdfs:comment "Annotate slot triples with their key using fx:slot-key (RDF 1.2 triple terms)." ;
    rdfs:domain fxe:Configuration ;
    rdfs:range xsd:boolean ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

fxe:generate-predicate-labels a rdf:Property, fxe:Option ;
    rdfs:label "generate-predicate-labels" ;
    rdfs:comment "Emit rdfs:label for minted properties and types." ;
    rdfs:domain fxe:Configuration ;
    rdfs:range xsd:boolean ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

fxe:metadata a rdf:Property, fxe:Option ;
    rdfs:label "metadata" ;
    rdfs:comment "Extract resource metadata into the graph xyz:metadata." ;
    rdfs:domain fxe:Configuration ;
    rdfs:range xsd:boolean ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

fxe:audit a rdf:Property, fxe:Option ;
    rdfs:label "audit" ;
    rdfs:comment "Emit an audit graph xyz:audit describing each generated graph." ;
    rdfs:domain fxe:Configuration ;
    rdfs:range xsd:boolean ;
    rdfs:isDefinedBy <http://sparql.xyz/facade-x/engine/> .

References

[rdf-schema]
RDF Schema 1.1. Dan Brickley; Ramanathan Guha. W3C. 25 February 2014. W3C Recommendation.
[xmlschema-2]
XML Schema Part 2: Datatypes Second Edition. Paul V. Biron; Ashok Malhotra. W3C. 28 October 2004. W3C Recommendation.
[sparql-anything]
SPARQL Anything — Configuration.