如何使用结构化数据

MDN 在可能的情况下将数据存储在定义明确的结构中。然后，这些信息将集中化，并且可以更新一次，同时在许多地方使用。

有几个这样的文件，本文档描述了它们的用途、结构和维护流程。

GroupData: API 的逻辑分组

GroupData 是一个 JSON 文件，用于收集有关 Web API 的信息。API 的分组是有点模糊的：任何接口、方法或属性都可以是几个 API 的一部分。在某个名称下分组的 API 集合是用于在没有技术强制的情况下交流有关功能的约定。

但是，MDN 需要这些信息来创建连贯的 Web API 侧边栏（例如使用 {{APIRef}} 宏），其中包含正确的参考页面、指南和概述文章。

GroupData 正是这样做的：对于每个 API，它都列出了接口、属性、方法、指南和概述页面。过去，它还列出了字典和回调。但这种用法虽然仍然受支持，但已过时，将在未来被移除。

GroupData 的结构

警告：此文件中列出的不存在的页面将被忽略（在 en-US 中）。

GroupData.json 中的条目具有以下结构

json

"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",
    (…)
  ]
}

…其中

"Name_of_the_API": 此键既是侧边栏宏（如 {{APIRef("Name_of_the_API")}}）使用的 ID，也是在侧边栏中显示的名称。明智地选择它。

警告：如果您想更改在侧边栏中显示的名称，则必须编辑所有显示它的页面。
"overview": 这是一个包含一个页面的列表：概述页面，用作 "Name_of_the_API" 文本的链接。该值是页面的标题，该页面必须位于 web/api/ 目录中。
"guides": 这是一个按照给定顺序显示在侧边栏中的指南列表。该值是页面路径，从 /docs/ 开始。
"interfaces": 这列出了 API 中包含的接口。
"methods": 这列出了 API 中包含的方法。

注意：在 "interfaces" 中列出的接口的方法不得列出在那里。如果该页面的 page-type 键是 web-api-static-method 或 web-api-instance-method，则会自动将它们添加到侧边栏中。
"properties": 这列出了 API 中包含的其他接口上的属性，如 navigator.xr（WebXR API 添加到 navigator 对象的属性）

注意：在 "interfaces" 中列出的接口的属性不得列出在那里。如果该页面的 page-type 键是 web-api-static-property 或 web-api-instance-property，则会自动将它们添加到侧边栏中。
"events": 这列出了 API 中包含的其他接口的事件。该值是页面标题（这些页面必须位于 Web/Events 下）

注意：针对 "interfaces" 中列出的接口的事件不得列出在那里。如果该页面的 page-type 键是 web-api-event，则会自动将它们添加到侧边栏中。

还有两个键，"dictionaries" 和 "callbacks"，它们的操作原理相同。由于我们不再在他们自己的页面中记录这些实体，因此它们的用法已过时，并且不应向它们添加新的条目（并且我们一点一点地删除它们）。

注意：此外，所有键都不是必需的；最好（并且我们将强制执行这一点）添加一个带有空列表的非过时键，而不是省略它们。它表明值的缺失是经过深思熟虑的选择。

GroupData 更新流程

应该在影响侧边栏发生的更改相同的 PR 中更新此文件。这样，侧边栏始终是最新的。审查者不应该合并不采用它的 PR。

要测试您的更改，请检查您 PR 中的文件中的侧边栏是否正确显示所有条目。

GroupData.json 文件位于这里 GitHub 上。

InterfaceData: 记录接口继承

注意：我们希望将来能够从通过 w3c/webref 可用的数据中自动生成此文件。

InterfaceData 描述了接口的层次结构。它列出了继承。过去，它还列出了每个接口实现的 mixin；但这种用法已过时，我们从这个文件中移除 mixin 的速度与 MDN 更新的速度相同。

此继承数据用于构建 API 侧边栏以及接口页面中的 {{InheritanceDiagram}}。

InterfaceData 的结构

InterfaceData.json 中的条目具有以下结构

json

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

注意：由于 mixin 已过时，因此对于所有新接口，"impl" 必须是一个空列表。

"Name_of_the_parent_interface" 的值不是一个列表，而是一个强制性的单个条目；我们不得列出任何不继承自另一个接口的接口。

InterfaceData 更新流程

添加一个从另一个接口继承的新接口的相同 PR 必须更新此文件。审查者不应该合并不这样做的 PR。

要测试您的更改，请检查您在 PR 中编辑的每个接口的侧边栏是否正确显示继承关系。

InterfaceData.json 文件位于这里 GitHub 上。

SpecData: 规范信息

警告：SpecData.json 文件不再维护。规范信息以规范形式存储在 w3c/browser-spec 中，以及 mdn/browser-compat-data 中功能的 spec_url 键中。

我们正在移除的 {{SpecName}} 和 {{Spec2}} 宏使用 SpecData.json 文件。我们不接受对 SpecData.json 文件的任何进一步贡献；相反，请尝试插入一个规范表格，使用 {{Specifications}} 宏，或者尝试硬编码到规范的（好的）链接。请注意，大多数情况下，在规范部分之外提及或链接到规范是 MDN 上未适当地记录的迹象。

SpecData.json 文件位于这里 GitHub 上。