emacs-ottr-toolkit

Johan W. Klüwer

OTTR user forum, 2021-06-18

1. Easily create an OTTR template library

  • set up a library document using GNU Emacs org-mode
  • write templates in stOTTR format
  • find errors with flycheck and Lutra lint
  • create test data in tables
  • generate bOTTR to map data to templates
  • expand and inspect results
  • prepare for publishing as linked data

2. Emacs?

Original author(s) David A. Moon, Guy L. Steele Jr.
Developer(s) Various free/libre software developers, including volunteers and commercial developers
Initial release 1976; 45 years ago
Written in Lisp, C
Current release GNU Emacs 27.1

3. How to get it

https://gitlab.com/ottr/pub/emacs-ottr-toolkit

Package dependencies for installation – coming soon!

4. Toolkit components

  • Boilerplate snippets
  • Emacs-Lisp functions
  • org-babel executable blocks

5. Snippets

6. Start a new library

6.1. Prefixes

7. Add snippets

  • template
  • annotations
  • data for testing
  • bOTTR maps

7.1. A template

*** o-rdf:Type
The template:
#+name: Type
#+header: :var annotations=(ottr-annotations-str "o-rdf:Type" "annotations-Type")
#+begin_src stottr 
o-rdf:Type [ 
    ottr:IRI ?resource, 
    ottr:IRI ?class
 ]
#annotations
:: {
ottr:Triple(?resource, rdf:type, ?class)
} .
#+end_src

7.2. Annotations

#+name: annotations-Statement
 - Provenance
     1. ?created ! dateTime  :: 2020-08-21T00:00:00Z
     2. ?updated ?! dateTime  :: 
     3. ?authors NEList<IRI>  :: <http://folk.uio.no/martige/foaf.rdf#me>  
     4. ?contributors ? NEList<IRI>  :: 
 - Version
     1. ?status ! IRI :: ottr:draft
     2. ?version ! string :: "0.1.1"
     3. ?previousVersion !? IRI :: 
     4. ?nextVersion !? IRI :: 

7.3. Test data

# Execute the call with C-c C-c to insert blank table for template.
#+name: Type-data-table
#+call: template-data-table( template="Type" ) :cache yes

#+RESULTS[ebb5da10fd21e1c605cb8518a6728d8e6b1ab1ee]: Type-data-table
| resource   | class     |
|------------+-----------|
| ex:Lucille | ex:Guitar |
| ex:Lucille | ex:Black  |

7.4. bOTTR map

# Execute the call with C-c C-c, then tangle the resulting bottr block to file with C-u C-c C-v t.
#+call: bottr-test-map( table=Type-data-table, file="Type-data-table.csv", template="Type" )

#+RESULTS:

#+begin_src ttl :tangle ./bottr/Type_Type-data-table.bottr
<<stottr-prefixes>>
[] a ottr:InstanceMap ; ottr:source [ a ottr:H2Source ] ; ottr:query """
select resource, class
from csvread( './data/Type-data-table.csv' )
""" ;
ottr:template o-rdf:Type ;
ottr:argumentMaps (
  [ ottr:type ottr:IRI ] #  ?resource
  [ ottr:type ottr:IRI ] #  ?class
) .
#+end_src

8. Expand examples

# Execute this call to run the bOTTR map:
#+call: expand-bottr(bottr="./bottr/Type_Type-data-table.bottr")

#+RESULTS:
#+begin_SRC ttl
@prefix ex:    <http://example.org/> .
@prefix rdf:   <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

ex:Lucille  a   ex:Black , ex:Guitar .

#+end_SRC

9. Edit with syntax checking

https://gitlab.com/ottr/pub/emacs-stottr-mode

10. Template index

Find templates across stOTTR buffers.

11. Prepare for publishing

Easily run Lutra within your buffer

  • lint finds problems in library
  • docTTR builds library web pages
  • expand library for .stottr, .ttl files

11.1. Lint

* Library lint                                                     :noexport:
#+call: lint-stottr()

#+RESULTS:
#+begin_src org

  - ERROR ::  Type error in template http://w3id.org/requirement-ontology/tpl/0.1/IntersectionGCI: incompatible argument and parameter type.
    The template contains a value ?intersection : ottr:IRI which has the type ottr:IRI and which is used as argument to a parameter with the incompatible type NEList<ottr:IRI> in instance http://tpl.ottr.xyz/owl/restriction/0.1/ObjectIntersectionOf
    (?gci : owl:Class, ?intersection : ottr:IRI) 
    (arg no. 2).
#+end_src

11.2. docTTR

* docTTR HTML pages                                                :noexport:
# Execute this call with C-c C-c to generate docTTR HTML pages:
#+call: write-docttr()

#+RESULTS:
#+begin_example
Wrote http://tpl.ottr.xyz/owl/axiom/0.1/SubClassOf to docttr\tpl.ottr.xyz\owl\axiom\0.1\SubClassOf.html
Wrote http://w3id.org/requirement-ontology/tpl/0.1/Requirement to docttr\w3id.org\requirement-ontology\tpl\0.1\Requirement.html
Wrote http://w3id.org/requirement-ontology/tpl/0.1/Requirement_SCD to docttr\w3id.org\requirement-ontology\tpl\0.1\Requirement_SCD.html
[...]
Wrote index files to docttr\w3id.org
Wrote index files to docttr\w3id.org\requirement-ontology
Wrote index files to docttr\w3id.org\requirement-ontology\tpl
Wrote index files to docttr\w3id.org\requirement-ontology\tpl\0.1
#+end_example  

11.3. Write .stottr, .ttl

* expand library, for web publishing                               :noexport:
#+call: expand-library()

#+RESULTS:

12. The outcome

  • Snippets reduce typing
  • Single file
  • Easy template annotations
  • Test with data
  • Run Lutra
  • Write documentation