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.