---
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-Hant
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-Hant/til-topics/ruby-on-rails) ([markdown](https://oozou.com/zh-Hant/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-Hant/contact

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