staticat 0.0.3

Generate static open data catalogs according to the DCAT-AP.de standard

Staticat

Mit Staticat können Sie statische Open-Data-Kataloge nach dem DCAT-AP.de-Standard direkt auf Ihrem Rechner generieren. Dazu müssen Sie nur die Dateien, die Sie veröffentlichen möchten, in einem Ordner sammeln und mit einigen wenigen Metadaten im TOML-Format anreichern. Nachdem Sie Staticat ausgeführt haben, können Sie den Ordner anschließend auf einen einfachen Webserver hochladen. MySQL, PHP usw. werden dabei nicht benötigt.

English summary: With Staticat, you can generate static open data catalogs according to the DCAT-AP.de standard right on your computer. All you need to do is collect the files you want to publish in a folder and enrich them with some metadata using the TOML format. After executing Staticat, you can then upload the folder to a simple web server. MySQL, PHP etc. are not required.

Installation

Staticat kann als portables Programm verwendet werden. Laden Sie dazu einfach die neueste Version für Windows herunter und entpacken Sie das ZIP-Archiv.

Alternativ, falls Sie bereits Python auf Ihrem Rechner installiert haben, können Sie Staticat auch mit dem Kommando pip install staticat installieren. Die Installation mit pip funktioniert auch auf macOS und Linux.

Benutzung

Um einen neuen Open-Data-Katalog aufzubauen, können Sie mit dem Open-Data-Ordner starten, der als Beispiel mit Staticat ausgeliefert wird. Sie finden den Ordner auch auf GitHub. Der Open-Data-Ordner folgt dem Schema: ein Verzeichnis pro Datensatz, eine oder mehrere Distributionen, also Dateien, pro Datensatz. Datensätze können dabei in beliebiger Verschachtelung und Tiefe angelegt werden.

Führen Sie nun folgende Schritte aus:

1. Passen Sie die Metadaten für den gesamten Katalog in der Datei catalog.toml an.
2. Ersetzen und ergänzen Sie die Beispieldatensätze nach und nach mit "echten" Datensätzen. Dazu bearbeiten Sie zunächst die Metadaten für den jeweiligen Datensatz in der Datei dataset.toml und legen dann die Dateien, die Sie dem Datensatz zuordnen möchten, im selben Verzeichnis ab.
3. Nachdem Sie Staticat ausgeführt haben, laden Sie den Open-Data-Ordner auf einen Webserver hoch.

Im Folgenden wird die Funktionsweise von Staticat etwas detaillierter beschrieben. Betrachten Sie dazu zum Beispiel diesen Open-Data-Ordner:

$ tree opendata
opendata                   ← Open-Data-Ordner
├── catalog.toml           ← Metadatenbeschreibung des Katalogs
└── example                ← Datensatz
    ├── dataset.toml       ← Metadatenbeschreibung des Datensatzes
    └── distribution.xlsx  ← Distribution

2 directories, 3 files

Nach dem DCAT-AP.de-Standard fasst ein Katalog mehrere Datensätze und ein Datensatz mehrere Distributionen, also in der Regel Dateien, zusammen. Dabei müssen sowohl der Katalog als auch die Datensätze mit einigen grundlegenden Metadaten ausgezeichnet werden. Dies geschieht über die Dateien catalog.toml (Beispieldatei, Details) und dataset.toml (Beispieldatei, Details).

Wenn Sie nun Staticat ausführen, legt das Programm einige zusätzliche Dateien an:

$ tree opendata
opendata
├── catalog.toml
├── catalog.ttl            ← Katalog im Turtle-Format
├── default.css            ← Stylesheet für die Websites
├── index.html             ← Website des Katalogs
└── example
    ├── dataset.toml
    ├── distribution.csv   ← Distribution im CSV-Format
    ├── distribution.xlsx
    └── index.html         ← Website des Datensatzes

2 directories, 8 files

Excel-Dateien werden von Staticat standardmäßig ins CSV-Format umgewandelt. Das CSV-Format ist im Gegensatz zu den Formaten XLS und XLSX offen und nicht-proprietär und daher besser für Open-Data-Veröffentlichungen geeignet. Dieses Verhalten lässt sich über die Konfigurationsdateien pro Datensatz anpassen.

Die Datei catalog.ttl beschreibt den Katalog im maschinenlesbaren Turtle-Format und kann durch andere Open-Data-Portale "geharvestet", also eingelesen, werden. Wenn Sie Ihren Katalog harvesten lassen, können Ihre veröffentlichten Dateien zum Beispiel auch über das Open-Data-Portal Ihres Landes oder über GovData gefunden werden.

Die Websites des Katalogs und der Datensätze bieten eine einfache, für Menschen lesbare Ansicht der veröffentlichten Dateien. Vorrangig ist der von Staticat erstellte Katalog aber für das Harvesting durch übergeordnete Open-Data-Portale gedacht.

Screenshots

Eine Online-Demo finden Sie unter hriebl.github.io/staticat. Folgende Screenshots vermitteln außerdem einen ersten visuellen Eindruck von Staticat:

Katalog	Datensatz

Konfigurationsdateien

config.toml

Die Datei config.toml muss im selben Verzeichnis wie das portable Programm staticat.exe liegen. Falls Sie Staticat mit pip installiert haben, also nicht die portable Version verwenden, nutzen Sie bitte die entsprechenden Kommandozeilenargumente anstatt der Datei config.toml.

Beispieldatei: portable/config.toml.

Folgende Schlüssel sind zulässig:

Schlüssel	Typ	Beschreibung
directory	String	Basisverzeichnis des lokalen Open-Data-Ordners
catalog_template	String (optional)	Pfad zum Jinja-Template für die HTML-Darstellung des Katalogs
dataset_template	String (optional)	Pfad zum Jinja-Template für die HTML-Darstellung der Datensätze
convert_excel	Boolean (optional)	Ob Excel zu CSV umgewandelt wird (für alle Datensätze)

catalog.toml

Die Datei catalog.toml muss im Basisverzeichnis des Open-Data-Ordners liegen.

Beispieldatei: opendata/catalog.toml.

Folgende Schlüssel sind zulässig:

Schlüssel	Typ	RDF / Beschreibung
uri	String	Basis-URL des Open-Data-Katalogs im Internet
title	String	dct:title
description	String	dct:description
[publisher]	Table	dct:publisher
name	String	foaf:name
uri	String	URI des Publishers
[dataset_defaults]	Table (optional)	Standardmetadaten (für alle Datensätze)
...	...	Siehe dataset.toml

dataset.toml

Jedes Verzeichnis im Open-Data-Ordner mit einer Datei dataset.toml wird von Staticat als Datensatz verarbeitet und zum Katalog hinzugefügt. Sollten Unklarheiten hinsichtlich der Bedeutung eines Schlüssel bestehen, können Sie das entsprechende RDF-Prädikat nachschlagen oder die HTML-Darstellung des Datensatzes zu Rate ziehen.

Beispieldatei: opendata/example/dataset.toml.

Folgende Schlüssel sind zulässig:

Schlüssel	Typ	Werte / Format	RDF / Beschreibung
title	String		dct:title
description	String		dct:description
keywords	Array mit Strings		dcat:keyword
themes	Array mit Strings	1 (nur Code)	dcat:theme
issued	Datum	JJJJ-MM-TT	dct:issued
start_date	Datum	JJJJ-MM-TT	dct:temporal//dcat:startDate
end_date	Datum	JJJJ-MM-TT	dct:temporal//dcat:endDate
license	String	2 (nur Code)	dct:license
availability	String	3 (nur Code)	dcatap:availability
spatial	String	4, 5, 6, 7 (komplette URI)	dct:spatial
political_geocoding	String	8, 9, 10, 11, 12, 13 (komplette URI)	dcatde:politicalGeocodingURI dcatde:politicalGeocodingLevelURI
[maintainer]	Table		dcatde:maintainer dcat:contactPoint
name	String		foaf:name vcard:fn
email	String		foaf:mbox vcard:hasEmail
[creator]	Table		dct:creator
name	String		foaf:name
email	String		foaf:mbox
[publisher]	Table		dct:publisher
name	String		foaf:name
uri	String		URI des Publishers
[config]	Table (optional)		Staticat-Einstellungen (für diesen Datensatz)
convert_excel	Boolean (optional)		Ob Excel zu CSV umgewandelt wird

Falls Sie eine Online-Ressource als Distribution zu einem Datensatz hinzufügen möchten, die nicht als Datei auf Ihrem Rechner vorliegt, können Sie diese ebenfalls in der Datei dataset.toml hinterlegen. Dazu müssen Sie lediglich ein Array [[distributions]] mit mindestens den beiden Schlüsseln uri und title zur Datei dataset.toml hinzufügen.

Beispieldatei: opendata/online/dataset.toml.

Folgende Schlüssel sind zulässig:

Schlüssel	Typ	Werte / Format	RDF / Beschreibung
[[distributions]]	Array		dcat:distribution
uri	String		URI der Distribution dcat:accessURL
title	String		dct:title
modified	Datum (optional)	JJJJ-MM-TT	dct:modified
format	String (optional)	14 (nur Code)	dct:format
media_type	String (optional)	MIME-Type	dcat:mediaType
byte_size	Float (optional)		dcat:byteSize

Kommandozeilenargumente

Falls Sie Staticat mit pip installiert haben, also nicht die portable Version verwenden, können Sie folgende Kommandozeilenargumente anstelle der Datei config.toml verwenden. Die portable Version unterstützt diese Argumente nicht:

$ staticat -h
usage: staticat [-h] [-c CATALOG_TEMPLATE] [-d DATASET_TEMPLATE] [-e] directory

positional arguments:
  directory             the base directory of the local open data folder

options:
  -h, --help            show this help message and exit
  -c CATALOG_TEMPLATE, --catalog-template CATALOG_TEMPLATE
                        the path of the Jinja template for the HTML view of the catalog
  -d DATASET_TEMPLATE, --dataset-template DATASET_TEMPLATE
                        the path of the Jinja template for the HTML view of the datasets
  -e, --excel           do not convert Excel distributions to CSV. can be overridden in
                        dataset.toml