Open Data App Spezifikationen

Eine Open Data App (ODA) ist eine nützliche Web-App, die Daten aus einem Open Data Portal bezieht und damit interagiert, beispielsweise durch Visualisierung.

ODAs ermöglichen den einfachen visuellen Zugang zu öffentlichen Daten und fördern Open Data Sichtbarkeit, Transparenz und Innovation.

Eine ODA kann in einem Open Data App Store (ODAS) veröffentlicht werden.

Vorbemerkung

In diesem Dokument wird soll, muss, darf und kann verwendet und das ist auch genauso gemeint!

Architektur einer ODA

Eine ODA …

Die ODA ist grundsätzlich serverless.

Funktion einer ODA

Die Datei app_package.json

Die Datei app_package.json liegt im Root Verzeichnis der ODA.

In der Datei sind alle Metadaten zur App (Lizenz, Version, Konfiguration,…) enthalten.

Die Datei /app_package.json muss folgende Top-Level Elemente enthalten:

Multiline-Strings in app_package.json

Wenn längerer Text in einem Wert enthalten sein soll, kann dieser als “Multiline-String” definiert werden.

Jeder Wert inder app_package.json, der ein Array von Strings ist und der erste String ein “multiline” ist, wird als Multiline-String interpretiert.

Beispiel für einen Wert, der als Multiline-String definiert ist:

{
  ...
  "mehrzeiliger-string": [
    "_multiline_",
    "erste zeile ",
    "zweite Zeile\n",
    "dritte Zeile"
  ],
  ...
}

Dieser Wert wird im ODAS interpretiert als:

  "mehrzeiliger-string":"erste zeile zweite Zeile\ndritte Zeile"

Ein vollständiges Beispiel für ein app_packages ist unten dargestellt.

ODA-Assets

ODA-Assets sind statische Dateien, die von der App benötigt werden, z.B. CSS-Dateien, Icons, …

Die ODA-Assets sind im Verzeichnis /assets zu speichern.

Folgende Dateinamen ist nicht zulässig:

ODA Styling

ODA sollten gleiche CSS-grundlagen verwenden. Im ODAS kann der ODP-Portalbetreiber ein eigenes CSS hinterlegen und damit das Corporate Design so anpassen, dass es nach dem Betreiber, der Stadt oder dem Open Data Portal aussieht.

Ein Beipiel für ein ODA-CSS ist hier zu finden: https://github.com/open-data-apps/oda-generic/blob/master/app/app-base.css

Aufbau der instanz-config

Die instanz-config definiert, wie das Formular zur Bearbeitung der Konfiguration durch den Open Data Portalbetreiber aufgebaut ist (siehe unten).

Es wird jedes Feld des Konfigurationsformulars für diese ODA einzeln spezifiert. Der App-Entwickler legt die Felder selber fest, die zur Konfiguration der App benötigt werden.

Aufbau der instanz-config:

Der Key (z.B. titel) muss eindeutig sein.

Feld-Angaben:

Beispiel für instanz-config:

  "instanz-config": {
    "titel": {
      "label": "Titel",
      "hilfe": "Der Titel wird in der Titelzeile der App angezeigt",
      "default": "Generic Open Data App",
      "format": {
        "typ": "string",
        "laenge": 50
      },
      "erforderlich": "ja"
    },
    "icon": {
      "label": "App-Icon",
      "hilfe": "Das Icon wird links oben in der Titelzeile angezeigt",
      "format": {
        "typ": "image",
        "hoehe": 100,
        "breite": 300
      },
      "erforderlich": "ja"
    },
    "kontakt": {
      "label": "Kontakt",
      "hilfe": "Der Text wird im Menüpunkt 'Kontakt' anzeigt",
      "format": {
        "typ": "markdown"
      },
      "default": [
        "_multiline_",
        "Bei Fragen zur App wenden Sie sich bitte an: ",
        "Tel.: <a href='tel:'></a>",
        "Fax: <a href='tel:'></a>",
        "E-Mail: <a href='mailto:'></a>"
      ],
      "erforderlich": "ja"
    },

Veröffentlichung einer ODA im ODAS

Eine ODA muss eine Datei /app_package.json haben. In der sind alle Metadaten zur App (Lizenz, Version, Konfiguration,…) enthalten.

Die Datei /app_package.json

Die in der ODA enthaltenen statischen Dateien sollten im Verzeichnis /assets liegen.

Vollständiges Beispiel einer app_package.json

{
  "app-entwickler-id": "12343",
  "app-entwickler-name": "ondics-gmbh",
  "name-in-url": "generic",
  "name": "Generic Open Data App",
  "version": "1.0.0",
  "odas-app-icon": "assets/odas-app-icon.png",
  "app-icon": "assets/app-icon.png",
  "kurzbeschreibung": "Diese Open Data App ist Anschauungsobjekt und Musterbeispiel für weitere Apps.",
  "beschreibung": [
    "_multiline_",
    "Die Open Data App ist Musterbeispiel für weitere Apps. Inhaltlich macht sie ",
    "fast nichts, sondern zeigt nur die Config Daten an. ",
    "Die Daten werden aus einem Open Data Portal bezogen. ",
    ""
  ],
  "screenshots": [
    "Desktop_Screenshot.png",
    "Mobile_Screenshot.png"
  ],
  "api-version": "1",
  "instanz-config": {
    "seitentitel": {
      "label": "Seitentitel",
      "hilfe": "Der Seitentitel wird im Browser-Tab der App angezeigt",
      "default": "Generic ODA",
      "format": {
        "typ": "string",
        "laenge": 50
      },
      "erforderlich": "ja"
    },
    "lizenz": {
      "label": "Lizenz",
      "hilfe": "Angabe der Lizenz, die für die Nutzung der App gilt.",
      "default": "Open Software License (OSL)",
      "format": {
        "typ": "string",
        "laenge": 50
      },
      "erforderlich": "ja"
    },
    "titel": {
      "label": "Titel",
      "hilfe": "Der Titel wird in der Titelzeile der App angezeigt",
      "default": "Generic Open Data App",
      "format": {
        "typ": "string",
        "laenge": 50
      },
      "erforderlich": "ja"
    },
    "icon": {
      "label": "App-Icon",
      "hilfe": "Das Icon wird links oben in der Titelzeile angezeigt",
      "format": {
        "typ": "image",
        "hoehe": 100,
        "breite": 300
      },
      "erforderlich": "ja"
    },
    "kontakt": {
      "label": "Kontakt",
      "hilfe": "Der Text wird im Menüpunkt 'Kontakt' anzeigt",
      "format": {
        "typ": "markdown"
      },
      "default": [
        "_multiline_",
        "Bei Fragen zur App wenden Sie sich bitte an: ",
        "Tel.: <a href='tel:'></a>",
        "Fax: <a href='tel:'></a>",
        "E-Mail: <a href='mailto:'></a>"
      ],
      "erforderlich": "ja"
    },
    "beschreibung": {
      "label": "Beschreibung",
      "hilfe": "Der Text wird im Menüpunkt 'Über diese App' anzeigt",
      "format": {
        "typ": "markdown"
      },
      "default": [
        "_multiline_",
        "Die Generic-App zeigt die jeweils definierten Configs.",
        "Die Daten werden tagesaktuell gehalten. Bei Änderungen versuchen wir, ",
        "den Datenbestend immer sofort zu aktualisieren.\n ",
        "## App-Anbieter",
        "Die App wird bereit gestellt von <a href=\"\"><>",
        "## Daten",
        "Die Daten kommen aus  unserem Open Data Portal <a href=\"\"><>",
        "Die Datenquelle ist in unserem Open Data Portal <a href=\"\"><>.",
        "## App-Entwickler",
        "Die App wurde entwickelt von <a href=\"\"><>. App-Version: .",
        "## Open Data App Store",
        "Der Open Data App Store betrieben von <a href=\"\"><>\""
      ],
      "erforderlich": "ja"
    },
    "impressum": {
      "label": "Impressum",
      "hilfe": "Der Text wird im Menüpunkt 'Impressum' anzeigt",
      "format": {
        "typ": "markdown"
      },
      "default": [
        "_multiline_",
        "",
        "",
        "",
        "",
        "Telefon: ",
        "Website: <a href='' target='_blank'></a>"
      ],
      "erforderlich": "ja"
    },
    "datenschutz": {
      "label": "Datenschutz",
      "hilfe": "Der Text wird im Menüpunkt 'Datenschutz' anzeigt",
      "format": {
        "typ": "markdown"
      },
      "default": "Alle Daten sind geschützt.",
      "erforderlich": "ja"
    },
    "urlDaten": {
      "label": "URL zum Datensatz im ODP",
      "hilfe": "Der Datensatz im Open Data Portal mit den Daten der Generic App",
      "format": {
        "typ": "url"
      },
      "default": "",
      "beispiel": "",
      "erforderlich": "ja"
    },
    "fusszeile": {
      "label": "Fußzeile",
      "hilfe": "Wird auf der Website unten in der Fusszeile angezeigt.",
      "format": {
        "typ": "String",
        "laenge": 50
      },
      "default": "(C) Copyright  | App & Daten:  | App-Entwickler:  | ODAS: ",
      "erforderlich": "ja"
    },
    "apiUrl": {
      "label": "URL zur Datensatz-API",
      "hilfe": "Von dieser API-URL zum Datensatz werden die Ressoucen bezogen",
      "format": {
        "typ": "url"
      },
      "default": "",
      "beispiel": "",
      "erforderlich": "ja"
    },
    "sprache": {
      "label": "Sprache der App",
      "hilfe": "Angabe der App-Sprache",
      "format": {
        "typ": "dropdown",
        "optionen": ["de"],
        "default": "de"
      },
      "erforderlich": "ja"
    }
  }
}

Entwicklung einer ODA

Systemvoraussetzungen (empfohlen):

Die Entwicklung kann mit der odas-app-generic begonnen werden. Zunächst wird das Repo gecloned:

$ git clone ...

Jetzt bauen wird das Image mit dem Webserver Nginx:

$ make build

Und starten den Conatiner (derTCP/IP-Port kann in docker-compose.yml geändert werden).

$ make up

Die ODA steht dann unter http://localhost:8090 zur Verfügung.

Die App kann wieder gestoppt werden mit

$ make down

Um eine ODA auszuliefern und in den ODAS einzustellen, wird die zip-Datei ersellt:

$ make zip

Folgende Dateien müssen dazu vorhanden sein:

odas-app-beispiel/
├── app/
│ ├── index.html
│ ├── app-base.css
│ ├── app.css
│ ├── app-base.js
│ ├── app.js
│ ├── logo.png
│ └── favicon.png
├── assets/
│ ├── Desktop_Screenshot.png
│ ├── Mobile_Screenshot.png
├── Changelog.md
└── app-package.json

Der Ordner “app” sowie der Ordner “assets” dürfen beliebig viele Dateien enthalten.

Beispiel App Prompt

Prompt:

agiere als softwareentwickler für eine web-app.

die technischen rahmenbedingungen der app sind folgende;

die app soll folendes tun:

aufgabe: Erstelle die app. fülle dazu die funktion app() {} und ggf. addToHead() {}

hier ist der code-template:

/\*

- Diese Funktion ist für die Inhalte der Startseite
- zuständig.
-
- Der umschließebde HTML code ist:
-      <body>
-      <div class="container mt-4" id="main-content">
-          ...
-      </div>
-      </body>
- Als CSS Framnework wird Bootstrap 5.3 verwendet.
-
- ConfigData ist ein JSON enthält die Referenz
- auf die Daten im CKAN Open Data Portal:
-     {
-         "apiurl": "https://open-data-musterstadt.ckan.de/dataset/db92da8e40f9/download/formular_multitemplate.json"
-     }
-
- @param {Object} configdata - Alle Konfigurationsdaten der App
- @enclosingHtmlDivElement - HTML Knoten des umschließenden Tags
- @returns {string | NULL} - darzustellendes HTML oder NULL wenn HTML Knoten direkt manipuliert wurde
  \*/

function app(configdata = [], enclosingHtmlDivElement) {
// hier muss der app-code stehen
}

/\*

- Diese Funktion kann Bibliotheken und benötigte Skripte laden.

- @returns {string} - HTML mit script, link, etc. Tags
  \*/
  function addToHead() {
  }

Offene Punkte

Autor und Kontakt

Kontakt: info@ondics.de

Website: ondics.de

(C) 2025 Ondics GmbH

zurück zum Index