如何在规范中描述 JSON 数据？

How to describe JSON data in a spec?

提问by Rob Walker

What is the best way to describe JSON data in a spec?

在规范中描述 JSON 数据的最佳方式是什么？

In the past I've used examples with 'wordy' descriptions, but it feels imprecise.

过去，我使用过带有“冗长”描述的示例，但感觉不准确。

There seems to be a nascent JSON schemastandard, but it doesn't look like a hugely active project. Any other ways?

似乎有一个新生的JSON 模式标准，但它看起来不像一个非常活跃的项目。还有其他方法吗？

---

---

(Update) After thinking about this for several days I like bmargulies suggestion around using a conversion convention. Since the JSON documents in this case our coming out of .NET web services I am going to simply document the schema with C# class syntax. This may not be totally rigourous, but everyone involved will understand it and coupled with the examples will get the message across as quickly as possible.

(更新) 经过几天的思考，我喜欢 bmargulies 关于使用转换约定的建议。由于在这种情况下 JSON 文档来自 .NET Web 服务，因此我将使用 C# 类语法简单地记录模式。这可能不完全严格，但每个参与的人都会理解它，并结合示例将尽快传达信息。

回答by molnarg

I would recommend my js-schemaJavaScript library. The primary motivation behind it was the same what you describe in the question. It is a simple and easy to understand notation to describe JSON schemas (or specification, if you want).

我会推荐我的js-schemaJavaScript 库。其背后的主要动机与您在问题中描述的相同。描述 JSON 模式（或规范，如果需要）是一种简单易懂的表示法。

An example schema described in JSON Schema:

JSON 架构中描述的示例架构：

{
  "type":"object",
  "properties":{
    "id":{
      "type":"number",
      "required":true
    },
    "name":{
      "type":"string",
      "required":true
    },
    "price":{
      "type": "number",
      "minimum":0,
      "required":true
    },
    "tags":{
      "type":"array",
      "items":{
        "type":"string"
      }
    }
  }
}

and the same schema description with js-schema:

以及与 js-schema 相同的模式描述：

{
  "id"    : Number,
  "name"  : String,
  "price" : Number.min(0),
  "?tags" : Array.of(String)
}

The library is able to validate object against schemas, generate random objects conforming to a given schema, and serialize/deserialize to/from JSON Schema.

该库能够根据模式验证对象，生成符合给定模式的随机对象，以及与 JSON 模式之间的序列化/反序列化。

回答by Michael Sandino

I know this is an older question, but it might be useful to someone else: When looking for methods to describe JSON-data I stumbled upon Orderly. Here's the abstract right of the front page:

我知道这是一个较旧的问题，但它可能对其他人有用：在寻找描述 JSON 数据的方法时，我偶然发现了Orderly。这是首页的摘要右侧：

Orderly is a textual format for describing JSON. Orderly can be compiled into JSONSchema. It is designed to be easy to read and write.

Orderly 是一种用于描述 JSON 的文本格式。Orderly 可以编译成 JSONSchema。它旨在易于阅读和编写。

I can agree with that, but I have only tried it with relatively simple structures so far.

我同意这一点，但到目前为止我只用相对简单的结构尝试过它。

回答by JeSuisse

How about using some kind of extended BNF?

使用某种扩展的 BNF 怎么样？

PERSON <- { "firstname": FIRSTNAMES, "lastname": LASTNAME, "age": AGE, "version": VERSION, "parents" <- PARENTS }

FIRSTNAMES <- [ FIRSTNAME+ ]

FIRSTNAME <- STRING

LASTNAME <- STRING

PARENTS <- [ PERSON{0,2} ]

AGE <- INTEGER

VERSION <- 1 | 2

You'd have to define the meaning of atomic type descriptions like INTEGER and STRING somewhere. If you wanted to add non-hardcoded keys for dictionaries, you would define that as follows:

您必须在某处定义诸如 INTEGER 和 STRING 之类的原子类型描述的含义。如果你想为字典添加非硬编码键，你可以定义如下：

BREADLOOKUP <- { (TYPE : HOWMANY)+ }

TYPE <- "white" | "dark" | "french" | "croissant"

HOWMANY <- POSITIVE-INTEGER

This would allow stuff like

这将允许像

{ "white": 5, 
  "french": 2
}

Since both regular expressions and BNF are pretty well known, this might be an easy way to go. ?, +, *, {n}, {min,max}would be easy ways to specify a number of elements (taken from regexes) and the rest is pretty much pure BNF.

由于正则表达式和 BNF 都是众所周知的，这可能是一种简单的方法。?, +, *, {n},{min,max}将是指定多个元素（取自正则表达式）的简单方法，其余部分几乎是纯 BNF。

If you did that rigorously enough, it might even be parsable for a validator.

如果你做得足够严格，它甚至可以被验证器解析。

回答by bmargulies

You could combine a W3C XML Schema, or some less ugly schema like RelaxNG, with conversion conventions.

您可以将 W3C XML 模式或一些不那么难看的模式（如 RelaxNG）与转换约定相结合。