Getting Started 

The basic idea of a TVD (Tabular Vocabulary Definition) is that it allows the definition terms used in an RDF vocabulary in a tabular format. These can be generated in spreadsheets or anything that can export a csv file. Each row comprises the definition of a single RDF term. Each column contains information about one aspect of the term, the column header is used to identify which aspect. A YAML config file defines how each column is processed. TVD2RDF allows a TVD saved as a CSV file to be converted into RDF encoded vocabulary definitions in a variety of serialization formats.

Installation 

TVD2RDF can be installed from its git repository on codeberg.org. You must have installed Python version 3.12 or higher, including pip, and software to clone git repositories.

First, clone the git repository into a local folder:

$ git clone https://codeberg.org/philbarker/TabularVocabDef.git
$ cd TabularVocabDef

It is recommended to use a virtual environment for TVD2RDF:

$ python -m venv venv
$ source venv/bin/activate

Install and check version:

(venv) $ pip install .
(venv) $ tvd -v
tvd 0.5.3

Optional: install dependencies used in development only:

(venv) $ pip install .[dev]

Basic Usage 

You will need a CSV file containing the Tabular Vocabulary Definition, and a YAML config file that describes how to interpret this file.

The TVD can be edited any tool that exports CSV files, such as spreadsheet software. The first row of the CSV will be treated as column headings. The only required headings are Type and URI which map to the type of term being described and ther term’s URI. Other common headings in the CSV stand for the name and definition of the term.

An example of a very simple TVD:

Type	URI	Label	Comment
Property	dct:title	Title	A name given to the resource.

TVD2RDF comes with a default config file which is used if no other file is specified. For the simple example above the default is sufficient. So if the tabular definition above is entered into a suitable tool, exported as a CSV file and saved as ex-tvd.csv in the TabularVocabDef directory where we installed TVD2RDF, the following will convert it to RDF:

(venv) $ tvd convert ex-tvd.csv

# RDF generated by TVD2RDF Converter v0.5.2.

@prefix dct: <http://purl.org/dc/terms/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .

dct:title a rdf:Property ;
    rdfs:label "Title" ;
    rdfs:comment "A name given to the resource." .

The help for the tvd convert command provides information on further options for conversion, such as different serialization formats and writing the RDF to a file:

(venv) $ tvd convert -h
usage: tvd convert [-h] [-ns <namespace filename>]
                [-of <output format, e.g. turtle, n3, xml>] [-c config filename]
                <tvd filename> [<output filename>]

Convert a tvd from CSV to RDF.

positional arguments:
<tvd filename>
<output filename>

options:
-h, --help            show this help message and exit
-ns <namespace filename>, --namespace_fn <namespace filename>
-of <output format, e.g. turtle, n3, xml>, --output_fmt <output format, e.g. turtle, n3, xml>
-c config filename, --config_fn config filename

Further Usage 

Basic information about terms can be encoded in a TVD without modifying the default configuration.

Types of term that are covered 

Definitions of OWL Ontologies, RDF Classes, RDFS Properties, SKOS Concept Schemes, and SKOS Concepts. Use one of the following key words in the Type column of the TVD: Ontology, Class, Property, Concept Scheme, Concept.

Note

It is not intended that a TVD be used to define complex OWL Ontologies with defined axioms and named instances such as would be better managed with a tool such as protege.

The inclusion of Ontology in the type of “term” that may be defined in a TVD allows for sets of RDF definitions that can be processed with tools such as pyLode that look for information for an owl:Ontology.

Attributes of terms that may be defined 

In all cases the coverage of term attributes that may be defined is somewhat limited, but includes a label or title, a definition or description, a note about the term, classes in the range and domain of a property and relationships between concepts using various SKOS terms.

Note

The domain and range of a property are indicated using schema.org domainIncludes and rangeIncludes by default.

This gives behaviour that is more intuitive to general users who are not familiar with rdf:domain and range when there is more than one class specified.

Default mapping from column headings to RDF properties 

Entries under the column headings URI and Type are required and provide the URI and Type for the term being defined.

The column headings Related Term and Relationship are used to express relationships between terms, see below.

By default, for under following column headings will be mapped as shown for all types of term:

Comment:: maps to rdfs:comment
Date:: maps to dcterms:date
Notation:: maps to skos:notation
Usage:: maps to skos:scopeNote

For Properties only:

domainIncludes:: maps to schema:domainIncludes
rangeIncludes:: maps to schema:rangeIncludes

Entries under other column headings will be mapped according to the type of term being defined:

Label:

maps to

rdfs:label for Ontologies, Classes and Properties
dct:title for Concept Schemes
skos:prefLabel for Concepts

Definition:

maps to

dct:description for Concept Schemes
skos:definition for Concepts

Warning

The default coverage may change in future versions.

Multiple object values 

Where the value of an attribute may be multiple URIs, for example with domain and range includes, several values may be entered in a cell in the TVD is separated by one of the following characters: ,, ;, \n (new line), or combinations thereof. This does not apply to literal values such as the label or definition of a term.

Relationships between terms 

A pair of columns headed Related Term and Relationship may be used to specify relationships between terms. Currently the default config covers the following relationships that may be entered in the Relatinoship column:

broadMatch for skos:broadMatch
broader for skos:broader
closeMatch for skos:closeMatch
hasTopConcept for skos:hasTopConcept
inScheme for skos:inScheme
narrowMatch for skos:narrowMatch
narrower for skos:narrower
topConceptOf for skos:topConceptOf

Further information on configuring Tabular Vocabulary Definitions is provided in the following section.

Example TVDs 

The following is an example of a small vocabulary comprising an RDF classes and Properties defined by a TVD using only the default column headings.

Type	URI	Label	Comment	Usage	Domain Includes	Range Includes
Ontology	ex:	Test Terms	A test RDF vocabulary.	Used for testing VocabDef
Class	ex:Document	Document	A written resource.	Documents may be in physical or digital media.
Property	ex:createdDateTime	Created Date Time	The date and Time stamp when the Resource was created.			xsd:dateTime
Property	ex:description	Description	A short account of the resource.
Property	ex:author	Author	The organization or person who created the document.		ex:Document ex:File	sdo:Person sdo:Organization

which is processed to

# RDF generated by TVD2RDF Converter v0.5.2.
@prefix ex: <https://example.org/terms#> .
@prefix owl: <http://www.w3.org/2002/07/owl#> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix sdo: <https://schema.org/> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

ex: a owl:Ontology ;
    rdfs:label "Test Terms" ;
    rdfs:comment "A test RDF vocabulary." ;
    skos:scopeNote "Used for testing VocabDef" .

ex:Document a rdfs:Class ;
    rdfs:label "Document" ;
    rdfs:comment "A written resource." ;
    skos:scopeNote "Documents may be in physical or digital media." .

ex:author a rdf:Property ;
    rdfs:label "Author" ;
    rdfs:comment "The organization or person who created the document." ;
    sdo:domainIncludes ex:Document,
        ex:File ;
    sdo:rangeIncludes sdo:Organization,
        sdo:Person .

ex:createdDateTime a rdf:Property ;
    rdfs:label "Created Date Time" ;
    rdfs:comment "The date and Time stamp when the Resource was created." ;
    sdo:rangeIncludes xsd:dateTime .

ex:description a rdf:Property ;
    rdfs:label "Description" ;
    rdfs:comment "A short account of the resource." .

This second example is of a TVD which defines a small Concept Scheme:

Type	URI	Label	Definition	Notation	Related term	Relationship	date
Concept Scheme	ex:colours	Colours	An example concept scheme for some colours.		ex:red ex:green ex:blue	hasTopConcept	2026-01-16
Concept	ex:red	Red	The primary colour wavelength 625–750nm.	r	ex:colours	inScheme
Concept	ex:red			FF0000	ex:colours	topConceptOf
Concept	ex:green	Green	The primary colour wavelength 500-565nm.	g, 00FF00	ex:colours	inScheme topConceptOf
Concept	ex:blue	Blue	The primary colour wavelength 450-485nm.	b, 0000FF
Concept	ex:pink	Pink	A lighter shade of red.	660000	ex:red	broader
Concept	ex:pink				ex2:rose	closeMatch

which is processed to:

# RDF generated by TVD2RDF Converter v0.5.0b2.
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix ex: <https://example.org/terms#> .
@prefix ex2: <https://example.org/moreterms#> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .

ex:colours a skos:ConceptScheme ;
    dcterms:date "2026-01-16" ;
    dcterms:description "An example concept scheme for some colours." ;
    dcterms:title "Colours" ;
    skos:hasTopConcept ex:blue,
        ex:green,
        ex:red .

ex:blue a skos:Concept ;
    skos:definition "The primary colour wavelength 450-485nm." ;
    skos:notation "b, 0000FF" ;
    skos:prefLabel "Blue" .

ex:green a skos:Concept ;
    skos:definition "The primary colour wavelength 500-565nm." ;
    skos:inScheme ex:colours ;
    skos:notation "g, 00FF00" ;
    skos:prefLabel "Green" ;
    skos:topConceptOf ex:colours .

ex:pink a skos:Concept ;
    skos:broader ex:red ;
    skos:closeMatch ex2:rose ;
    skos:definition "A lighter shade of red." ;
    skos:notation "660000" ;
    skos:prefLabel "Pink" .

ex:red a skos:Concept ;
    skos:definition "The primary colour wavelength 625–750nm." ;
    skos:inScheme ex:colours ;
    skos:notation "FF0000",
        "r" ;
    skos:prefLabel "Red" ;
    skos:topConceptOf ex:colours .