记录 JSON 文件结构的最佳实践？

Question

我希望其他人能够创建我的代码可以理解的 JSON 文件。我如何最好地记录所需/允许的结构是什么？

例子：

{
    "customer1" : {
        "open-orders" : [
            123,
            456
        ],
        "terms" : [
            "net 30"
        ]
    }, ...
}

我将如何声明诸如“在第一层，它是在 CRM 系统中找到的客户 ID。然后需要有‘条款’，并且数组中可能有 1 到 3 个项目。您永远不能调用一级标签'错误'，但所有其他未知标签都被忽略等等。”

在 XML 中，我可以使用一个 DTD，它已经捕获了其中的一些信息，并且我可以添加一些额外的注释。

但是 JSON 的最佳实践是什么？现在我正在使用一个表结构，其中在左列中，根据我的结构，我有一个有效的 JSON 文件，该文件被切成块，每个块都是表中的一行。在右侧的列中，我然后写散文，一次一大块/一行。我对此不太满意。有更好的想法吗？

Answer 1

JSON 只是数据结构的序列化表示；因此，您应该记录数据结构而不是序列化输出。

/**
 * @var object Customer
 */
var customer = {
    /**
     * @var Number[][]
     */
    "open-orders": [],
    /**
     * @var String[][]
     */
    "terms": []
};

此外，JSON 没有任何数据规范（标记）符号，如 XML；尽管 XML 也可用于序列化数据，但它允许您指定数据的结构（使用 XSD）。JSON 无意执行此操作，并且没有提供此类机制。