Getting Started
===============

.. contents::

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:

.. code-block:: console

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

It is recommended to use a virtual environment for TVD2RDF:

.. code-block:: console

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

Install and check version:

.. code-block:: console

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

Optional: install dependencies used in development only:

.. code-block:: console

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

.. code-block:: console

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

.. code-block:: console

    (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.

.. csv-table:: 
    :header-rows: 1
    :file: ../samples/terms.csv

which is processed to

.. literalinclude:: ../samples/terms.ttl
    :linenos:
    :language: turtle

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

.. csv-table::
    :header-rows: 1
    :file: ../samples/concepts.csv

which is processed to:

.. literalinclude:: ../samples/concepts.ttl
    :linenos:
    :language: turtle