What is the JSON schema

背景： 对于核心云物联平台的设计，其中一个最重要的是物模型的设计。 而在处理物模型的时候，后端需要校验物模型设计模板的约束(不同数据类型有不同的限制)是否符合设计的基本规范。 由于物模型定义结构和校验维度较为复杂，纯通过后端代码编写不仅繁琐，且无法语义化，维护起来是非常麻烦。 经过调研，接触到JSON schema非常符合此类场景的需求。通过定义模板的Json schema，以“声明式”的描述语言作为前端、后端和测试的api请求的约束“契约”唯一来源，便于团队交流和后期维护。避免了代码和文档的分别描述导致的更新不及时。

本文章是对JSON Schema的入门介绍以及提供了一些可以更深入研究的参考资料指引，方便大家查找。

（由于当时调研后自己记录用的是英语，所以偷个懒，就不给自己做翻译了。）

1. Why do we need the Json schema?

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. - JSON Schema

JSON Schema defines the media type "application/schema+json", a JSON-based format for describing the structure of JSON data. JSON Schema asserts what a JSON document must look like, ways to extract information from it, and how to interact with it. The "application/schema-instance+json" media type provides additional feature-rich integration with "application/schema+json" beyond what can be offered for "application/json" documents. -- JSON Schema: A Media Type for Describing JSON Documents

JSON stands for “JavaScript Object Notation”, a simple data interchange format. It began as a notation for the world wide web. Since JavaScript exists in most web browsers, and JSON is based on JavaScript, it’s very easy to support there. However, it has proven useful enough and simple enough that it is now used in many other contexts that don’t involve web surfing.

At its heart, JSON is built on the following data structures:

• object: { "key1": "value1", "key2": "value2" }

• array: [ "first", "second", "third" ]

• number: 42,3.1415926

• string: "This is a string"

• boolean: true false

• null: null

  With these simple data types, all kinds of structured data can be represented. With that great flexibility comes great responsibility, however, as the same concept could be represented in myriad ways. For example, you could imagine representing information about a person in JSON in different ways:

{
 "name": "George Washington",
 "birthday": "February 22, 1732",
 "address": "Mount Vernon, Virginia, United States"
}


{
 "first_name": "George",
 "last_name": "Washington",
 "birthday": "1732-02-22",
 "address": {
   "street_address": "3200 Mount Vernon Memorial Highway",
   "city": "Mount Vernon",
   "state": "Virginia",
   "country": "United States"
 }
}

Both representations are equally valid, though one is clearly more formal than the other. The design of a record will largely depend on its intended use within the application, so there’s no right or wrong answer here. However, when an application says “give me a JSON record for a person”, it’s important to know exactly how that record should be organized. For example, we need to know what fields are expected, and how the values are represented. That’s where JSON Schema comes in. The following JSON Schema fragment describes how the second example above is structured. Don’t worry too much about the details for now. They are explained in subsequent chapters.

{
  "type": "object",
  "properties": {
    "first_name": { "type": "string" },
    "last_name": { "type": "string" },
    "birthday": { "type": "string", "format": "date" },
    "address": {
      "type": "object",
      "properties": {
        "street_address": { "type": "string" },
        "city": { "type": "string" },
        "state": { "type": "string" },
        "country": { "type" : "string" }
      }
    }
  }
}

By “validating” the first example against this schema, you can see that it fails:

{
  "name": "George Washington",
  "birthday": "February 22, 1732",
  "address": "Mount Vernon, Virginia, United States"
}

However, the second example passes:

{
  "first_name": "George",
  "last_name": "Washington",
  "birthday": "22-02-1732",
  "address": {
    "street_address": "3200 Mount Vernon Memorial Highway",
    "city": "Mount Vernon",
    "state": "Virginia",
    "country": "United States"
  }
}

2. Benefits

• Describes your existing data format(s).

• Provides clear human- and machine- readable documentation.

• Validates data which is useful for:

  • Automated testing.
  • Ensuring quality of client submitted data.

You may have noticed that the JSON Schema itself is written in JSON. It is data itself, not a computer program. It’s just a declarative format for “describing the structure of other data”. This is both its strength and its weakness (which it shares with other similar schema languages). It is easy to concisely describe the surface structure of data, and automate validating data against it. However, since a JSON Schema can’t contain arbitrary code, there are certain constraints on the relationships between data elements that can’t be expressed. Any “validation tool” for a sufficiently complex data format, therefore, will likely have two phases of validation: one at the schema (or structural) level, and one at the semantic level. The latter check will likely need to be implemented using a more general-purpose programming language.

3. Specification Links:

Specification
Specification Links

For further information about JSON Schema (7.0):
Understanding JSON Schema — Understanding JSON Schema 2020-12 documentation

4. references:

Learn

JSON Schema: A Media Type for Describing JSON Documents

5. Useful Tools:

There are som useful online json validators that runs all validation in browser:
JSON Schema Validation
JSON Schema Generator.