app.json-Referenz

app.json beschreibt eine gehostete App vollständig: welche Bausteine sie zeigt, woher die Daten kommen, was bei einem Klick passiert. Der Builder schreibt diese Datei, im Bereich Code kannst du sie direkt bearbeiten. Beides ist gleichwertig – der Builder kann alles, was die Datei kann.

Diese Referenz entsteht aus der Runtime selbst (@methacore/runtime, Schema-Version 1). Das JSON-Schema liegt unter https://methacore.de/schemas/apps/app/v1.json; mit "$schema" bekommst du in jedem Editor Autovervollständigung.

Aufbau

{
  "$schema": "https://methacore.de/schemas/apps/app/v1.json",
  "schemaVersion": 1,
  "name": "Pinnwand",
  "auth": { "clientId": "cl_7d2e41a9", "scopes": ["mc.apps.storage:read", "mc.apps.storage:write"] },
  "initialState": { "entwurf": "" },
  "root": { "id": "root", "type": "Stack", "children": [] }
}

Knoten

Jeder Baustein ist ein Knoten:

{
  "id": "speichern",
  "type": "Button",
  "props": { "label": "Speichern", "variant": "filled" },
  "bind": [],
  "on": { "click": [{ "type": "toast", "message": "Gespeichert" }] },
  "children": []
}

Zusätzliche Felder am Knoten sind nicht erlaubt; die Runtime meldet einen Fehler, statt sie still zu ignorieren.

Bausteine

Zwei Eigenschaften hat jeder Baustein:

Stack – Stapel

Das load-Ereignis wirkt nur am Wurzelknoten. label braucht ein Stapel nur als Kind von Tabs.

Grid – Raster

Mit minWidth bricht das Raster von selbst um; sonst gilt columns (1–12).

Card – Karte

label braucht eine Karte nur als Kind von Tabs.

Tabs – Tabs

Jedes Kind ist ein Tab; sein props.label ist die Beschriftung und Pflicht. change liefert { value: <Index> }.

Heading – Überschrift

Text – Text

Image – Bild

Geladen werden nur Adressen mit https: oder data:image/.

Button – Button

Die Klasse ist .mc-button--primary für gefüllte, .mc-button--secondary für helle, umrandete und dezente Knöpfe.

TextInput – Textfeld

change kommt bei jeder Eingabe mit { value }, submit bei Enter. Mit type: "number" landet eine Zahl (oder null) im State.

Select – Auswahl

options ist eine Liste von Texten oder Objekten. Mit optionValue und optionLabel passt eine Datenquelle direkt: "options": "{{state.gruppen}}", "optionValue": "id", "optionLabel": "name".

Checkbox – Checkbox

Im State landet true oder false; change liefert { value }.

DateInput – Datum

Im State landet der Wert des Browsers: 2026-10-02 bzw. mit Uhrzeit 2026-10-02T17:00.

Table – Tabelle

columns darf auch eine Liste von Feldnamen sein: ["title", "start"]. Bei rowClick steht die Zeile als item (und event) in den Aktionen.

List – Liste

Ohne Kinder zeigt jeder Eintrag itemText. Mit Kindern werden sie je Eintrag gezeichnet; darin gibt es {{item}} und {{index}}. itemText wird je Eintrag ausgewertet. click liefert den Eintrag als item.

Chart – Diagramm

Ein schlichtes SVG-Diagramm. Beschriftungen kommen aus dem Feld x (Standard label), Werte aus y (Standard value).

Ausdrücke {{…}}

Ausdrücke setzen Werte aus dem State oder dem Kontext ein. Sie sind reine Pfade: kein Rechnen, keine Vergleiche, keine Funktionsaufrufe. Alles, was mehr braucht, gehört in einen Handler.

{{state.profil.firstName}}        Wert aus dem State
{{state.termine[0].title}}        Listeneintrag über den Index (auch state.termine.0.title)
{{item.name}}                     Eintrag einer Liste oder angeklickte Tabellenzeile
{{event.value}}                   Wert eines change- oder submit-Ereignisses
{{context.organisation.name}}     Kontext des Hosts

Was verfügbar ist:

Zwei Regeln bestimmen das Ergebnis:

• Steht der Ausdruck allein, bekommst du den Wert selbst – eine Liste bleibt eine Liste, eine Zahl eine Zahl. So übergibst du {{state.termine}} an eine Tabelle.
• Steht er in einem Text, wird er zu Text: "Hallo {{state.profil.firstName}}!". Objekte erscheinen dann als JSON, fehlende Werte als leerer Text.

Pfade auf __proto__, prototype oder constructor liefern immer nichts.

Datenbindungen

Eine Bindung lädt eine Datenquelle beim Start der App und legt das Ergebnis im State ab:

"bind": [
  { "source": "me.events", "to": "termine", "pick": "items" },
  { "source": "storage.list", "params": { "collection": "notizen", "scope": "org" }, "to": "notizen", "pick": "items" }
]

Alle Bindungen aller Knoten starten gleichzeitig, sobald die App geladen ist. Die Parameter werden einmal gegen den Start-State ausgewertet. Danach laufen die load-Aktionen des Wurzelknotens. Schlägt eine Bindung fehl, zeigt die App einen roten Hinweis; die übrigen laufen weiter.

Um Daten später neu zu laden – etwa nach dem Speichern –, nimmst du die Aktion call mit demselben to.

Ereignisse

load wirkt nur am Wurzelknoten. Ein Ereignis führt seine Aktionen nacheinander aus; wirft eine davon einen Fehler, bricht die Kette ab und die App zeigt „Aktion fehlgeschlagen: …“.

Aktionen

call – Daten abrufen

{ "type": "call", "source": "storage.put",
  "params": { "collection": "notizen", "key": "{{state.neu.key}}", "value": "{{state.neu.text}}" } }

export – Exportieren

{ "type": "export", "format": "csv", "data": "{{state.termine}}", "filename": "termine-{{context.organisation.name}}",
  "columns": [{ "key": "title", "label": "Termin" }, { "key": "start", "label": "Beginn" }], "excel": true }

Die Datei geht über die Bridge an den Host, der sie herunterlädt (Dashboard) oder teilt (Handy).

navigate – Navigieren

{ "type": "navigate", "path": "/apps" }

Bittet den Host, zu einer seiner eigenen Seiten zu wechseln – ein Pfad des Dashboards bzw. der Mitglieder-App, keine fremde Adresse. Ziele, die es in der Mitglieder-App nicht gibt, lehnt sie mit einem Fehler ab. Außerhalb eines Hosts setzt die Runtime nur den Hash der Seite.

setState – State setzen

{ "type": "setState", "key": "auswahl", "value": "{{item}}" }

value darf ein Ausdruck oder ein fester Wert sein, auch ein Objekt. Ohne value wird der Schlüssel geleert.

toast – Hinweis anzeigen

{ "type": "toast", "message": "{{state.notizen.length}} Notizen geladen", "color": "green" }

color: green, blue, orange oder red. Der Host zeigt den Hinweis in seinem eigenen Stil.

script – Handler aus main.js

{ "type": "script", "handler": "speichern", "args": { "collection": "notizen" } }

Ruft die gleichnamige exportierte Funktion aus main.js auf. args wird vorher ausgewertet. Mehr unter main.js & Handler.

Beispiel: Pinnwand

Eine App, die Notizen des Vereins im App-Speicher ablegt und anzeigt – ganz ohne main.js:

{
  "schemaVersion": 1,
  "name": "Pinnwand",
  "auth": { "clientId": "cl_7d2e41a9", "scopes": ["mc.apps.storage:read", "mc.apps.storage:write"] },
  "initialState": { "neu": "" },
  "root": {
    "id": "root",
    "type": "Stack",
    "bind": [{ "source": "storage.list", "params": { "collection": "pinnwand" }, "to": "notizen", "pick": "items" }],
    "children": [
      { "id": "titel", "type": "Heading", "props": { "text": "Pinnwand {{context.organisation.name}}", "level": 2 } },
      {
        "id": "zeile",
        "type": "Stack",
        "props": { "direction": "row", "gap": 8 },
        "children": [
          { "id": "eingabe", "type": "TextInput", "props": { "label": "Neue Notiz", "model": "neu" } },
          {
            "id": "anheften",
            "type": "Button",
            "props": { "label": "Anheften" },
            "on": {
              "click": [
                { "type": "call", "source": "storage.put",
                  "params": { "collection": "pinnwand", "key": "{{state.neu}}", "value": "{{state.neu}}" } },
                { "type": "call", "source": "storage.list", "params": { "collection": "pinnwand" }, "to": "notizen", "pick": "items" },
                { "type": "setState", "key": "neu", "value": "" }
              ]
            }
          }
        ]
      },
      {
        "id": "liste",
        "type": "List",
        "props": { "data": "{{state.notizen}}", "itemText": "{{item.value}}", "empty": "Noch nichts angeheftet" }
      }
    ]
  }
}

Der Schlüssel ist hier der Text selbst – das hält das Beispiel kurz, erlaubt aber nur Zeichen aus A–Z a–z 0–9 _ -. Eine echte Pinnwand erzeugt Schlüssel in einem Handler.

Validierung

Die Runtime prüft app.json beim Laden, das Studio schon beim Tippen. Typische Meldungen:

Ältere Dokumente repariert das Studio beim Öffnen selbst: leere State-Schlüssel bekommen einen lesbaren Namen, Tabs ohne Titel heißen „Tab 1“, „Tab 2“ usw.