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
Namespace URI
https://vocab.methodandstructure.com/transformation#
Preferred Namespace Prefix
tfo

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:Transform ;
  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:Application ;
  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 Provenance Ontology, by way of refining the prov:SoftwareAgent and prov:Activity classes, 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

Transforms

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

Transform

This class provides a specification for a transformation function.

Subclass of:
prov:SoftwareAgent
Properties:
tfo:implementation
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:Transform
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:domaintfo:Partial
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:Transform (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:Transform (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

TransformList

A transform list is a list that only holds tfo:Transform or tfo:Partial entities.

Subclass of:
rdf:List
Property restrictions:
rdf:first tfo:Transform tfo:Partial
rdf:resttfo:TransformList

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 Application

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

Application

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

Subclass of:
tfo:Partial
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:Transform entities and their parameters.

accepts

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

Domain:
tfo:Transform
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:
tfo:Transform
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:Transform
Range:
tfo:content-type rdf:List

Back to Top

implementation

URI to the implementation of the function.

Domain:
tfo:Transform
Range:
rdfs:Resource

Back to Top

parameter

Binds a parameter object to its function.

Domain:
tfo:Transform
Range:
tfo:Parameter

Back to Top

parameter-list

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

Domain:
tfo:Transform
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:Transform tfo:Partial

Back to Top

member-list

Denotes an explicit member list for a queue.

Domain:
tfo:Queue
Range:
tfo:TransformList

Back to Top

precedes

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

Domain:
tfo:Transform
Range:
tfo:Transform
Inverse of:
tfo:follows

Back to Top

follows

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

Domain:
tfo:Transform
Range:
tfo:Transform
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:Transform tfo:Partial

Back to Top

last

Explicitly specifies a transform that must go last.

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

Back to Top

Manipulating Queues at Runtime

These properties relate trnasforms to queue insertion events.

triggers

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

Domain:
tfo:Transform
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:Transform to the actual data objects they transform.

completes

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

Domain:
tfo:Application
Range:
tfo:Partial

Back to Top

transform

Specifies the transform associated with this particular application

Domain:
tfo:Partial
Range:
tfo:Transform

Back to Top

input

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

Domain:
tfo:Application
Range:
rdfs:Resource

Back to Top

output

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

Domain:
tfo:Application
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:Transform
Range:
tfo:regexp

Back to Top

not-by-uri

Specifies a regular expression for anti-matching against URIs.

Domain:
tfo:Transform
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