JSON Schema 实战示例 - 从真实场景学习

引言#

学习 JSON Schema 最好的方式就是通过实际案例。本文提供了来自真实项目的完整 Schema 示例，涵盖 REST API、表单验证、配置文件、微服务通信等多个场景。

目录#

REST API 响应 Schema
表单验证 Schema
配置文件 Schema
微服务通信 Schema
数据管道 Schema
GraphQL 集成 Schema
事件驱动架构 Schema

REST API 响应 Schema {#rest-api}#

示例 1：用户 API 完整 Schema#

场景：电商平台的用户管理 API

1
{
2
  "$schema": "http://json-schema.org/draft-07/schema#",
3
  "$id": "https://api.example.com/schemas/user.json",
4
  "title": "用户 API 响应",
5
  "description": "描述用户相关的 API 响应结构",
6
  "type": "object",
7
  "definitions": {
8
    "address": {
9
      "type": "object",
10
      "properties": {
11
        "id": {
12
          "type": "integer",
13
          "description": "地址 ID",
14
          "minimum": 1
15
        },
16
        "label": {
17
          "type": "string",
18
          "description": "地址标签（如：家、公司）",
19
          "enum": ["home", "work", "other"],
20
          "default": "home"
21
        },
22
        "country": {
23
          "type": "string",
24
          "description": "国家/地区",
25
          "minLength": 2,
26
          "maxLength": 2,
27
          "pattern": "^[A-Z]{2}$"
28
        },
29
        "province": {
30
          "type": "string",
31
          "description": "省/州"
32
        },
33
        "city": {
34
          "type": "string",
35
          "description": "城市"
36
        },
37
        "district": {
38
          "type": "string",
39
          "description": "区/县"
40
        },
41
        "street": {
42
          "type": "string",
43
          "description": "街道地址",
44
          "maxLength": 200
45
        },
46
        "postalCode": {
47
          "type": "string",
48
          "description": "邮政编码",
49
          "pattern": "^\\d{6}$"
50
        },
51
        "isDefault": {
52
          "type": "boolean",
53
          "description": "是否为默认地址",
54
          "default": false
55
        }
56
      },
57
      "required": ["country", "city", "street"]
58
    },
59
    "user_profile": {
60
      "type": "object",
61
      "properties": {
62
        "avatar": {
63
          "type": "string",
64
          "format": "uri",
65
          "description": "头像 URL"
66
        },
67
        "bio": {
68
          "type": "string",
69
          "description": "个人简介",
70
          "maxLength": 500
71
        },
72
        "website": {
73
          "type": "string",
74
          "format": "uri",
75
          "description": "个人网站"
76
        },
77
        "company": {
78
          "type": "string",
79
          "description": "公司名称"
80
        },
81
        "position": {
82
          "type": "string",
83
          "description": "职位"
84
        }
85
      }
86
    }
87
  },
88
  "properties": {
89
    "status": {
90
      "type": "string",
91
      "enum": ["success", "error"],
92
      "description": "响应状态"
93
    },
94
    "code": {
95
      "type": "integer",
96
      "description": "状态码",
97
      "minimum": 1000,
98
      "maximum": 9999
99
    },
100
    "data": {
101
      "type": "object",
102
      "properties": {
103
        "user": {
104
          "type": "object",
105
          "properties": {
106
            "id": {
107
              "type": "integer",
108
              "description": "用户 ID",
109
              "minimum": 1,
110
              "example": 10001
111
            },
112
            "username": {
113
              "type": "string",
114
              "description": "用户名",
115
              "minLength": 3,
116
              "maxLength": 30,
117
              "pattern": "^[a-zA-Z0-9_]+$",
118
              "example": "john_doe"
119
            },
120
            "email": {
121
              "type": "string",
122
              "format": "email",
123
              "description": "邮箱地址",
124
              "example": "john@example.com"
125
            },
126
            "phone": {
127
              "type": "string",
128
              "description": "手机号码",
129
              "pattern": "^\\+?[0-9\\-\\s]+$",
130
              "example": "+86-13800138000"
131
            },
132
            "role": {
133
              "type": "string",
134
              "description": "用户角色",
135
              "enum": ["customer", "vip", "admin"],
136
              "default": "customer"
137
            },
138
            "status": {
139
              "type": "string",
140
              "description": "账户状态",
141
              "enum": ["active", "inactive", "suspended", "deleted"],
142
              "default": "active"
143
            },
144
            "profile": {
145
              "$ref": "#/definitions/user_profile"
146
            },
147
            "addresses": {
148
              "type": "array",
149
              "description": "收货地址列表",
150
              "items": {
151
                "$ref": "#/definitions/address"
152
              },
153
              "minItems": 0,
154
              "maxItems": 10
155
            },
156
            "preferences": {
157
              "type": "object",
158
              "description": "用户偏好设置",
159
              "properties": {
160
                "language": {
161
                  "type": "string",
162
                  "description": "语言",
163
                  "pattern": "^[a-z]{2}(-[A-Z]{2})?$",
164
                  "default": "zh-CN"
165
                },
166
                "currency": {
167
                  "type": "string",
168
                  "description": "货币",
169
                  "pattern": "^[A-Z]{3}$",
170
                  "default": "CNY"
171
                },
172
                "timezone": {
173
                  "type": "string",
174
                  "description": "时区",
175
                  "default": "Asia/Shanghai"
176
                },
177
                "notifications": {
178
                  "type": "object",
179
                  "properties": {
180
                    "email": {
181
                      "type": "boolean",
182
                      "default": true
183
                    },
184
                    "sms": {
185
                      "type": "boolean",
186
                      "default": false
187
                    },
188
                    "push": {
189
                      "type": "boolean",
190
                      "default": true
191
                    }
192
                  }
193
                }
194
              }
195
            },
196
            "statistics": {
197
              "type": "object",
198
              "description": "用户统计信息",
199
              "properties": {
200
                "totalOrders": {
201
                  "type": "integer",
202
                  "minimum": 0,
203
                  "default": 0
204
                },
205
                "totalSpent": {
206
                  "type": "number",
207
                  "minimum": 0,
208
                  "multipleOf": 0.01
209
                },
210
                "loyaltyPoints": {
211
                  "type": "integer",
212
                  "minimum": 0,
213
                  "default": 0
214
                },
215
                "memberSince": {
216
                  "type": "string",
217
                  "format": "date-time"
218
                },
219
                "lastLoginAt": {
220
                  "type": ["string", "null"],
221
                  "format": "date-time"
222
                }
223
              }
224
            },
225
            "createdAt": {
226
              "type": "string",
227
              "format": "date-time"
228
            },
229
            "updatedAt": {
230
              "type": "string",
231
              "format": "date-time"
232
            }
233
          },
234
          "required": ["id", "username", "email", "status", "createdAt"]
235
        }
236
      }
237
    },
238
    "timestamp": {
239
      "type": "string",
240
      "format": "date-time",
241
      "description": "响应时间戳"
242
    },
243
    "requestId": {
244
      "type": "string",
245
      "description": "请求 ID（用于追踪）",
246
      "pattern": "^[a-f0-9]{32}$"
247
    }
248
  },
249
  "required": ["status", "code", "data", "timestamp"]
250
}

使用示例：

1
{
2
  "status": "success",
3
  "code": 2000,
4
  "data": {
5
    "user": {
6
      "id": 10001,
7
      "username": "john_doe",
8
      "email": "john@example.com",
9
      "phone": "+86-13800138000",
10
      "role": "vip",
11
      "status": "active",
12
      "profile": {
13
        "avatar": "https://example.com/avatars/john.jpg",
14
        "bio": "Full-stack developer",
15
        "company": "Tech Corp"
16
      },
17
      "addresses": [
18
        {
19
          "id": 1,
20
          "label": "home",
21
          "country": "CN",
22
          "province": "Beijing",
23
          "city": "Beijing",
24
          "district": "Chaoyang",
25
          "street": "Building 1, Street 2",
26
          "postalCode": "100000",
27
          "isDefault": true
28
        }
29
      ],
30
      "preferences": {
31
        "language": "zh-CN",
32
        "currency": "CNY",
33
        "timezone": "Asia/Shanghai",
34
        "notifications": {
35
          "email": true,
36
          "sms": false,
37
          "push": true
38
        }
39
      },
40
      "statistics": {
41
        "totalOrders": 25,
42
        "totalSpent": 12580.50,
43
        "loyaltyPoints": 1250,
44
        "memberSince": "2023-01-15T08:00:00Z",
45
        "lastLoginAt": "2024-01-20T14:30:00Z"
46
      },
47
      "createdAt": "2023-01-15T08:00:00Z",
48
      "updatedAt": "2024-01-20T14:30:00Z"
49
    }
50
  },
51
  "timestamp": "2024-01-20T15:00:00Z",
52
  "requestId": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
53
}

示例 2：分页列表响应 Schema#

1
{
2
  "$schema": "http://json-schema.org/draft-07/schema#",
3
  "title": "分页列表响应",
4
  "type": "object",
5
  "definitions": {
6
    "pagination": {
7
      "type": "object",
8
      "properties": {
9
        "page": {
10
          "type": "integer",
11
          "minimum": 1,
12
          "default": 1
13
        },
14
        "pageSize": {
15
          "type": "integer",
16
          "minimum": 1,
17
          "maximum": 100,
18
          "default": 20
19
        },
20
        "totalItems": {
21
          "type": "integer",
22
          "minimum": 0
23
        },
24
        "totalPages": {
25
          "type": "integer",
26
          "minimum": 0
27
        },
28
        "hasNext": {
29
          "type": "boolean"
30
        },
31
        "hasPrev": {
32
          "type": "boolean"
33
        }
34
      },
35
      "required": ["page", "pageSize", "totalItems", "totalPages"]
36
    }
37
  },
38
  "properties": {
39
    "status": {
40
      "type": "string",
41
      "enum": ["success", "error"]
42
    },
43
    "data": {
44
      "type": "object",
45
      "properties": {
46
        "items": {
47
          "type": "array",
48
          "items": {
49
            "type": "object"
50
          }
51
        },
52
        "pagination": {
53
          "$ref": "#/definitions/pagination"
54
        }
55
      },
56
      "required": ["items", "pagination"]
57
    }
58
  },
59
  "required": ["status", "data"]
60
}

表单验证 Schema {#form-validation}#

示例 3：用户注册表单 Schema#

场景：网站用户注册表单验证

1
{
2
  "$schema": "http://json-schema.org/draft-07/schema#",
3
  "title": "用户注册表单",
4
  "description": "验证用户注册提交的数据",
5
  "type": "object",
6
  "properties": {
7
    "username": {
8
      "type": "string",
9
      "title": "用户名",
10
      "description": "3-20 位字母、数字或下划线",
11
      "minLength": 3,
12
      "maxLength": 20,
13
      "pattern": "^[a-zA-Z0-9_]+$"
14
    },
15
    "email": {
16
      "type": "string",
17
      "title": "邮箱地址",
18
      "format": "email",
19
      "description": "请输入有效的邮箱地址"
20
    },
21
    "password": {
22
      "type": "string",
23
      "title": "密码",
24
      "description": "至少 8 位，包含大小写字母、数字和特殊字符",
25
      "minLength": 8,
26
      "maxLength": 32,
27
      "pattern": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(?=.*[@$!%*?&])[A-Za-z\\d@$!%*?&]{8,}$"
28
    },
29
    "confirmPassword": {
30
      "type": "string",
31
      "title": "确认密码"
32
    },
33
    "phone": {
34
      "type": "string",
35
      "title": "手机号码",
36
      "pattern": "^1[3-9]\\d{9}$",
37
      "description": "请输入 11 位中国大陆手机号"
38
    },
39
    "captcha": {
40
      "type": "string",
41
      "title": "验证码",
42
      "pattern": "^[0-9A-Z]{6}$",
43
      "description": "6 位字母数字组合"
44
    },
45
    "agreeToTerms": {
46
      "type": "boolean",
47
      "title": "同意条款",
48
      "const": true
49
    },
50
    "marketingOptIn": {
51
      "type": "boolean",
52
      "title": "接收营销邮件",
53
      "default": false
54
    }
55
  },
56
  "required": ["username", "email", "password", "confirmPassword", "agreeToTerms"],
57
  "additionalProperties": false
58
}

前端验证实现：

1
import Ajv from 'ajv';
2
import addFormats from 'ajv-formats';
3

4
const ajv = new Ajv({ allErrors: true });
5
addFormats(ajv);
6

7
const validate = ajv.compile(registrationSchema);
8

9
function validateForm(formData) {
10
  const valid = validate(formData);
11

12
  if (!valid) {
13
    const errors = validate.errors.map(err => ({
14
      field: err.instancePath.slice(1),
15
      message: err.message
16
    }));
17
    return { valid: false, errors };
18
  }
19

20
  // 额外验证：密码匹配
21
  if (formData.password !== formData.confirmPassword) {
22
    return {
23
      valid: false,
24
      errors: [{
25
        field: 'confirmPassword',
26
        message: '两次输入的密码不一致'
27
      }]
28
    };
29
  }
30

31
  return { valid: true };
32
}

示例 4：电商订单表单 Schema#

1
{
2
  "$schema": "http://json-schema.org/draft-07/schema#",
3
  "title": "订单提交表单",
4
  "type": "object",
5
  "definitions": {
6
    "order_item": {
7
      "type": "object",
8
      "properties": {
9
        "productId": {
10
          "type": "string",
11
          "pattern": "^PROD-[0-9]{6}$"
12
        },
13
        "quantity": {
14
          "type": "integer",
15
          "minimum": 1,
16
          "maximum": 99
17
        },
18
        "giftWrap": {
19
          "type": "boolean",
20
          "default": false
21
        }
22
      },
23
      "required": ["productId", "quantity"]
24
    },
25
    "shipping_address": {
26
      "type": "object",
27
      "properties": {
28
        "recipientName": {
29
          "type": "string",
30
          "minLength": 2,
31
          "maxLength": 50
32
        },
33
        "phone": {
34
          "type": "string",
35
          "pattern": "^1[3-9]\\d{9}$"
36
        },
37
        "country": {
38
          "type": "string",
39
          "pattern": "^[A-Z]{2}$"
40
        },
41
        "province": { "type": "string" },
42
        "city": { "type": "string" },
43
        "district": { "type": "string" },
44
        "street": {
45
          "type": "string",
46
          "maxLength": 200
47
        },
48
        "postalCode": {
49
          "type": "string",
50
          "pattern": "^\\d{6}$"
51
        }
52
      },
53
      "required": ["recipientName", "phone", "country", "city", "street"]
54
    }
55
  },
56
  "properties": {
57
    "items": {
58
      "type": "array",
59
      "minItems": 1,
60
      "maxItems": 20,
61
      "items": {
62
        "$ref": "#/definitions/order_item"
63
      },
64
      "uniqueItems": true
65
    },
66
    "shippingAddress": {
67
      "$ref": "#/definitions/shipping_address"
68
    },
69
    "billingAddress": {
70
      "oneOf": [
71
        { "$ref": "#/definitions/shipping_address" },
72
        { "type": "null" }
73
      ]
74
    },
75
    "paymentMethod": {
76
      "type": "string",
77
      "enum": ["credit_card", "debit_card", "paypal", "bank_transfer", "cod"]
78
    },
79
    "couponCode": {
80
      "type": "string",
81
      "pattern": "^COUPON[0-9A-Z]{6}$"
82
    },
83
    "orderNotes": {
84
      "type": "string",
85
      "maxLength": 500
86
    },
87
    "deliveryTime": {
88
      "type": "string",
89
      "enum": ["asap", "morning", "afternoon", "evening"],
90
      "default": "asap"
91
    },
92
    "invoiceRequired": {
93
      "type": "boolean",
94
      "default": false
95
    }
96
  },
97
  "required": ["items", "shippingAddress", "paymentMethod"],
98
  "additionalProperties": false
99
}

配置文件 Schema {#config-files}#

示例 5：应用配置文件 Schema#

场景：Node.js 应用配置文件验证

1
{
2
  "$schema": "http://json-schema.org/draft-07/schema#",
3
  "title": "应用配置",
4
  "type": "object",
5
  "definitions": {
6
    "database_config": {
7
      "type": "object",
8
      "properties": {
9
        "host": {
10
          "type": "string",
11
          "format": "hostname",
12
          "default": "localhost"
13
        },
14
        "port": {
15
          "type": "integer",
16
          "minimum": 1,
17
          "maximum": 65535,
18
          "default": 5432
19
        },
20
        "database": {
21
          "type": "string",
22
          "minLength": 1
23
        },
24
        "username": {
25
          "type": "string"
26
        },
27
        "password": {
28
          "type": "string"
29
        },
30
        "pool": {
31
          "type": "object",
32
          "properties": {
33
            "min": {
34
              "type": "integer",
35
              "minimum": 0,
36
              "default": 2
37
            },
38
            "max": {
39
              "type": "integer",
40
              "minimum": 1,
41
              "default": 10
42
            },
43
            "idleTimeoutMillis": {
44
              "type": "integer",
45
              "minimum": 1000,
46
              "default": 30000
47
            }
48
          }
49
        },
50
        "ssl": {
51
          "type": "boolean",
52
          "default": false
53
        }
54
      },
55
      "required": ["database", "username", "password"]
56
    },
57
    "redis_config": {
58
      "type": "object",
59
      "properties": {
60
        "host": {
61
          "type": "string",
62
          "format": "hostname",
63
          "default": "localhost"
64
        },
65
        "port": {
66
          "type": "integer",
67
          "minimum": 1,
68
          "maximum": 65535,
69
          "default": 6379
70
        },
71
        "password": {
72
          "type": ["string", "null"]
73
        },
74
        "db": {
75
          "type": "integer",
76
          "minimum": 0,
77
          "maximum": 15,
78
          "default": 0
79
        },
80
        "keyPrefix": {
81
          "type": "string",
82
          "default": ""
83
        }
84
      }
85
    },
86
    "logging_config": {
87
      "type": "object",
88
      "properties": {
89
        "level": {
90
          "type": "string",
91
          "enum": ["debug", "info", "warn", "error"],
92
          "default": "info"
93
        },
94
        "format": {
95
          "type": "string",
96
          "enum": ["json", "text"],
97
          "default": "json"
98
        },
99
        "outputs": {
100
          "type": "array",
101
          "items": {
102
            "type": "string",
103
            "enum": ["console", "file", "elasticsearch"]
104
          },
105
          "default": ["console"]
106
        },
107
        "file": {
108
          "type": "object",
109
          "properties": {
110
            "path": {
111
              "type": "string"
112
            },
113
            "maxSize": {
114
              "type": "string",
115
              "pattern": "^\\d+[KMGT]B$"
116
            },
117
            "maxFiles": {
118
              "type": "integer",
119
              "minimum": 1,
120
              "default": 5
121
            }
122
          }
123
        }
124
      }
125
    }
126
  },
127
  "properties": {
128
    "app": {
129
      "type": "object",
130
      "properties": {
131
        "name": {
132
          "type": "string",
133
          "default": "my-application"
134
        },
135
        "version": {
136
          "type": "string",
137
          "pattern": "^\\d+\\.\\d+\\.\\d+$"
138
        },
139
        "env": {
140
          "type": "string",
141
          "enum": ["development", "staging", "production"],
142
          "default": "development"
143
        },
144
        "port": {
145
          "type": "integer",
146
          "minimum": 1,
147
          "maximum": 65535,
148
          "default": 3000
149
        },
150
        "host": {
151
          "type": "string",
152
          "format": "hostname",
153
          "default": "0.0.0.0"
154
        }
155
      },
156
      "required": ["version", "env"]
157
    },
158
    "database": {
159
      "$ref": "#/definitions/database_config"
160
    },
161
    "redis": {
162
      "$ref": "#/definitions/redis_config"
163
    },
164
    "logging": {
165
      "$ref": "#/definitions/logging_config"
166
    },
167
    "features": {
168
      "type": "object",
169
      "properties": {
170
        "enableCache": {
171
          "type": "boolean",
172
          "default": true
173
        },
174
        "enableRateLimit": {
175
          "type": "boolean",
176
          "default": true
177
        },
178
        "enableCors": {
179
          "type": "boolean",
180
          "default": true
181
        },
182
        "enableCompression": {
183
          "type": "boolean",
184
          "default": true
185
        }
186
      }
187
    },
188
    "rateLimit": {
189
      "type": "object",
190
      "properties": {
191
        "windowMs": {
192
          "type": "integer",
193
          "minimum": 1000,
194
          "default": 900000
195
        },
196
        "max": {
197
          "type": "integer",
198
          "minimum": 1,
199
          "default": 100
200
        }
201
      }
202
    },
203
    "cors": {
204
      "type": "object",
205
      "properties": {
206
        "origin": {
207
          "oneOf": [
208
            { "type": "string", "format": "uri" },
209
            { "type": "boolean", "const": true }
210
          ]
211
        },
212
        "methods": {
213
          "type": "array",
214
          "items": {
215
            "type": "string",
216
            "enum": ["GET", "POST", "PUT", "DELETE", "PATCH", "OPTIONS"]
217
          },
218
          "default": ["GET", "POST", "PUT", "DELETE"]
219
        },
220
        "allowedHeaders": {
221
          "type": "array",
222
          "items": { "type": "string" }
223
        },
224
        "credentials": {
225
          "type": "boolean",
226
          "default": true
227
        }
228
      }
229
    }
230
  },
231
  "required": ["app", "database"]
232
}

使用示例：

1
{
2
  "app": {
3
    "name": "ecommerce-api",
4
    "version": "1.0.0",
5
    "env": "production",
6
    "port": 3000,
7
    "host": "0.0.0.0"
8
  },
9
  "database": {
10
    "host": "db.example.com",
11
    "port": 5432,
12
    "database": "ecommerce",
13
    "username": "app_user",
14
    "password": "secure_password",
15
    "pool": {
16
      "min": 5,
17
      "max": 20,
18
      "idleTimeoutMillis": 30000
19
    },
20
    "ssl": true
21
  },
22
  "redis": {
23
    "host": "redis.example.com",
24
    "port": 6379,
25
    "password": "redis_password",
26
    "db": 0,
27
    "keyPrefix": "ecom:"
28
  },
29
  "logging": {
30
    "level": "info",
31
    "format": "json",
32
    "outputs": ["console", "file"],
33
    "file": {
34
      "path": "/var/log/app",
35
      "maxSize": "100MB",
36
      "maxFiles": 10
37
    }
38
  },
39
  "features": {
40
    "enableCache": true,
41
    "enableRateLimit": true,
42
    "enableCors": true,
43
    "enableCompression": true
44
  },
45
  "rateLimit": {
46
    "windowMs": 900000,
47
    "max": 100
48
  },
49
  "cors": {
50
    "origin": "https://example.com",
51
    "methods": ["GET", "POST", "PUT", "DELETE"],
52
    "credentials": true
53
  }
54
}

微服务通信 Schema {#microservices}#

示例 6：服务间消息 Schema#

场景：微服务架构中的事件消息

1
{
2
  "$schema": "http://json-schema.org/draft-07/schema#",
3
  "title": "服务间事件消息",
4
  "type": "object",
5
  "definitions": {
6
    "event_metadata": {
7
      "type": "object",
8
      "properties": {
9
        "eventId": {
10
          "type": "string",
11
          "format": "uuid",
12
          "description": "事件唯一标识"
13
        },
14
        "eventType": {
15
          "type": "string",
16
          "pattern": "^[a-z]+\\.[a-z]+(\\.[a-z]+)*$",
17
          "description": "事件类型（如：user.created）"
18
        },
19
        "source": {
20
          "type": "string",
21
          "description": "事件来源服务"
22
        },
23
        "timestamp": {
24
          "type": "string",
25
          "format": "date-time"
26
        },
27
        "version": {
28
          "type": "string",
29
          "pattern": "^v\\d+$",
30
          "default": "v1"
31
        },
32
        "correlationId": {
33
          "type": "string",
34
          "format": "uuid",
35
          "description": "关联 ID（用于链路追踪）"
36
        },
37
        "causationId": {
38
          "type": ["string", "null"],
39
          "format": "uuid",
40
          "description": "因果 ID（触发此事件的上游事件）"
41
        }
42
      },
43
      "required": ["eventId", "eventType", "source", "timestamp"]
44
    }
45
  },
46
  "properties": {
47
    "metadata": {
48
      "$ref": "#/definitions/event_metadata"
49
    },
50
    "data": {
51
      "type": "object",
52
      "description": "事件负载数据"
53
    },
54
    "context": {
55
      "type": "object",
56
      "properties": {
57
        "userId": {
58
          "type": ["string", "null"],
59
          "format": "uuid"
60
        },
61
        "sessionId": {
62
          "type": ["string", "null"],
63
          "format": "uuid"
64
        },
65
        "ipAddress": {
66
          "type": ["string", "null"],
67
          "format": "ipv4"
68
        },
69
        "userAgent": {
70
          "type": ["string", "null"]
71
        }
72
      }
73
    }
74
  },
75
  "required": ["metadata", "data"]
76
}

具体事件示例：

1
{
2
  "metadata": {
3
    "eventId": "550e8400-e29b-41d4-a716-446655440000",
4
    "eventType": "order.created",
5
    "source": "order-service",
6
    "timestamp": "2024-01-20T10:30:00Z",
7
    "version": "v1",
8
    "correlationId": "123e4567-e89b-12d3-a456-426614174000",
9
    "causationId": null
10
  },
11
  "data": {
12
    "orderId": "ORD-2024-000001",
13
    "userId": "USR-10001",
14
    "totalAmount": 299.99,
15
    "currency": "CNY",
16
    "status": "pending",
17
    "items": [
18
      {
19
        "productId": "PROD-001",
20
        "quantity": 2,
21
        "price": 149.995
22
      }
23
    ]
24
  },
25
  "context": {
26
    "userId": "USR-10001",
27
    "sessionId": "SES-ABC123",
28
    "ipAddress": "192.168.1.100",
29
    "userAgent": "Mozilla/5.0..."
30
  }
31
}

数据管道 Schema {#data-pipeline}#

示例 7：ETL 数据转换 Schema#

场景：数据管道中的数据格式定义

1
{
2
  "$schema": "http://json-schema.org/draft-07/schema#",
3
  "title": "ETL 数据记录",
4
  "type": "object",
5
  "definitions": {
6
    "data_quality": {
7
      "type": "object",
8
      "properties": {
9
        "score": {
10
          "type": "number",
11
          "minimum": 0,
12
          "maximum": 100
13
        },
14
        "issues": {
15
          "type": "array",
16
          "items": {
17
            "type": "object",
18
            "properties": {
19
              "field": { "type": "string" },
20
              "issue": { "type": "string" },
21
              "severity": {
22
                "type": "string",
23
                "enum": ["low", "medium", "high", "critical"]
24
              }
25
            }
26
          }
27
        },
28
        "validatedAt": {
29
          "type": "string",
30
          "format": "date-time"
31
        }
32
      }
33
    }
34
  },
35
  "properties": {
36
    "recordId": {
37
      "type": "string",
38
      "format": "uuid"
39
    },
40
    "sourceSystem": {
41
      "type": "string",
42
      "enum": ["salesforce", "sap", "oracle", "mysql", "mongodb"]
43
    },
44
    "extractedAt": {
45
      "type": "string",
46
      "format": "date-time"
47
    },
48
    "transformedAt": {
49
      "type": ["string", "null"],
50
      "format": "date-time"
51
    },
52
    "loadedAt": {
53
      "type": ["string", "null"],
54
      "format": "date-time"
55
    },
56
    "status": {
57
      "type": "string",
58
      "enum": ["extracted", "transforming", "transformed", "loading", "loaded", "failed"]
59
    },
60
    "data": {
61
      "type": "object"
62
    },
63
    "quality": {
64
      "$ref": "#/definitions/data_quality"
65
    },
66
    "metadata": {
67
      "type": "object",
68
      "properties": {
69
        "version": {
70
          "type": "string"
71
        },
72
        "checksum": {
73
          "type": "string",
74
          "pattern": "^[a-f0-9]{64}$"
75
        },
76
        "size": {
77
          "type": "integer",
78
          "minimum": 0
79
        },
80
        "encoding": {
81
          "type": "string",
82
          "default": "utf-8"
83
        }
84
      }
85
    },
86
    "errors": {
87
      "type": "array",
88
      "items": {
89
        "type": "object",
90
        "properties": {
91
          "code": { "type": "string" },
92
          "message": { "type": "string" },
93
          "timestamp": { "type": "string", "format": "date-time" }
94
        }
95
      }
96
    }
97
  },
98
  "required": ["recordId", "sourceSystem", "extractedAt", "status", "data"]
99
}

GraphQL 集成 Schema {#graphql}#

示例 8：GraphQL 响应验证 Schema#

1
{
2
  "$schema": "http://json-schema.org/draft-07/schema#",
3
  "title": "GraphQL 响应",
4
  "type": "object",
5
  "definitions": {
6
    "graphql_error": {
7
      "type": "object",
8
      "properties": {
9
        "message": {
10
          "type": "string"
11
        },
12
        "locations": {
13
          "type": "array",
14
          "items": {
15
            "type": "object",
16
            "properties": {
17
              "line": { "type": "integer" },
18
              "column": { "type": "integer" }
19
            }
20
          }
21
        },
22
        "path": {
23
          "type": "array",
24
          "items": {
25
            "oneOf": [
26
              { "type": "string" },
27
              { "type": "integer" }
28
            ]
29
          }
30
        },
31
        "extensions": {
32
          "type": "object",
33
          "properties": {
34
            "code": { "type": "string" },
35
            "classification": { "type": "string" }
36
          }
37
        }
38
      },
39
      "required": ["message"]
40
    }
41
  },
42
  "properties": {
43
    "data": {
44
      "type": ["object", "null"]
45
    },
46
    "errors": {
47
      "type": "array",
48
      "items": {
49
        "$ref": "#/definitions/graphql_error"
50
      }
51
    },
52
    "extensions": {
53
      "type": "object"
54
    }
55
  }
56
}

事件驱动架构 Schema {#event-driven}#

示例 9：领域事件 Schema#

场景：DDD 中的领域事件定义

1
{
2
  "$schema": "http://json-schema.org/draft-07/schema#",
3
  "title": "领域事件",
4
  "type": "object",
5
  "definitions": {
6
    "money": {
7
      "type": "object",
8
      "properties": {
9
        "amount": {
10
          "type": "number",
11
          "minimum": 0
12
        },
13
        "currency": {
14
          "type": "string",
15
          "pattern": "^[A-Z]{3}$"
16
        }
17
      },
18
      "required": ["amount", "currency"]
19
    }
20
  },
21
  "oneOf": [
22
    {
23
      "title": "订单创建事件",
24
      "properties": {
25
        "eventId": { "type": "string", "format": "uuid" },
26
        "eventType": { "const": "OrderCreated" },
27
        "aggregateId": { "type": "string" },
28
        "occurredOn": { "type": "string", "format": "date-time" },
29
        "payload": {
30
          "type": "object",
31
          "properties": {
32
            "orderId": { "type": "string" },
33
            "customerId": { "type": "string" },
34
            "items": {
35
              "type": "array",
36
              "items": {
37
                "type": "object",
38
                "properties": {
39
                  "productId": { "type": "string" },
40
                  "quantity": { "type": "integer", "minimum": 1 },
41
                  "price": { "$ref": "#/definitions/money" }
42
                }
43
              }
44
            },
45
            "totalAmount": { "$ref": "#/definitions/money" }
46
          }
47
        }
48
      },
49
      "required": ["eventId", "eventType", "aggregateId", "occurredOn", "payload"]
50
    },
51
    {
52
      "title": "订单支付事件",
53
      "properties": {
54
        "eventId": { "type": "string", "format": "uuid" },
55
        "eventType": { "const": "OrderPaid" },
56
        "aggregateId": { "type": "string" },
57
        "occurredOn": { "type": "string", "format": "date-time" },
58
        "payload": {
59
          "type": "object",
60
          "properties": {
61
            "orderId": { "type": "string" },
62
            "paymentId": { "type": "string" },
63
            "paymentMethod": { "type": "string" },
64
            "paidAmount": { "$ref": "#/definitions/money" },
65
            "paidAt": { "type": "string", "format": "date-time" }
66
          }
67
        }
68
      },
69
      "required": ["eventId", "eventType", "aggregateId", "occurredOn", "payload"]
70
    },
71
    {
72
      "title": "订单取消事件",
73
      "properties": {
74
        "eventId": { "type": "string", "format": "uuid" },
75
        "eventType": { "const": "OrderCancelled" },
76
        "aggregateId": { "type": "string" },
77
        "occurredOn": { "type": "string", "format": "date-time" },
78
        "payload": {
79
          "type": "object",
80
          "properties": {
81
            "orderId": { "type": "string" },
82
            "reason": { "type": "string" },
83
            "cancelledBy": { "type": "string" },
84
            "cancelledAt": { "type": "string", "format": "date-time" }
85
          }
86
        }
87
      },
88
      "required": ["eventId", "eventType", "aggregateId", "occurredOn", "payload"]
89
    }
90
  ]
91
}

总结#

本文提供了 9 个来自真实项目的 JSON Schema 示例：

REST API：用户 API 响应、分页列表
表单验证：用户注册、订单提交
配置文件：应用配置
微服务：服务间消息
数据管道：ETL 记录
GraphQL：响应验证
事件驱动：领域事件

最佳实践总结：

使用 definitions 复用：避免重复定义
添加详细描述：便于理解和文档化
使用 $ref 引用：保持 Schema 模块化
提供示例数据：帮助理解和使用
版本控制：使用 $id 管理 Schema 版本

相关资源：

JSON Schema Generator 工具 - 在线生成 Schema
JSON Schema 完整指南 - 语法基础
JSON Schema 最佳实践 - 设计技巧
JSON Schema 常见问题 - 故障排除

使用这些示例作为起点，根据您的具体需求调整和扩展 Schema！