JSON Toolkit

אימות YAML באמצעות JSON Schema: רשת הביטחון של קובצי התצורה

שורה תחתונה: קובץ YAML שנפרסר ללא שגיאות אינו בהכרח קובץ נכון: עבור מנתח YAML 1.1 הערך country: NO אינו מחרוזת, והערך version: 1.10 הופך בשקט למספר העשרוני 1.1. המדריך מסביר מדוע JSON Schema יכול לאמת YAML, את מסלולי ה-CLI והעורך להקמה, כיצד סכימה אחת הייתה תופסת את תקרית קוד המדינה הנורווגית האמיתית, ואת שלוש מגבלות האימות בסכימה.

בינוניכ-6 דקות קריאהפורסם 2026-11-13עודכן 2026-11-13
דיאגרמה הממחישה אימות קובצי תצורת YAML באמצעות JSON Schema

מסקנה: YAML 1.2 הוא תת־קבוצה־על מחמירה של JSON, ולכן JSON Schema מאמת את מבנה הנתונים לאחר הפרסור, לא את פורמט הקובץ — כתבו את הסכימה פעם אחת והיא תכסה גם נתוני JSON וגם YAML. בדיוק מסיבה זו הוא מסוגל לתפוס תקריות שבהן המנתח משנה טיפוס בשקט.

yaml.safe_load ללא שגיאות מוכיח רק שהקובץ הוא YAML תקין תחבירית. הוא אינו מוכיח ש-country: NO עדיין מחרוזת — תחת מנתח YAML 1.1 היא כבר false זמן רב לפני שהקוד שלכם רואה את הקובץ.

אחד: פרסור ללא שגיאות ≠ תצורה נכונה — קודם תקרית אמיתית

צוות מסחר אלקטרוני הוסיף את נורווגיה לרשימת ארצות המשלוח: שורה אחת, NO, ברשימה בתוך group_vars של Ansible. נסקר, אומת, הופעל בייצור. שבוע לאחר מכן: אפס הזמנות מנורווגיה — קובץ ה-JSON בשרתים הכיל "DK", false, "SE". Ansible מפרסר את קובצי המשתנים שלו עם PyYAML, מנתח YAML 1.1: הערך NO הפך לבוליאני false כבר בזמן קריאת הקובץ, ומסנן ה-to_json כתב זאת בנאמנות. התבנית התממשקה, ה-JSON היה תקין, אף אחד לא התלונן — רק שירות ה-checkout המשיך לדחות כל לקוח נורווגי, כי NO לא היה ברשימה.

המשותף לתקריות מהסוג הזה: כל הכלים התחביריים בירוק בעוד שכבת הנתונים כבר שגויה. הטבלה הבאה מציגה את שחיקת הטיפוסים שנמדדה עם PyYAML 6.0.3; מנתחי YAML 1.2 מתקנים רק חלק ממנה:

כותבים YAML 1.1 קורא YAML 1.2 קורא רציתם
country: NO false "NO" "NO"
version: 1.10 מספר עשרוני 1.1 מספר עשרוני 1.1 "1.10"
zip: 02134 אוקטלי 1116 עשרוני 2134 "02134"
mode: 0755 עשרוני 493 עשרוני 755 493 או "0755"
ports: ["22:22"] שישיני 1342 "22:22" "22:22"

התרופה היסודית: לשים מירכאות סביב כל מחרוזת שנראית כמו קוד. אבל מירכאות נשענות על זיכרון אנושי; סכימה נשענת על בדיקת מכונה — לכן YAML ראוי ל-JSON Schema.

שניים: מדוע JSON Schema יכול לשלוט ב-YAML

מפרט YAML 1.2 אומר זאת בפירוש: המטרה העיקרית של 1.2 הייתה להפוך את YAML לתת־קבוצה־על מחמירה של JSON, ומנתח 1.2 קורא JSON רגיל ללא שינוי. שני הפורמטים מפורסרים לאותן מבני נתונים, ולכן סיומת הקובץ חסרת משמעות עבור מאמת. צינור העבודה כולו בן שלושה צעדים:

  1. פרסור קובץ ה-YAML לאובייקטים ומערכים;
  2. טעינת ה-JSON Schema;
  3. אימות הנתונים מול הסכימה — שגיאות או עמידה.

שימו לב שצעד אחד אינו דורש סריאליזציה של ה-YAML לטקסט JSON ופרסור חוזר; ספריית ה-YAML של השפה שלכם מעבירה את המבנה ישירות למאמת. את הסכימה עצמה אפשר לכתוב גם ב-YAML (yq -P schema.json > schema.yaml ממיר בפקודה אחת), אבל לשמור אותה כ-JSON היא הבחירה הבטוחה ביותר: תאימות כלים טובה יותר, וכל הסכמות בקטלוג schemastore.org הן JSON.

שלושה: שלושה מסלולי CLI שעובדים כבר היום

ניקח config.yaml שבו הסכימה מחייבת name ו-version, כופה צורת semver ורשימת countries כמערך מחרוזות בן שתי אותיות גדולות:

# config.yaml
name: checkout
version: "1.4.2"
countries:
  - DK
  - NO
  - SE

Python (jsonschema + PyYAML):

import json, yaml
from jsonschema import validate

data = yaml.safe_load(open("config.yaml", encoding="utf-8"))
schema = json.load(open("schema.json", encoding="utf-8"))
validate(instance=data, schema=schema)

Node (js-yaml + Ajv):

import Ajv from "ajv";
import yaml from "js-yaml";
import fs from "fs";

const schema = JSON.parse(fs.readFileSync("schema.json", "utf8"));
const data = yaml.load(fs.readFileSync("config.yaml", "utf8"));
const validate = new Ajv().compile(schema);
if (!validate(data)) console.error(validate.errors);

צינור טהור (yq + ajv-cli):

yq -o=json config.yaml | ajv validate -s schema.json -d -
# או check-jsonschema, שמקבל YAML ישירות
pip install check-jsonschema
check-jsonschema --schemafile schema.json config.yaml

שלושת המסלולים שונים רק בצעד הפרסור: השניים הראשונים מפורשים, בן שתי שורות; הצינור זורם בזרם אחד; ו-check-jsonschema מבצע המרת YAML→JSON בפנים. קובץ הסכימה זהה לשלושתם.

ארבעה: אימות בזמן אמת בעורך: modeline ו-SchemaStore

הרחבת ה-YAML של Red Hat (מבוססת yaml-language-server) מותקנת כ-30 מיליון פעמים ב-VS Code ותומכת ב-JSON Schema draft-04/07/2019-09/2020-12. שלוש דרכי חיבור:

# אפשרות 1: modeline — השורה הראשונה של הקובץ מצביעה על הסכימה
# yaml-language-server: $schema=./schema.json
name: checkout
// אפשרויות 2 ו-3: .vscode/settings.json, לפי שם קובץ או glob
{
  "yaml.schemas": {
    "./schema.json": ["config/*.yaml", "*.config.yaml"],
    "https://json.schemastore.org/github-workflow.json": ".github/workflows/*.yml"
  }
}

ההגדרה yaml.schemaStore.enable פעילה כברירת מחדל: קבצים מוכרים כמו package.json, זרימות GitHub או docker-compose מקושרים אוטומטית לקטלוג schemastore.org, בלי שום תצורה. שדות ה-description של הסכימה הופכים לעזרי השלמה אוטומטית וטיפים, והתכונות ה-required החסרות מסומנות בקו אדום — שגיאות תצורה עוברות מ"דיבוג אחרי הפריסה" אל "ברגע שאתם מקלידים". זה גם מסביר מדוע SchemaStore ולא "תקן סכימות ל-YAML": ל-YAML אין תקן סכימות רשמי, ו-JSON Schema הוא התקן דה־פקטו.

חמישה: איך סכימה הייתה תופסת את בעיית נורווגיה

נחזור לתקרית ה-NO שבסעיף הראשון. ניתן ל-countries סכימה ברמת הפריט:

{
  "type": "object",
  "required": ["name", "version", "countries"],
  "properties": {
    "countries": {
      "type": "array",
      "items": { "type": "string", "pattern": "^[A-Z]{2}$" }
    }
  }
}

הערך false ש-PyYAML מייצר אינו מחרוזת, ולכן type: string נופל מיד; גם אם מנתח כלשהו קרא אותה "no" באותיות קטנות, ה-pattern עוצר אותה. לשליטה מהודקת יותר הוסיפו רשימה לבנה של enum. אותה סכימה רצה ב-CI דרך מסלולי ה-CLI שבסעיף שלושה ובעורך דרך ה-modeline שבסעיף ארבעה — חוזה אחד בשני הקצוות.

חלוקת העבודה עם yamllint ראויה למשפט: כלל ה-truthy של yamllint (מתקבלים רק true/false, כל איות בוליאני אחר מדווח) שולט בסגנון הכתיבה ותופס flag: yes בשכבת ה-lint; JSON Schema שולט בצורת הנתונים, ללא קשר למנתח. הצוות מהתקרית אימץ לבסוף את שלושתם: מירכאות על מחרוזות, yamllint truthy בצינור, ובדיקת מחרוזת בן שתי אותיות בתבנית. שתי שכבות ההגנה אינן חופפות; הן משלימות זו את זו.

שישה: אימות צובר של מניפסטים של Kubernetes

ממשק ה-API של Kubernetes עצמו מתואר ב-OpenAPI, ופרויקט kubernetes-json-schema ממיר אותו ל-JSON Schema תקני. Kubeconform משתמש במאגר זה לאימות צובר: על מחשב נייד בן ארבעה ליבות, 35,139 קבצים ו-50,714 משאבים עם kubeconform -ignore-missing-schemas -n 8 -summary מסתיימים ב-6.7 שניות, לעומת 35 שניות של kubeval על אותה משימה. צעד ה-Helm הסטנדרטי: מימוש קודם, אימות אחר כך:

helm template my-app ./charts/my-app > rendered.yaml
kubeconform -strict -summary -kubernetes-version 1.28.0 rendered.yaml

-strict דוחה שדות שאינם מוגדרים בסכימה (שגיאות הקלדה נראות מוקדם); משאבי CRD אפשר לדלג עם -ignore-missing-schemas או לחבר מאגר מותאם דרך -schema-location.

שבעה: מה שאימות בסכימה אינו יכול: שלוש מגבלות

  1. שחיקת גרסת המנתח מתרחשת בצעד הפרסור. הסכימה רואה רק את תוצאת הפרסור: הערך NO ש-PyYAML קרא הוא כבר false, והסכימה יכולה רק לכלוא את הערך השגוי הזה בעזרת type/pattern. התרופה היסודית נשארות המירכאות; אל תצפו מסכימה לתקן מנתח.
  2. שגיאות לוגיות מחוץ להיקף. שגיאת הקלדה ב-selector או selector של K8s המצביע על תווית לא קיימת — הסכימה יודעת צורות, לא סמנטיקה. זהו תחום של admission webhooks, מדיניות OPA או kubectl apply --dry-run=server.
  3. מפתחות כפולים מנצחים בשקט. מנתחי YAML רבים מקבלים מפתחות כפולים ללא אזהרה (האחרון מנצח), כך שהסכימה מקבלת נתונים שאיבדו כבר מפתח. כלל ה-key-duplicates של yamllint או ווקים של פרסור נותרים הגלאים.

רשימת בדיקה לפני פריסה: מירכאות על מחרוזות דמויות קוד → הריצת yamllint (truthy + key-duplicates) → אימות JSON Schema הן ב-CI והן בעורך → למשאבי קלאסטר הוסיפו גם --dry-run=server. עם ארבעה צעדים אלה, תקרית נורווגיה שבסעיף הראשון לא שורדת את הצעד השני של הצינור.

FAQ

האם JSON Schema יכול לאמת קובצי YAML ישירות?

כן — אך הוא מאמת את הנתונים אליהם הקובץ מפורסר, לא את הקובץ עצמו. YAML 1.2 הוא תת־קבוצה־על מחמירה של JSON, שניהם מפורסרים לאותן מבנים, ולכן סכימה אחת משרתת גם JSON וגם YAML. בחרו אחד מארבעה מסלולים — Python, Node, צינור yq או check-jsonschema — בלי להמיר פורמטים ידנית.

מהו SchemaStore וכיצד משתמשים בו?

schemastore.org הוא קטלוג של JSON Schema (catalog.json) המאגד סכמות של מאות קובצי תצורה מוכרים: package.json, זרימות GitHub, docker-compose ועוד. עורכים עם תמיכה ב-YAML/JSON מקשרים קבצים לקטלוג אוטומטית, או שאפשר למפות URL ידנית ב-yaml.schemas. גם את הסכימה של הפרויקט שלכם אפשר להגיש לקטלוג.

האם yamllint ו-JSON Schema מכפילים זה את זה?

לא. yamllint בודק סגנון כתיבה (הזחה, אורך שורות, truthy, מפתחות כפולים) ברמת הטקסט; JSON Schema בודק מבנה נתונים (טיפוסים, required, enum, pattern) ברמת הנתונים. רשימת התיקונים של תקרית נורווגיה השתמשה בשניהם: כלל truthy תופס איותים כמו flag: yes, בעוד הסכימה תופסת ערך false שהגיע למערך מחרוזות.

עבור Kubernetes: kubeconform או kubectl dry-run?

שני מקצועות שונים. Kubeconform עובד ללא חיבור ובאצווה, בלי קלאסטר, מקומו ב-CI לתפיסת שגיאות מבניות; dry-run=server מדבר עם שרת API אמיתי וחושף בעיות admission webhook ומכסות, אבל דורש גישה לקלאסטר. השילוב הסטנדרטי: kubeconform ב-CI, ואז מעבר --dry-run=server לפני פריסה — שמרו על שתי השכבות.


אחרי כתיבת הסכימה, הדביקו את ה-JSON שהומר מה-YAML שלכם במאמת JSON מקוון כדי לראות שגיאות קודם; לכתיבת מילות מפתח של הסכימה ראו מדריך JSON Schema; כדי להחזיק סכימה תחת שמירת בדיקות CI קראו בדיקת חוזים ב-JSON Schema; להמרת JSON↔YAML יומיומית השתמשו בממיר JSON YAML XML.