← Semantechs home The tarka Manual EPUBA4 PDFGitHub
Contents
  1. Introduction

Part I — Setting out

  1. 1What tarka does
  2. 2Installing
  3. 3The Bookshop Trail

Part II — TARQL

  1. 4A first mapping
  2. 5TARQL in depth

Part III — OTTR

  1. 6Templates
  2. 7OTTR over tables
  3. 8bOTTR

Part IV — Data frames

  1. 9Python and Polars

Part V — Checking the transformation

  1. 10Shapes and SHACL
  2. 11SPARQL checks
  3. 12The Ontology Quality Suite

Part VI — In production

  1. 13Into a store
  2. 14A pipeline

Appendices

  1. ACommand reference
  2. BPython reference
  3. CDifferences
  4. DTroubleshooting
  5. EThe example files

Appendix E. The example files

Everything in manual/examples/bookshop-trail/, and the chapter that uses it. Each file name links to the file as it is on tarka's main branch: it opens in the browser, and the browser saves it. To have them all, browse the folder on GitHub, or download tarka as a ZIP and look in manual/examples/bookshop-trail/.

The open links load a file into the Turtle Editor Viewer, as the Semantechs courses load theirs, so it can be read as a diagram, queried and validated in the browser, with nothing to install. Shapes open in a tab of their own, beside the courses' whole trail in one file, and already chosen for validation: press Validate, and the editor reports what is written beside the link. A query opens the editor with the trail loaded: paste the query into the SPARQL panel and press Execute Query. The trail is the course's graph, which tarka's mappings reproduce, so a check finds in it what it finds in their output.

reference/

Copied unchanged from the Semantechs courses, which are MIT-licensed by the same author. Files 04 and 06 to 09 are the course's graph, which the spreadsheets were written from and the mappings must reproduce.

File What it is Chapters In the editor
01-vocabulary.ttl the Bookshop Trail ontology (OWL 2 DL) 3, 12 open
02-genres.ttl reference data: the genres 10, 11, 12 open
03-places.ttl reference data: the places 10, 11, 12 open
04-bookshops.ttl the course's graph: the bookshops 3, 11 open
05-people.ttl reference data: the authors and publishers 10, 11, 12 open
06-books.ttl the course's graph: works, translations and series 3, 11 open
07-events.ttl the course's graph: the events 3, 11 open
08-trail.ttl the course's graph: the trail's segments 3, 11 open
09-stock.ttl the course's graph: the stock records 3, 11 open
s64-the-whole-trail-in-one-shapes-graph.ttl the SHACL course's shapes for the whole trail 10 open: six warnings, no violations
q01-every-bookshop-on-the-trail.rq the SPARQL course's first query 11 open the trail
NOTICE.md where these files come from, and their licence 3

data/

The spreadsheets and the prepared tables. The Parquet file downloads; the rest are text.

File Rows Chapters
bookshops.csv, events.csv, works.csv, stock.csv, segments.csv the committee's spreadsheets, written by tools/make-spreadsheets.py 3 to 5
faulty/bookshops.csv bookshops.csv with five mistakes 10, 11
prepared/bookshops.csv, prepared/segments.csv tables for the bOTTR maps, written by python/prepare.py 8, 9
prepared/shop-stock.csv, prepared/shop-stock.parquet each shop's stock as four lists, for tt:ShopStock 7, 9

Mappings

The TARQL queries run over a table's rows, not over a graph, so they are for reading here; a bOTTR map is Turtle, and opens as one.

File What it maps Chapter
tarql/bookshops-first.rq shops: name and town 4
tarql/bookshops.rq shops, in full, with their points 4
tarql/stocks.rq the titles a shop stocks, with apf:strSplit 5
tarql/stocks-split.rq the same, for --split 5
tarql/stock.rq stock records 5
tarql/events.rq events: UK dates, pound signs 5
tarql/works.rq works: optional columns, translations, tagged titles 5
tarql/functions-tour.rq a guide to the trail, through Jena's, XPath's, SPIN's and GeoSPARQL's functions 5
ottr/base.stottr tt:Geometry, tt:Named 6
ottr/trail.stottr tt:Bookshop, tt:Stocks, tt:StockRecord, tt:Segment, tt:Connects 6
ottr/rows.stottr tt:ShopStock, with cross and zipMin 6, 7
ottr-mistakes/events.stottr a draft with five lint errors and a warning 6
instances/two-rivers.stottr a new shop, written by hand 7
bottr/bookshops.bottr.ttl shops, through tt:Bookshop (open) 8
bottr/segments.bottr.ttl trail segments, through tt:Segment (open) 8
bottr/connections.bottr.ttl bs:connectsTo, from the segments' RDF (open) 8
bottr/connections-endpoint.bottr.ttl the same, from a store's SPARQL endpoint (open) 13

Checks

File What it checks Chapter In the editor
shapes/trail-extra.ttl events, stock records, a shop's answers and its year 10 open: conforms
sparql/counts.rq how many of each class 11 open the trail
sparql/cross-file-checks.rq disagreements between files, unknown towns 11 open the trail
sparql/every-shop-answers.rq an ASK for shops that skip a yes/no question 11 open the trail

Scripts

File Does Chapter
tools/make-spreadsheets.py writes data/*.csv from the course's graph 3
python/prepare.py prepares the tables for OTTR and bOTTR, with Polars 9
python/frames.py maps a frame and a Parquet file from Python 9
python/validate.py validates with the mapping's shapes (SHACL_Engine) and with s64 and the reference data (HOLOS) 10
tools/sparql.py runs a query over files and the reference data; --expect-none makes a gate of it 11
tools/compare.py compares what tarka made with the course's graph, value for value 11
pipeline/trail.yml the whole transformation as a GitHub Actions workflow 14
check.py runs every example in the manual, in order, and checks each result 2

check.py needs tarka on the PATH (or TARKA=path/to/tarka) and the Python packages tarka-rdf, polars, holosdb and shacl. Set TARKA_EXAMPLES_OUT to keep the output on another drive, and HOLOS_SERVER=path/to/holos-server to run Chapter 13's store steps too. On this edition's machine, it runs 39 checks.