---
title: "在 collection JSON schema 中使用 minItems/maxItems"
description: "要让你的 collection JSON schema 更可靠，请使用 minItems 和 maxItems，这样你才能信任你的 API。"
canonical: https://oozou.com/til/use-minitems-maxitems-in-collection-json-schemas-1
locale: zh-Hans
date: 2020-10-13
topic: ruby-on-rails
---

# 在 collection JSON schema 中使用 minItems/maxItems

> 要让你的 collection JSON schema 更可靠，请使用 minItems 和 maxItems，这样你才能信任你的 API。

Published: 2020-10-13 · Topic: [ruby on rails](https://oozou.com/zh-Hans/til-topics/ruby-on-rails) ([markdown](https://oozou.com/zh-Hans/til-topics/ruby-on-rails.md))

要让你的 collection JSON schema 更可靠，请使用 *minItems* 和 *maxItems*，这样你才能信任你的 API。

```json
{
  "type": "array",
  "minItems": 1,
  "items": {
    "$ref": "subscription_notification.json"
  }
}
```

而不是

```json
{
  "type": "array",
  "items": {
    "$ref": "subscription_notification.json"
  }
}
```

如果你的 API 返回 *[]* 空数组，当你在 spec 中做断言时，后面那个 schema 仍然会通过。

```ruby
expect(response).to match_response_schema(:subscription_notifications)
```

但前面那个就不会

```bash
The property '#/' did not contain a minimum number of items 1 in schema
```

\<https://json-schema.org/understanding-json-schema/reference/array.html>

# 认识 JSON Schema 数组

JSON Schema 数组对于定义 JSON 数据中数组的结构和限制非常重要。JSON 的数组是一组有序的值，而 JSON Schema 数组则用来指定这些数组的特性和限制。通过 JSON Schema 数组，你可以验证数组的长度、内容和唯一性，确保数据符合预期的格式。当你需要对数据结构强制执行特定规则时，例如要求一定数量的元素，或确保所有元素都是特定类型，这就特别有用。

# 数组的验证关键字

JSON Schema 提供了几个可以用来限制数组的验证关键字。这些关键字包括：

- items：指定数组中每个元素的 schema。
- additionalItems：指定数组中超出第一个 items schema 的额外元素的 schema。
- minItems 和 maxItems：指定数组中元素数量的下限和上限。
- uniqueItems：指定数组中的元素是否必须唯一。
- contains：指定数组中至少要有一个元素符合的 schema。
- minContains 和 maxContains：指定数组中必须符合 contains schema 的元素数量下限和上限。

这些关键字让你可以对数组定义精确的限制，确保数据符合要求。

# 限制数组长度

JSON Schema 提供了几种限制数组长度的方式。minItems 和 maxItems 关键字可以用来指定数组中元素数量的下限和上限。例如：\{ "type": "array", "minItems": 2, "maxItems": 5 } 这个 schema 规定数组必须至少有 2 个元素、最多 5 个元素。使用这些关键字，你就能确保数组长度落在期望的范围内，避免元素太少或太多的问题。

# 数组验证的最佳实践

用 JSON Schema 验证数组时，建议搭配多个验证关键字，确保数组符合所需的限制。比如，你可以用 items 指定数组中每个元素的 schema，并用 minItems 和 maxItems 指定数组中元素数量的下限和上限。

如果数据有唯一性需求，也建议使用 uniqueItems 关键字来确保数组中的元素不重复。把这些关键字组合起来，你就能创建一个稳健的 schema，彻底验证数组的结构和内容。

# 使用示例

以下是几个 JSON Schema 数组的使用示例：

- **验证用户 ID 列表**：你可以用像这样的 schema 来验证用户 ID 列表：

```
{ "type": "array", 
"items": {"type": "integer"}, 
"minItems": 1, "maxItems": 10 } 
```

- **验证产品名称列表**：你可以用像这样的 schema 来验证产品名称列表：

```
{ "type": "array", "items": {"type": "string"}, "minItems": 1, "maxItems": 5, "uniqueItems": true } 
```

- **验证地址列表**：你可以用像这样的 schema 来验证地址列表：

```
{ "type": "array", "items": { "type": "object", "properties": { "street": {"type": "string"}, "city": {"type": "string"}, "state": {"type": "string"}, "zip": {"type": "string"} }, "required": ["street", "city", "state", "zip"] }, "minItems": 1, "maxItems": 10 } 
```

这些示例说明了如何把 JSON Schema 数组应用到不同类型的数据上，确保数组符合指定的限制和需求。

---

Contact OOZOU: hello@oozou.com · +66 2544 0000 · https://oozou.com/zh-Hans/contact

More for AI agents: https://oozou.com/llms.txt · every page has a markdown twin at its URL plus ".md"