Cómo usar datos estructurados

GroupData es un archivo JSON que recopila información sobre las API web. La agrupación de APIs es algo difusa: cualquier interfaz, método o propiedad puede formar parte de varias APIs. El conjunto de API agrupadas bajo un nombre es una convención utilizada para comunicar sobre una característica, sin ninguna aplicación técnica.

Sin embargo, MDN necesita esta información para crear menus laterales coherentes de Web-API (como con la macro {{APIRef}}) con las páginas de referencia, guías y artículos generales adecuados.

GroupData hace exactamente eso: para cada API, enumera las interfaces, propiedades, métodos, guías y páginas de descripción general. En el pasado, también enumeraba diccionarios y devoluciones de llamada. Pero ese uso, aunque todavía es compatible, está obsoleto y se eliminará en el futuro.

Una entrada en GroupData.json tiene la siguiente estructura:

"Nombre_de_API": {
  "overview": ["nombre de la página de descripción general"],
  "guides": [
    "nombre_de_guia_1",
    (…)
  ],
  "interfaces": [
    "nombre_de_interfaz_1",
    (…)
  ],
  "methods": [
    "nombre_de_metodo_adicional_1",
    (…)
  ],
  "properties": [
    "nombre_de_propiedad_adicional_1",
    (…)
  ],
  "events": [
    "nombre_de_propiedad_adicional_1",
    (…)
  ]
}

…donde:

"Nombre_de_API"

Esta clave es un ID utilizado por macros de menu lateral como {{APIRef("Nombre_de_API")}} y el nombre que se muestra en el menu lateral. Elígelo sabiamente.

Advertencia: Si desea cambiar el nombre que se muestra en el menu lateral, debe editar todas las páginas que lo muestran.

"overview"

Esta es una lista que contiene una página: la página de resumen, utilizada como enlace para el texto "Nombre_de_API". El valor es el titulo de la página, y la página debe estar en el directorio web/api/.

"guides"

Esta es una lista de guías para mostrar en el menu lateral, en el orden dado. Los valores son rutas a la página, comenzando con /docs/.

"interfaces"

Enumera las interfaces que forman parte de la API.

"methods"

Enumera los métodos que forman parte de la API.

Nota: Los métodos de las interfaces enumeradas en "interfaces" no deben estar enumerados allí. Se añaden automáticamente al menu lateral si la etiqueta Method está en el encabezado YAML de esa página.

"properties"

Enumera los métodos en otras interfaces que forman parte de la API, como navigator.xr (una propiedad que la API de WebXR agrega al objeto navigator)

Nota: Las propiedades de las interfaces enumeradas en "interfaces" no deben estar enumeradas allí. Se añaden automáticamente a la barra lateral si la etiqueta Property está en el encabezado YAML de esa página.

"events"

Enumera los eventos de otras interfaces que forman parte de la API. Los valores son el título de las páginas (que debe residir en Web/Events)

Nota: Los eventos dirigidos a las interfaces enumeradas en "interfaces" no deben estar enumerados allí. Se añaden automáticamente al menu lateral si la etiqueta Event (¡singular!) está en el encabezado YAML de esa página.

Hay otras dos claves, "dictionaries" y "callbacks", que funcionan con el mismo principio. Como ya no documentamos estas entidades en sus propias páginas, su uso está obsoleto y no se les debe añadir ninguna entrada nueva (y las eliminamos poco a poco).

Este archivo debe actualizarse en el mismo PR donde se producen los cambios que afectan al menu lateral. De esta forma, el menu lateral estará siempre actualizado. Los revisores no deben fusionar las solicitudes de incorporacion que no las adopten.

Para probar sus cambios, verifique que el menu lateral en los archivos de su PR muestre todas las entradas correctamente.

El archivo GroupData.json se encuentra aquí en GitHub.

InterfaceData describe la jerarquía de las interfaces. Enumera la herencia. En el pasado, también enumeraba los mixins implementados por cada interfaz; pero ese uso está obsoleto, y eliminamos los mixins de este archivo al mismo ritmo que se actualiza MDN.

Estos datos de herencia se utilizan al crear menus laterales de API y por el {{InheritanceDiagram}} en las páginas de la interfaz.

Una entrada en InterfaceData.json tiene la siguiente estructura:

"Nombre_de_la_interfaz": {
  "inh": "Nombre_de_la_interfaz_padre",
  "impl": []
}

El valor de "Nombre_de_la_interfaz_padre" no es una lista sino una sola entrada, obligatoria; no debemos enumerar ninguna interfaz que no herede de otra.

El mismo PR que añade una nueva interfaz que hereda de otra debe actualizar este archivo. Los revisores no deben fusionar las solicitudes de incorporacion que no lo hacen.

Para probar sus cambios, verifique que los menus laterales de cada interfaz que editó en su PR muestren la herencia correctamente.

El archivo InterfaceData.json se encuentra aquí en GitHub.

Las macros {{SpecName}} y {{Spec2}} que estamos eliminando utilizan el archivo SpecData.json. No aceptamos más contribuciones al archivo SpecData.json; en su lugar, intente insertar una tabla de especificaciones, utilizando la macro {{Specifications}}, o intente codificar el enlace (bueno) a la especificación. Tenga en cuenta que la mayoría de las veces, mencionar o vincular a una especificación fuera de la sección Especificaciones es un signo de algo que no está debidamente documentado en MDN.

El archivo SpecData.json se encuentra aquí en GitHub.