JSON-Studio/README.md

# JSON Studio & MariaDB Workbench

Zwei JSON-Editoren nebeneinander, die komplett im Browser laufen. Gedacht für
den Alltag mit Daten aus Shops, Schnittstellen und Tabellen: importieren,
vergleichen, umformen, wieder ausgeben.

**Live nutzen:** [https://software.obraasch.de/](https://software.obraasch.de/json-workbench/json-workbench.html)

---

## Funktionen

**Import**
JSON · CSV · Excel (xlsx/xls) · YAML (auch mehrere Dokumente) · XML ·
SQL-Dump (liest `INSERT`-Anweisungen zurück) · direkt von einer URL ·
aus einer Datenbank über eine HTTP-Brücke

**Export**
JSON · CSV · Excel · YAML · XML · MariaDB-Skript (`CREATE TABLE` + `INSERT`) ·
JSON-Schema (Draft 2020-12) · an einen Webhook senden · in eine Datenbank schreiben

**Arbeiten mit zwei Dokumenten**
Inhalt hin- und herkopieren · Verschachtelungen auflösen („Flatten“, nötig für
CSV/Excel/Datenbank) · Feld-für-Feld-Vergleich mit Bericht als Markdown oder CSV

**Sonstiges**
Hell- und Dunkelmodus · Snippet-Bibliothek · Tastaturkürzel · integrierte
Anleitung · Sicherung aller Einstellungen als JSON-Datei für den Umzug auf
einen anderen Rechner

---

## Installation

Es genügt, `json-workbench.html` auf einen Webserver zu legen. Die Datei ist
in sich abgeschlossen und braucht keinen Build-Schritt.

### Bibliotheken lokal ablegen (empfohlen)

Ohne lokale Kopien lädt die Anwendung ihre Bibliotheken von einem öffentlichen
CDN. Das funktioniert, überträgt aber die IP-Adressen deiner Nutzerinnen und
Nutzer an einen Dritten — in Deutschland ein datenschutzrechtliches Thema, das
du dir sparen kannst. Lege stattdessen an:

```
json-workbench.html
lib/
  papaparse.min.js
  xlsx.full.min.js
  js-yaml.min.js
  jsoneditor/
    standalone.js
```

Die Quelladressen (mit fest angegebener Version, um unangekündigte Änderungen
zu vermeiden) stehen als Kommentar im Kopf der HTML-Datei. Der JSON-Editor
bringt seine Stile seit Version 3 direkt im Skript mit — eine separate
CSS-Datei ist dafür nicht mehr nötig. Lege die `LICENSE`-Dateien der
Bibliotheken gleich mit in `lib/` ab.

Die Anwendung sucht immer zuerst lokal und geht nur ins Netz, wenn sie dort
nichts findet. Welche Quelle benutzt wurde, zeigt die Anleitung unter
„Offline-Betrieb“ an.

**Wichtig:** Der JSON-Editor ist ein ES-Modul. Browser verbieten das Laden
solcher Module über `file://`. Per Doppelklick geöffnet, holt die Seite den
Editor deshalb weiterhin aus dem Netz. Für echten Offline-Betrieb muss der
Ordner über einen Webserver ausgeliefert werden — `python3 -m http.server`
im Ordner genügt zum Ausprobieren.

---

## Datenbankanbindung (optional)

Ein Browser kann sich nicht direkt mit MariaDB oder MySQL verbinden. Dafür
liegt `db-bridge.php` bei: ein kleines Serverskript, das die Anfragen
entgegennimmt und an die Datenbank weiterreicht.

1. `db-bridge.php` auf den Server legen und im Kopf der Datei Zugangsdaten,
   API-Schlüssel und erlaubte Herkunft eintragen
2. In der Anwendung oben rechts auf das Datenbank-Symbol, Profil anlegen
3. Auf „Testen“ klicken — erscheint die Tabellenliste, steht die Verbindung

### Bitte beachten

- Lege einen **eigenen Datenbankbenutzer** mit genau den nötigen Rechten an.
  Niemals `root` verwenden.
- Betreibe die Brücke **ausschließlich über HTTPS**.
- Die Aktion `query` lässt bewusst nur lesende Abfragen zu. Alle Werte gehen
  über vorbereitete Statements; Tabellennamen werden gegen ein striktes Muster
  geprüft, weil sie sich nicht als Parameter binden lassen.
- Schreibzugriffe lassen sich über `WRITES_ALLOWED` komplett abschalten.
- Der API-Schlüssel wird im Browser-Speicher der Nutzer abgelegt. Behandle ihn
  wie ein Passwort und tausche ihn aus, wenn ein Gerät abhandenkommt.
- Der Schreibmodus „Ersetzen“ führt ein `TRUNCATE` aus und löscht damit alle
  bestehenden Zeilen der Zieltabelle.

---

## Die Übersichtsseite

`index.php` gehört ins Wurzelverzeichnis der Domain und listet automatisch
alle Unterordner auf, die eine Datei `tool.json` enthalten. Ein Ordner ohne
diese Datei taucht nicht auf.

```json
{
  "name": "JSON Studio & MariaDB Workbench",
  "beschreibung": "Kurzbeschreibung in einem Satz.",
  "einstieg": "json-workbench.html",
  "repository": "https://gitea.obraasch.de/oliver/json-studio",
  "repositoryName": "Quellcode (Gitea)",
  "version": "3.0",
  "lizenz": "MIT",
  "stand": "2026-09-16",
  "tags": ["JSON", "CSV", "Excel"],
  "sichtbar": true
}
```

Nur `name` und `einstieg` sind wirklich nötig, alles andere ist optional.
`sichtbar: false` blendet einen Ordner aus, ohne die Datei zu löschen.

Die Seite verarbeitet bewusst **keinerlei Nutzereingaben** — weder `$_GET`
noch `$_POST` noch Cookies. Damit entfällt die übliche Angriffsfläche. Inhalte
aus `tool.json` werden trotzdem geprüft und beim Ausgeben vollständig maskiert;
Pfade dürfen den Tool-Ordner nicht verlassen, externe Links nur `http`/`https`
sein. Die Seite kommt ohne JavaScript aus, entsprechend verbietet die
Content-Security-Policy Skripte komplett.

---

## Rechtliches beim öffentlichen Betrieb

In Deutschland brauchst du für ein öffentlich erreichbares Angebot ein
Impressum (§ 5 DDG) und eine Datenschutzerklärung. Vorlagen liegen als
`impressum.html` und `datenschutz.html` bei — mit Platzhaltern, die vor der
Veröffentlichung ausgefüllt werden müssen. Die Vorlagen sind nach bestem
Wissen erstellt, ersetzen aber keine Rechtsberatung.

---

## Lizenz

Dieses Projekt steht unter der MIT-Lizenz, siehe [LICENSE](LICENSE).

Eingebundene Bibliotheken und ihre Lizenzen:

| Bibliothek | Lizenz | Projekt |
|---|---|---|
| vanilla-jsoneditor | ISC | https://github.com/josdejong/svelte-jsoneditor |
| PapaParse | MIT | https://github.com/mholt/PapaParse |
| js-yaml | MIT | https://github.com/nodeca/js-yaml |
| SheetJS (xlsx) | Apache-2.0 | https://github.com/SheetJS/sheetjs |

SheetJS steht unter Apache-2.0. Bei Weitergabe muss der Lizenztext beiliegen
und es müssen Änderungen an den Dateien kenntlich gemacht werden — am
einfachsten, indem du die unveränderte Datei samt ihrer `LICENSE` in `lib/`
ablegst.