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
Namespace URI
https://vocab.methodandstructure.com/transformation#
Preferred Namespace Prefix
tfo
Imported Vocabularies
W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes

This document describes functions which transform HTTP representations, i.e., the actual literal payloads of HTTP messages.

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 a mechanism for 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 a transform's 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

ParameterList

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

Subclass of:
rdf:List
Property restrictions:
rdf:firsttfo:Parameter
rdf:resttfo:ParameterList

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:resttfo: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

Back to Top

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

Back to Top

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

Back to Top

implementation

URI to the implementation of the function.

Domain:
tfo:Bundle
Range:
rdfs:Resource

Back to Top

parameter

Binds a parameter object to its function.

Domain:
dcat:DataService
Range:
tfo:Parameter

Back to Top

parameter-list

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

Domain:
dcat:DataService
Range:
tfo:ParameterList

Back to Top

default

Specifies one or more default values for a parameter.

Domain:
tfo:Parameter

Back to Top

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

Back to Top

member-list

Denotes an explicit member list for a queue.

Domain:
tfo:Queue
Range:
tfo:FunctionList

Back to Top

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

Back to Top

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

Back to Top

next

Specifies the next queue to run after this one.

Domain:
tfo:Queue
Range:
tfo:Queue

Back to Top

first

Explicitly specifies a transform that must go first.

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

Back to Top

last

Explicitly specifies a transform that must go last.

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

Back to Top

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

Back to Top

target

A target queue for the insertion.

Domain:
tfo:Insertion
Range:
tfo:Queue

Back to Top

condition

An HTTP status code for which the insertion is triggered.

Domain:
tfo:Insertion
Range:
http:StatusCode

Back to Top

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

Back to Top

transform

Specifies the transform associated with this particular invocation.

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

Back to Top

input

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

Subproperty of:
prov:used
Domain:
tfo:Invocation
Range:
rdfs:Resource

Back to Top

output

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

Domain:
tfo:Invocation
Range:
rdfs:Resource

Back to Top

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

Back to Top

not-by-uri

Specifies a regular expression for anti-matching against URIs.

Domain:
tfo:Function
Range:
tfo:regexp

Back to Top

prefix

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

Domain:
tfo:MarkupTransform
Range:
sh:PrefixDeclaration

Back to Top

by-xpath

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

Domain:
tfo:MarkupTransform
Range:
tfo:xpath

Back to Top

not-by-xpath

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

Domain:
tfo:MarkupTransform
Range:
tfo:xpath

Back to Top

Datatypes

Currently there is only the datatype for designating content types, and those for regular expressions and XPath.

content-type

A literal that represents a content-type such as that which is found in the HTTP Accept: or Content-Type: header.

Restriction of:
xsd:token matching ^([!#$%&'\*\+\-.^_`|~0-9-A-Za-z]+)(?:/[!#$%&'\*\+\-.^_`|~0-9-A-Za-z]+)?)$
See also:
RFC 7230 — Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing § 3.2.6: Field Value Components
RFC 7231 — Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content § 5.3.2: Accept

Back to Top

regexp

A regular expression.

Restriction of:
xsd:string

Back to Top

iregexp

A case-insensitive regular expression.

Subclass of:
tfo:regexp
Restriction of:
xsd:string

Back to Top

xpath

An XPath expression.

Restriction of:
xsd:string

Back to Top

References