Anleitung zur Verwendung von strukturierten Daten

GroupData: Logische Gruppierung von APIs

GroupData ist eine JSON-Datei, die Informationen über Web-APIs sammelt. Die Gruppierung von APIs ist etwas unscharf: Jede Schnittstelle, Methode oder Eigenschaft kann Teil mehrerer APIs sein. Der unter einem Namen gruppierte Satz von APIs ist eine Konvention, die zur Kommunikation über eine Funktion verwendet wird, ohne dass eine technische Durchsetzung erfolgt.

Dennoch benötigt MDN diese Informationen, um kohärente Web-API-Seitenelemente (wie mit dem {{APIRef}} Makro) mit den passenden Referenzseiten, Leitfäden und Überblicksartikeln zu erstellen.

GroupData übernimmt genau diese Aufgabe: Für jede API listet es die Schnittstellen, Eigenschaften, Methoden, Leitfäden und Überblicksseiten auf. In der Vergangenheit listete es auch Wörterbücher und Rückrufe auf. Diese Nutzung wird zwar noch unterstützt, ist jedoch veraltet und wird in Zukunft entfernt.

Struktur von GroupData

Ein Eintrag in GroupData.json hat die folgende Struktur:

{
  "Name_of_the_API": {
    "overview": ["name_of_the_overview_page"],
    "guides": [
      "name_of_guide_1"
      // …
    ],
    "interfaces": [
      "name_of_interface_1"
      // …
    ],
    "methods": [
      "name_of_additional_method_1"
      // …
    ],
    "properties": [
      "name_of_additional_property_1"
      // …
    ],
    "events": [
      "name_of_additional_property_1"
      // …
    ]
  }
}

…wo:

"Name_of_the_API"

Dieser Schlüssel ist sowohl eine ID, die von Seitenleisten-Makros wie {{APIRef("Name_of_the_API")}} verwendet wird, als auch der im Seitenleisten angezeigt wird. Wählen Sie ihn mit Bedacht.

Warnung: Wenn Sie den Namen, der in der Seitenleiste angezeigt wird, ändern möchten, müssen Sie alle Seiten bearbeiten, die ihn anzeigen.

"overview"

Dies ist eine Liste, die eine Seite enthält: die Übersichtsseite, die als Link für den "Name_of_the_API" Text verwendet wird. Der Wert ist der Titel der Seite, und die Seite muss im Verzeichnis web/api/ liegen.

"guides"

Dies ist eine Liste von Leitfäden, die in der Seitenleiste in der angegebenen Reihenfolge angezeigt werden. Die Werte sind Pfade zur Seite, beginnend mit /docs/.

"interfaces"

Dies listet die Schnittstellen auf, die Teil der API sind.

"methods"

Dies listet die Methoden auf, die Teil der API sind.

Hinweis: Die Methoden der in "interfaces" aufgelisteten Schnittstellen dürfen dort nicht aufgelistet werden. Sie werden automatisch in die Seitenleiste aufgenommen, wenn der page-type Schlüssel für diese Seite web-api-static-method oder web-api-instance-method ist.

"properties"

Dies listet die Eigenschaften auf anderen Schnittstellen auf, die Teil der API sind, wie navigator.xr (eine Eigenschaft, die die WebXR API zum navigator Objekt hinzufügt).

Hinweis: Die Eigenschaften der in "interfaces" aufgelisteten Schnittstellen dürfen dort nicht aufgelistet werden. Sie werden automatisch in die Seitenleiste aufgenommen, wenn der page-type Schlüssel für diese Seite web-api-static-property oder web-api-instance-property ist.

"events"

Dies listet die Ereignisse anderer Schnittstellen auf, die Teil der API sind. Die Werte sind die Titel der Seiten.

Hinweis: Die Ereignisse, die die in "interfaces" aufgelisteten Schnittstellen ansprechen, dürfen dort nicht aufgelistet werden. Sie werden automatisch in die Seitenleiste aufgenommen, wenn der page-type Schlüssel für diese Seite web-api-event ist.

Es gibt zwei weitere Schlüssel, "dictionaries" und "callbacks", die nach dem gleichen Prinzip arbeiten. Da wir diese Entitäten nicht mehr auf ihren eigenen Seiten dokumentieren, ist ihre Verwendung veraltet, und es sollten keine neuen Einträge hinzugefügt werden (und wir entfernen sie nach und nach).

Aktualisierungsprozess für GroupData

Diese Datei, die sich unter files/jsondata/GroupData.json befindet, sollte in dem gleichen PR aktualisiert werden, in dem Änderungen, die die Seitenleiste betreffen, erfolgen. So bleibt die Seitenleiste immer aktuell. Prüfer sollten keine PRs zusammenführen, die dies nicht übernehmen.

Um Ihre Änderungen zu testen, überprüfen Sie, dass die Seitenleiste in den Dateien in Ihrem PR alle Einträge korrekt anzeigt.

InterfaceData: Aufzeichnung der Schnittstellenvererbung

InterfaceData beschreibt die Hierarchie der Schnittstellen. Es listet Vererbung auf. In der Vergangenheit listete es auch Mixins auf, die von jeder Schnittstelle implementiert wurden; aber diese Nutzung ist veraltet, und wir entfernen Mixins aus dieser Datei in dem Maße, wie MDN aktualisiert wird.

Diese Vererbungsdaten werden beim Erstellen von API-Seitenleisten und durch das {{InheritanceDiagram}} auf den Interface-Seiten verwendet.

Struktur von InterfaceData

Ein Eintrag in InterfaceData.json hat die folgende Struktur:

{
  "Name_of_the_interface": {
    "inh": "Name_of_the_parent_interface",
    "impl": []
  }
}

Der Wert von "Name_of_the_parent_interface" ist keine Liste, sondern ein einzelner obligatorischer Eintrag; wir dürfen keine Schnittstelle aufführen, die nicht von einer anderen erbt.

Aktualisierungsprozess für InterfaceData

Der gleiche PR, der eine neue Schnittstelle hinzufügt, die von einer anderen erbt, muss diese Datei, die sich unter files/jsondata/InterfaceData.json befindet, aktualisieren. Prüfer sollten keine PRs zusammenführen, die dies nicht tun.

Um Ihre Änderungen zu testen, überprüfen Sie, dass die Seitenleisten jeder Schnittstelle, die Sie in Ihrem PR bearbeitet haben, die Vererbung korrekt anzeigen.

SpecData: Spezifikationsinformationen

Wir akzeptieren keine weiteren Beiträge zur SpecData.json Datei; stattdessen fügen Sie eine Spezifikationstabelle mithilfe des {{Specifications}} Makros ein oder verlinken die Spezifikation im Fließtext. Beachten Sie, dass das Erwähnen oder Verlinken einer Spezifikation außerhalb des Spezifikationen Abschnitts meist ein Zeichen dafür ist, dass etwas auf MDN nicht angemessen dokumentiert ist.