JSONL Schema 驗證:確保資料品質

使用 JSON Schema 驗證 JSONL 檔案的完整指南。學習定義 Schema、在 Python 和 Node.js 中驗證記錄、在 CI/CD 管線中自動化檢查,以及診斷常見驗證錯誤。

最後更新:2026 年 2 月

為什麼 JSONL 檔案需要 Schema 驗證

JSONL(JSON Lines)檔案廣泛用於日誌擷取、機器學習資料集、API 批次處理和資料管線。由於每一行都是獨立的 JSON 物件,因此沒有內建機制來強制所有記錄保持一致的結構。一行格式錯誤的資料、一個遺漏的必要欄位或一個意外的資料類型,都可能悄無聲息地破壞下游處理、中斷模型訓練,或導致 API 批次作業在執行過程中失敗。

Schema 驗證透過定義每筆記錄必須滿足的正式契約來解決這個問題。JSON Schema 是描述 JSON 資料結構、類型和約束條件的行業標準。在資料進入管線之前,對 JSONL 檔案的每一行進行 JSON Schema 驗證,可以及早發現錯誤、減少除錯時間,並大規模保證資料品質。本指南將引導您完成整個流程,從撰寫第一個 Schema 到將驗證整合到自動化 CI/CD 工作流程。

JSONL 的 JSON Schema 基礎

JSON Schema 是一種宣告式語言,讓您描述 JSON 物件的預期結構。您可以定義哪些欄位是必要的、它們必須具備什麼資料類型、可接受的值範圍、字串模式等。當應用於 JSONL 驗證時,同一個 Schema 會對檔案中的每一行進行檢查。這確保所有記錄共享一致的結構,這對可靠的資料處理至關重要。

以下是使用者事件記錄的 JSON Schema 範例。它要求 id(整數)、event(來自固定集合的字串)、timestamp(ISO 8601 格式),以及一個可選的 metadata 物件。additionalProperties 欄位設定為 false,以拒絕任何意外的鍵。

定義 JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"required": ["id", "event", "timestamp"],
"properties": {
"id": {
"type": "integer",
"minimum": 1
},
"event": {
"type": "string",
"enum": ["click", "view", "purchase", "signup"]
},
"timestamp": {
"type": "string",
"format": "date-time"
},
"metadata": {
"type": "object",
"properties": {
"source": { "type": "string" },
"campaign": { "type": "string" }
},
"additionalProperties": false
}
},
"additionalProperties": false
}

以下是一個記錄與上述 Schema 相符的 JSONL 檔案。每一行都是一個獨立的 JSON 物件,代表一個使用者事件。請注意,可選的 metadata 欄位在某些行中存在而在其他行中不存在,根據 Schema 這兩種情況都是有效的。

範例 JSONL 資料
{"id":1,"event":"click","timestamp":"2026-02-15T10:30:00Z","metadata":{"source":"google","campaign":"spring"}}
{"id":2,"event":"purchase","timestamp":"2026-02-15T11:00:00Z"}
{"id":3,"event":"view","timestamp":"2026-02-15T11:15:00Z","metadata":{"source":"direct"}}
{"id":4,"event":"signup","timestamp":"2026-02-15T12:00:00Z"}

驗證 JSONL 檔案:Python、Node.js 和 CLI

有幾種成熟的工具可以對 JSON Schema 驗證 JSONL。最佳選擇取決於您現有的技術棧。Python 開發者通常使用 jsonschema 函式庫,JavaScript 開發者使用 Ajv,而偏好 Shell 腳本的團隊可以使用命令列驗證器。以下展示了這三種方法。

jsonschema 函式庫是最流行的 Python JSON Schema 驗證套件。使用 pip install jsonschema 安裝。以下腳本逐行讀取 JSONL 檔案,驗證每筆記錄,並收集所有錯誤及其行號,方便除錯。

Python 搭配 jsonschema
import json
from jsonschema import validate, ValidationError
def validate_jsonl(file_path, schema):
errors = []
with open(file_path, 'r', encoding='utf-8') as f:
for line_num, line in enumerate(f, start=1):
line = line.strip()
if not line:
continue
try:
record = json.loads(line)
validate(instance=record, schema=schema)
except json.JSONDecodeError as e:
errors.append({
'line': line_num,
'error': f'Invalid JSON: {e.msg}'
})
except ValidationError as e:
errors.append({
'line': line_num,
'error': e.message,
'path': list(e.absolute_path)
})
return errors
# Load schema and validate
with open('schema.json', 'r') as f:
schema = json.load(f)
errors = validate_jsonl('data.jsonl', schema)
if errors:
print(f'Found {len(errors)} validation errors:')
for err in errors:
print(f" Line {err['line']}: {err['error']}")
else:
print('All records are valid!')

Ajv(Another JSON Schema Validator)是 JavaScript 最快的 JSON Schema 驗證器。使用 npm install ajv ajv-formats 安裝。ajv-formats 套件新增了對 date-time 等格式關鍵字的支援。此腳本逐行串流讀取 JSONL 檔案,以提高記憶體效率。

Node.js 搭配 Ajv
guide-jsonl-schema-validation.jsonlSchemaValidation.methods.nodejs.code

對於快速的一次性檢查或基於 Shell 的工作流程,您可以結合使用 jq 和 ajv-cli。以下方法將 JSONL 檔案拆分為單獨的 JSON 物件,並對每個物件進行 Schema 驗證。當您不想撰寫自訂腳本時,這非常有用。

命令列驗證
# Install ajv-cli globally
npm install -g ajv-cli ajv-formats
# Validate each line of a JSONL file against a schema
line_num=0
errors=0
while IFS= read -r line; do
line_num=$((line_num + 1))
if [ -z "$line" ]; then continue; fi
echo "$line" | ajv validate -s schema.json -d /dev/stdin --all-errors 2>/dev/null
if [ $? -ne 0 ]; then
echo " Error on line $line_num"
errors=$((errors + 1))
fi
done < data.jsonl
if [ $errors -eq 0 ]; then
echo "All records are valid!"
else
echo "Found $errors invalid records"
exit 1
fi

在 CI/CD 管線中自動化驗證

手動驗證適用於小型資料集,但生產環境的工作流程需要自動化。透過將 JSONL Schema 驗證整合到 CI/CD 管線中,每次資料變更都會在到達生產環境之前被檢查。這可以防止不良資料進入資料倉庫、中斷模型訓練或破壞 API 批次作業。以下是一個 GitHub Actions 工作流程,在每次 push 和 pull request 時驗證 JSONL 檔案。

GitHub Actions 工作流程
guide-jsonl-schema-validation.jsonlSchemaValidation.automation.code

此工作流程僅在 data 目錄內的 JSONL 檔案變更時觸發,保持 CI 快速運行。驗證腳本載入一次 Schema,然後遞迴檢查所有找到的 JSONL 檔案。如果任何記錄驗證失敗,工作流程會以非零代碼退出,阻止合併。您可以擴展此模式,為不同檔案類型新增多個 Schema、在失敗時發送 Slack 通知,或將驗證報告作為建構產出物上傳。

常見驗證錯誤及修復方法

當您首次對現有 JSONL 資料集啟用 Schema 驗證時,通常會發現隱藏的資料品質問題。以下是三種最常見的驗證錯誤及其解決方法。

類型不匹配

類型不匹配發生在欄位包含錯誤類型的值時。最常見的情況是數值 ID 被儲存為字串,這通常發生在資料從試算表或 CSV 檔案匯出時。修復方法是在 ETL 過程中將值轉換為正確的類型,或者如果兩種類型都有效,則更新 Schema 以接受多種類型。

範例:ID 為字串而非整數
// Schema expects: { "type": "integer" }
// Invalid record:
{"id": "42", "event": "click", "timestamp": "2026-02-15T10:00:00Z"}
// Fix: cast to integer during processing
// Python: record['id'] = int(record['id'])
// JS: record.id = Number(record.id)

缺少必要欄位

缺少必要欄位錯誤表示記錄缺少 Schema 的 required 陣列中列出的屬性。這通常發生在上游系統變更輸出格式或可選欄位被錯誤地遺漏時。在資料管線中新增預設值處理,或者如果該欄位確實不一定存在,則更新 Schema 使其成為可選。

範例:缺少 timestamp 欄位
// Schema requires: ["id", "event", "timestamp"]
// Invalid record (no timestamp):
{"id": 5, "event": "view"}
// Fix option 1: add default timestamp
// Python: record.setdefault('timestamp', datetime.utcnow().isoformat() + 'Z')
// Fix option 2: make timestamp optional in schema
// Change required to: ["id", "event"]

意外的額外屬性

當 Schema 中的 additionalProperties 設定為 false 時,任何未在 properties 中明確列出的欄位都會觸發驗證錯誤。這很嚴格但有助於捕獲拼寫錯誤和資料洩漏。如果您有意允許額外欄位,請將 additionalProperties 設定為 true,或使用 patternProperties 定義允許的屬性名稱模式。

範例:記錄中的未知欄位
// Schema has: "additionalProperties": false
// Invalid record (extra field "user_agent"):
{"id": 6, "event": "click", "timestamp": "2026-02-15T14:00:00Z", "user_agent": "Mozilla/5.0"}
// Fix option 1: remove the extra field before validation
// Fix option 2: add "user_agent" to schema properties
// Fix option 3: set "additionalProperties": true

線上驗證 JSONL 檔案

想要無需撰寫腳本就能快速檢查您的 JSONL 資料嗎?使用我們的免費瀏覽器工具來驗證、格式化和檢查 JSONL 檔案。所有處理都在您的瀏覽器本機進行,因此您的資料保持私密。

立即驗證您的 JSONL 檔案

上傳您的 JSONL 檔案,即時檢查語法錯誤、結構問題和格式問題。無需伺服器上傳,100% 私密。

常見問題

JSONL Schema 驗證 — 使用 JSON Schema 驗證 JSON Lines | jsonl.co