Skip to content

JSON#

JavaScript Object Notation

Why use JSON Schema#

  • Describe existing data format
  • Define rules and constraints
  • Clear and readable documentation
  • Highly extensible
  • Vaildate your data
    • Automate testing
    • Enhance data quality
  • Wide range of tools availabiility

JSON Data Type#

  1. Arrays

    string, number, object, array, Boolean, or null
    [ "first", 2, true, null ]

  2. Boolean

    true, false. Doesn't need "
    true false

  3. Null

    When no value is assigned to a key, it can be treated as null.
    null

  4. Number

    Both positive and negative numbers as well as decimal points. A JSON numbers follows JavaScript's double-precision floating-point format (1).

      • 64位元 IEEE 754浮點數
      • 範圍: -21024 ~ +21023

    465.3213

  5. Ojbect

    { key1: value1, key2: value2 }

  6. String

    Strings are enclosed in ", can contain any Unicode (1) character.

      • 因為ASCII code不足以支持所有的語系，所以有了Unicode的誕生。
      • UTF-8:
        • Unicode Transformation Format (UTF)
        • 可變長度的編碼，使用1到4個位元組來表達一個字元，並與ASCII相容
        • 世界最廣泛的編碼方式

    "This is a string"

JSON Schema#

  • Data is name(key)/ value pairs
  • Data is separated by commas
  • Curly braces hold objects
  • Square brackets hold arrays

Keywords#

Metadata keywords#

  • $schema: states that this schema complies
  • $id: provides a base URI for referencing this schema, type, or property
  • title: describes the intent of a schema
  • description: provides a definition for this type or property

Validation Keywords#

  • Numbers and Integers

    • multipleOf: limit the value to be a multiple of a given number
    • minimum, exclusiveMinimum, maximum, exclusiveMaxmum: restrict the range of values

  • Strings

    • minLength, maxLength: limit the length of the string
    • pattern: require the value to satisfy of the string
    • format: require the value to match a certain format

  • Arrays

    • type: limit the type of each item
    • enum: define the alloable values of each item with an array
    • minItems, maxItems: limit the number or items
    • uniqueItems: require each item to be unique

  • Objects

    • properties: list properties that may be included in the object
    • required: list properties that must be included in the object
    • additionalProperties: allow properties that are not listed in the type definition
    • minProperties, maxProperties: limit the number of properties in the object
    • patternProperties: define types for properties based on their name
    • dependencies: add restrictions if certain conditions are met
  • allOf: must be valid against all of the subschemas
  • anyOf: must be valid against any of the subschemas

  • oneOf: must be valid against exactly one of the subschemas

  • $ref, $def: must be an object, and object must be a valid JSON schema

Create a Simple JSON Schema#

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
{
  // employee schema
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "mySchema",
  "title": "Information of Employee",
  "description": "The document records the details of an employee",
  "type": "object",
  "properties": {
    "id": {
      "description": "The unique number for an employee",
      "type": "number",
    },
    "name": {
      "description" : "The name of the employee",
      "type": "string",
      "minLength": 2
    },
    "dateOfBirth": {
      "description": "The date of birth of the employee",
      "type": "string",
      "format": "date"
    },
    "hobbies": {
      "description": "Hobbies of the employee",
      "type": "object",
      "properties": {
        "indoor": {
          "type": "array",
          "items": {
            "description": "List of hobbies",
            "type": "string"
          },
          "minItems": 1,
          "uniqueItems": true
        },
        "outdoor": {
          "type": "array",
          "items": {
            "description": "List of hobbies",
            "type": "string"
          },
        "minItems": 1,
        "uniqueItems": true
        }
      }
    },
    "usedLaptop": {
      "description": "Which brands of laptops do employees use",
      "OSType": {
        "type": "string"
      },
      "required": ["OSType"],
      "oneOf": [
        {
          "properties": {
            "OSType": {
              "const": "Windows"
            }
          },
          "$ref": "#/loptop.schema.json"
        },
        {
          "properties": {
            "OSType": {
              "const": "OSX"
            }
          },
          "$ref": "#/loptop.schema.json"
        }
      ]
    }
  },
  "required": ["id", "name", "dateOfBirth", "hobbies", "usedLaptop"]
}


// laptop schema --------------------------------------------------
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "#/laptop.schema.json",
  "type": "object",
  "properties": {
    "brand": {
      "type": "string"
    },
    "model": {
      "type": "string"
    }
  },
  "required": ["brand", "model"]
}

Differences#

JSON vs. XML vs. YAML

JSON#

Commonly used for data storage and transfer.

XML (Extensible Markup Language)#

It is general-purpose markup language similar to JSON that allows for more complex data structures.

YAML#

It was designed specifically to be easier for humans to read, and originally built to simplify XML.

  • Indentation to represent objects
  • Colons to separate key-value pairs
  • Hyphens for arrays
  • Hashes to denote a comment
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
{
  "cart":[
    {
      "_id":"637eab8f58712097007074e9",
      "foodName":"Bacon Cheddar Potato",
      "price":12.99,
      "quantity":2
    },
    {
      "_id":"637eade758712097007074ea",
      "foodName":"Karaage Chicken",
      "price":8.99,
      "quantity":3
    },
    {
      "_id":"63880b014a6a057eca9c9a6c",
      "foodName":"Lay's Chip",
      "price":3.29,
      "quantity":3
    },
    {
      "_id":"637eaf4058712097007074eb",
      "foodName":"Fruit Cake",
      "price":3.99,
      "quantity":5
    },
    {  
      "_id":"6388077afe667358fd954bd9",
      "foodName":"Lemonade",
      "price":2.99,
      "quantity":2
    }
  ]
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
<?xml version="1.0" encoding="UTF-8" ?>
<cart>
    <_id>637eab8f58712097007074e9</_id>
    <foodName>Bacon Cheddar Potato</foodName>
    <price>12.99</price>
    <quantity>2</quantity>
</cart>
<cart>
    <_id>637eade758712097007074ea</_id>
    <foodName>Karaage Chicken</foodName>
    <price>8.99</price>
    <quantity>3</quantity>
</cart>
<cart>
    <_id>63880b014a6a057eca9c9a6c</_id>
    <foodName>Lay's Chip</foodName>
    <price>3.29</price>
    <quantity>3</quantity>
</cart>
<cart>
    <_id>637eaf4058712097007074eb</_id>
    <foodName>Fruit Cake</foodName>
    <price>3.99</price>
    <quantity>5</quantity>
</cart>
<cart>
    <_id>6388077afe667358fd954bd9</_id>
    <foodName>Lemonade</foodName>
    <price>2.99</price>
    <quantity>2</quantity>
</cart>

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
cart:
- _id: 637eab8f58712097007074e9
  foodName: Bacon Cheddar Potato
  price: 12.99
  quantity: 2
- _id: 637eade758712097007074ea
  foodName: Karaage Chicken
  price: 8.99
  quantity: 3
- _id: 63880b014a6a057eca9c9a6c
  foodName: Lay's Chip
  price: 3.29
  quantity: 3
- _id: 637eaf4058712097007074eb
  foodName: Fruit Cake
  price: 3.99
  quantity: 5
- _id: 6388077afe667358fd954bd9
  foodName: Lemonade
  price: 2.99
  quantity: 2

References#