Transformation Functions Ontology

Author: Dorian Taylor
Created: June 4, 2014
Updated: January 20, 2020; April 10, 2020; June 10, 2020; July 2, 2020; August 27, 2023; September 6, 2023; October 9, 2023; January 30, 2024; October 16, 2024; November 25, 2024; December 3, 2024
Namespace URI: https://vocab.methodandstructure.com/transformation#
Preferred Namespace Prefix: tfo
Imported Vocabularies: W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes; W3C PROVenance Interchange Ontology (PROV-O)

This document defines a vocabulary for representing the description and application of pure functions that transform byte segments. It is intended primarily for functions over HTTP representations—i.e., the actual literal payloads of HTTP messages—but can be used to represent other such functions.

Many, if not most Web content manipulation tasks are concerned exclusively with representations: the literal contents of HTTP messages, rather than abstract or internal representations. Such manipulations may include excerpting and rearranging files, compressing and decompressing, cropping and resizing images, and converting between data formats. If we separate these operations from other development tasks, we can reuse them.

The purpose of this vocabulary is to provide a mechanism for identifying pure functions that transform opaque data segments (like HTTP response bodies) and perhaps take additional scalar parameters (and specify both named and sequential calling conventions), and relate a function definition to a concrete implementation. The vocabulary also provides terms to represent memoizing the application of a function to a particular data object, i.e., relating a particular input (plus any additional parameters) to a particular output.

Consider the following example:

@prefix tfo:  <https://vocab.methodandstructure.com/transformation#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix owl:  <http://www.w3.org/2002/07/owl#> .
@prefix xsd:  <http://www.w3.org/2001/XMLSchema#> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix dct:  <http://purl.org/dc/terms/> .
@prefix prov: <http://www.w3.org/ns/prov#> .
@prefix ex:   <https://example.club/#> .

ex:range a tfo:Function ;
  skos:prefLabel "Byte Range"@en ;
  skos:description "Select a subset of bytes from a given segment."@en ;
  tfo:accepts "*/*"^^tfo:content-type ;
  tfo:returns "*/*"^^tfo:content-type ;
  tfo:parameter ex:start, ex:end ;
  tfo:parameter-list ( ex:start ex:end ) ;
  tfo:implementation <jar:functions.jar!org/foobar/textproc/ByteRange.class> .

ex:start a tfo:Parameter ;
  dct:identifier "start"^^xsd:token ;
  rdfs:comment "The beginning offset (omission interpreted as zero)."@en ;
  owl:maxCardinality 1 ;
  rdfs:range xsd:nonNegativeInteger .

ex:end a tfo:Parameter ;
  dct:identifier "end"^^xsd:token ;
  rdfs:comment "The ending offset (omission interpreted as the end of the input)."@en ;
  owl:maxCardinality 1 ;
  rdfs:range xsd:nonNegativeInteger .

<urn:uuid:1d85f168-1710-4bc8-b68b-c7513483c228> a tfo:Invocation ;
  prov:startedAtTime "2020-01-20T16:46:27.043Z"^^xsd:dateTime ;
  prov:endedAtTime "2020-01-20T16:46:27.051Z"^^xsd:dateTime ;
  tfo:transform ex:range ;
  tfo:input <ni:///sha-256;fzhKzqnfAxmB9ICBwe00Dq3smuo43J2K-58uL_62t6Q> ;
  ex:start 1234 ;
  ex:end 31337 ;
  tfo:output <ni:///sha-256;QqNiOgLJk13nOs8Mn4prYtEIZZfwuiju2y4cT_YCOlI> .

The preceding example defines a transformation function, along with its parameters, and relates it to a fictional implementation embedded in a JAR somewhere (the exact way an implementation is resolved is out of scope for this vocabulary). At the bottom is an imaginary application of the transformation function, along with values for supplied parameters. The input and output are designated by digest URIs, which can be resolved to their corresponding representations.

This vocabulary extends the Data Catalog Vocabulary by making tfo:Function a subclass of dcat:DataService and the Provenance Ontology, by way of refining the prov:Activity class and related properties. For instance, a record can use its inherited PROV properties to store metrics on the time it took to execute the function over the input.

Classes

Bundles

The Transformation Functions Ontology includes a basic bundling class that affords the reuse of parameters, e.g. for configuration.

`Bundle`

This class provides a basic mechanism to yoke a set of transformation functions together.

Subclass of:: dcat:Catalog; prov:SoftwareAgent
Properties:: tfo:implementation

Transforms

A tfo:Function is essentially a function definition, specifying input and output constraints, and parameters in both named and positional representations.

`Function`

This class provides a specification for a transformation function.

Subclass of:: dcat:DataService; prov:Entity
Properties:: tfo:parameter; tfo:parameter-list; tfo:accepts; tfo:returns; tfo:prefers; tfo:precedes; tfo:follows; tfo:triggers; tfo:by-uri; tfo:not-by-uri

`MarkupTransform`

This class represents the set of transformation functions that operate exclusively over (HTML/XML) markup.

Subclass of:: tfo:Function
Properties:: ~~tfo:by-xpath~~; ~~tfo:not-by-xpath~~

Parameters

tfo:Parameter entities encapsulate name, type, and cardinality of a given function parameter, while tfo:ParameterList entities specify position.

`Parameter`

This class provides a specification for a parameter in a given function.

Subclass of:: rdf:Property
Property restrictions:: rdfs:domain ∈ (tfo:Partial ∪ tfo:Bundle)
Properties:: tfo:default; tfo:empty; tfo:shift; tfo:universe

`Composite`

A composite parameter has a multi-valued value like a list, tuple, set or range.

Subclass of:: tfo:Parameter
Properties:: tfo:element
See also:: rdf:Bag; rdf:List; tfo:Range

`ParameterList`

This class represents a list with the restriction that its members be tfo:Parameter nodes.

Subclass of:: rdf:List
Property restrictions:: rdf:first ∈ tfo:Parameter; rdf:rest ∈ tfo:ParameterList

`Range`

A span of numbers or sequence-able objects, like dates.

Subclass of:: rdfs:Container
Properties:: tfo:low; tfo:high; tfo:infimum; tfo:supremum

Queues

Queues are how we bundle sequences of tfo:Function (or tfo:Partial) for execution. Queue is something of a misnomer, as the sequence of transforms need not be explicitly asserted, but rather negotiated on the fly.

`Queue`

A queue is a collection of tfo:Function (and/or tfo:Partial) elements, organized either by explicit sequence (via tfo:member-list), or by dynamic sorting at runtime.

Subclass of:: prov:Activity
Properties:: tfo:member; tfo:member-list; tfo:first; tfo:last; tfo:next

`StrictQueue`

A strict queue is one for which all its elements must be executed, unlike an ordinary queue which only has to attempt to run its contents.

Subclass of:: tfo:Queue

`AddressableQueue`

An addressable queue is a strict queue intended to hold transforms that have been invoked through the URL.

Subclass of:: tfo:StrictQueue

`FunctionList`

A function list is a list that only holds tfo:Function or tfo:Partial entities.

Subclass of:: rdf:List
Property restrictions:: rdf:first ∈ tfo:Function ∪ tfo:Partial; rdf:rest ∈ tfo:FunctionList

`Insertion`

An insertion is a pre-packaged event that manipulates a per-request instance of a transformation queue. When the result of the transform being run matches the condition, the contents of the tfo:Insertion are inserted into the target queue.

Subclass of:: tfo:Queue
Properties:: tfo:condition; tfo:target

Function Invocation

Recording partial and full function invocations is important for memoizing computations.

`Invocation`

This class represents an invocation of a transformation function, connecting a specific input and scalar parameters with its output.

Subclass of:: tfo:Partial
Equivalent to:: tfo:Application
Properties:: tfo:completes; tfo:input; tfo:output

`Partial`

This class represents a partial application of a transformation function, affording the encapsulation and re-use of existing parameters.

Subclass of:: prov:Activity
Properties:: tfo:transform

Properties

Specifying Transforms

These properties have to do with specifying tfo:Function entities and their parameters.

`accepts`

Specifies the list of content-types, in order of preference, that the function can process.

Domain:: dcat:DataService
Range:: tfo:content-type ∪ rdf:List

`returns`

Specifies the list of content-types, in order of preference, that the function is capable of returning.

Domain:: dcat:DataService
Range:: tfo:content-type ∪ rdf:List

`prefers`

Specifies the tfo:content-type the transform prefers to emit in lieu of a preference specified by the request. May be a list.

Subproperty of:: tfo:returns
Domain:: tfo:Function
Range:: tfo:content-type ∪ rdf:List

`implementation`

URI to the implementation of the function.

Domain:: tfo:Bundle
Range:: rdfs:Resource

`parameter`

Binds a parameter object to its function.

Domain:: dcat:Resource
Range:: tfo:Parameter

`parameter-list`

Specifies the sequence of parameters when the invocation method of the function is sequential.

Domain:: dcat:Resource
Range:: tfo:ParameterList

`element`

This property designates an elementary type to go into the composite type.

Domain:: tfo:Composite
Range:: rdfs:Datatype

`default`

Specifies one or more default values for a parameter.

Domain:: tfo:Parameter

`universe`

Specifies the container that contains the universe of values that a paramter can take.

Domain:: tfo:Parameter
Range:: rdfs:Container

`empty`

Flags whether an empty parameter value should be treated as input rather than ignored.

Domain:: tfo:Parameter
Range:: xsd:boolean

`shift`

Flags whether a parameter with multiple values but a fixed cardinality shift off the front of the list rather than truncate off the back.

Domain:: tfo:Parameter
Range:: xsd:boolean

`low`

Specifies the lower bound of a tfo:Range.

Domain:: tfo:Range
Range:: rdfs:Literal

`high`

Specifies the upper bound of a tfo:Range.

Domain:: tfo:Range
Range:: rdfs:Literal

`infimum`

Flags whether a tfo:Range will be open on the low side.

Domain:: tfo:Range
Range:: xsd:boolean

`supremum`

Flags whether a tfo:Range will be open on the high side.

Domain:: tfo:Range
Range:: xsd:boolean

Specifying Queues

These properties all have to do with providing hints to topological sorts of transforms within queues, or otherwise explicit sequences.

`member`

Denotes a member of a queue.

Domain:: tfo:Queue
Range:: tfo:Function ∪ tfo:Partial

`member-list`

Denotes an explicit member list for a queue.

Domain:: tfo:Queue
Range:: tfo:FunctionList

`precedes`

Specifies one or more tfo:Function that the subject must precede in a queue.

Domain:: tfo:Function
Range:: tfo:Function
Inverse of:: tfo:follows

`follows`

Specifies one or more tfo:Function that the subject must follow in a queue.

Domain:: tfo:Function
Range:: tfo:Function
Inverse of:: tfo:precedes

`next`

Specifies the next queue to run after this one.

Domain:: tfo:Queue
Range:: tfo:Queue

`first`

Explicitly specifies a transform that must go first.

Sub-property of:: tfo:member
Domain:: tfo:Queue
Range:: tfo:Function ∪ tfo:Partial

`last`

Explicitly specifies a transform that must go last.

Sub-property of:: tfo:member
Domain:: tfo:Queue
Range:: tfo:Function ∪ tfo:Partial

Manipulating Queues at Runtime

These properties relate trnasforms to queue insertion events.

`triggers`

A tfo:Function can trigger an tfo:Insertion event on a certain condition (e.g., successful completion).

Domain:: tfo:Function
Range:: tfo:Insertion

`target`

A target queue for the insertion.

Domain:: tfo:Insertion
Range:: tfo:Queue

`condition`

An HTTP status code for which the insertion is triggered.

Domain:: tfo:Insertion
Range:: ht:StatusCode

Applying Transformations

This group of properties is responsible for relating tfo:Function to the actual data objects they transform.

`completes`

Identifies a tfo:Partial function that this tfo:Invocation completes.

Domain:: tfo:Invocation
Range:: tfo:Partial

`transform`

Specifies the transform associated with this particular invocation.

Subproperty of:: prov:used
Domain:: tfo:Partial
Range:: tfo:Function

`input`

Specifies the resource that was the input of the transformation function.

Subproperty of:: prov:used
Domain:: tfo:Invocation
Range:: rdfs:Resource
See also:: RFC 6920 — Naming Things with Hashes

`output`

Specifies the resource that was the output of the transformation function.

Domain:: tfo:Invocation
Range:: rdfs:Resource
See also:: RFC 6920 — Naming Things with Hashes

Constraints

In certain contexts it is useful to pre-declare constraints on what constitutes valid input for a transform. We can do this either by URI or by XPath.

`by-uri`

Specifies a regular expression for matching against URIs.

Domain:: tfo:Function
Range:: tfo:regexp

`not-by-uri`

Specifies a regular expression for anti-matching against URIs.

Domain:: tfo:Function
Range:: tfo:regexp

`prefix`

Specifies a SHACL prefix declaration for complementing any associated XPath expression.

Domain:: tfo:MarkupTransform
Range:: sh:PrefixDeclaration

`by-xpath`

Specifies an XPath expression for matching against markup (HTML/XML) content.

Domain:: ~~tfo:MarkupTransform~~
Range:: ~~tfo:xpath~~

`not-by-xpath`

Specifies an XPath expression for anti-matching against markup (HTML/XML) content.

Domain:: ~~tfo:MarkupTransform~~
Range:: ~~tfo:xpath~~

Classes

Bundles

Bundle

Transforms

Function

MarkupTransform

Parameters

Parameter

Composite

ParameterList

Range

Queues

Queue

StrictQueue

AddressableQueue

FunctionList

Insertion

Function Invocation

Invocation

Partial

Properties

Specifying Transforms

accepts

returns

prefers

implementation

parameter

parameter-list

element

default

universe

empty

shift

low

high

infimum

supremum

Specifying Queues

member

member-list

precedes

follows

next

first

last

Manipulating Queues at Runtime

triggers

target

condition