JSON Schema দিয়ে YAML ভ্যালিডেশন: কনফিগ ফাইলের সেফটি নেট
সংক্ষেপে: যে YAML ফাইল এরর ছাড়া parse হয় সে সঠিক ফাইল নয়: YAML 1.1 পার্সারের কাছে country: NO স্ট্রিং নয়, আর version: 1.10 নীরবে float 1.1 হয়ে যায়। এই গাইড ব্যাখ্যা করে কেন JSON Schema দিয়ে YAML ভ্যালিডেট করা যায়, CLI ও এডিটরে সেটআপের পথগুলো, একটি schema কীভাবে নরওয়ের দেশের কোডের বাস্তব ঘটনাটি ধরতে পারত, এবং schema ভ্যালিডেশনের তিনটি সীমাবদ্ধতা।

উপসংহার: YAML 1.2 হলো JSON-এর কঠোর সুপারসেট, তাই JSON Schema পার্স-পরবর্তী ডেটা স্ট্রাকচার ভ্যালিডেট করে, ফাইল ফরম্যাট নয় — schema একবার লিখুন, এটি JSON ও YAML দুটো ডেটাই কভার করে। এ জন্যই পার্সার নীরবে টাইপ বদলালে এটি ধরে ফেলতে পারে।
yaml.safe_load-এ এরর না থাকা শুধু প্রমাণ করে ফাইলটি বৈধ YAML। এটি প্রমাণ করে না যেcountry: NOএখনো স্ট্রিং — YAML 1.1 পার্সারে আপনার কোড ফাইলটি দেখার অনেক আগেই এটিfalseহয়ে গেছে।
এক: এরর ছাড়া parse ≠ সঠিক কনফিগ — প্রথমেই একটি বাস্তব ঘটনা
একটি ই-কমার্স দল ডেলিভারি দেশের তালিকায় নরওয়ে যোগ করেছিল: এক লাইন, NO, Ansible-এর group_vars-এ একটি লিস্টে। রিভিউ হয়েছে, ভ্যালিডেট হয়েছে, ডিপ্লয় হয়েছে। এক সপ্তাহ পরে: নরওয়ের অর্ডার শূন্য — সার্ভারের JSON ফাইলে ছিল "DK", false, "SE"। Ansible নিজের ভেরিয়েবল ফাইল PyYAML দিয়ে parse করে, যা 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 |
float 1.1 |
float 1.1 |
"1.10" |
zip: 02134 |
অক্টাল 1116 |
দশমিক 2134 |
"02134" |
mode: 0755 |
দশমিক 493 |
দশমিক 755 |
493 বা "0755" |
ports: ["22:22"] |
ষাটভিত্তিক 1342 |
"22:22" |
"22:22" |
মূল প্রতিকার: যে স্ট্রিং কোডের মতো দেখায় সব কিছুতে কোটেশন মার্ক দেওয়া। কিন্তু কোটেশন মানুষের স্মৃতির ওপর দাঁড়ায়; schema যন্ত্রের যাচাইয়ের ওপর দাঁড়ায় — এ কারণেই YAML JSON Schema পাওয়া মর্যাদা রাখে।
দুই: কেন JSON Schema YAML-কে শাসন করতে পারে
YAML 1.2 স্পেসিফিকেশন স্পষ্ট বলে: 1.2-এর মূল লক্ষ্য ছিল YAML-কে JSON-এর কঠোর সুপারসেট বানানো, আর 1.2 পার্সার সাধারণ JSON কোনো পরিবর্তন ছাড়াই পড়ে। দুই ফরম্যাটই একই ডেটা স্ট্রাকচারে parse হয়, তাই ভ্যালিডেটরের কাছে ফাইলের এক্সটেনশনের কোনো মানে নেই। পুরো পাইপলাইন তিন ধাপের:
- YAML ফাইল parse করে অবজেক্ট/অ্যারেতে নেওয়া;
- JSON Schema লোড করা;
- ডেটা schema-এর বিপরীতে ভ্যালিডেট করা — এরর বা পাস।
খেয়াল করুন, ধাপ একে YAML-কে JSON টেক্সটে সিরিয়ালাইজ করে আবার parse করা লাগে না; আপনার ভাষার YAML লাইব্রেরি স্ট্রাকচার সরাসরি ভ্যালিডেটরে দেয়। schema নিজেও YAML-এ লেখা যায় (yq -P schema.json > schema.yaml এক কমান্ডে কনভার্ট করে), তবে JSON-এ রাখাই নিরাপদ পছন্দ: টুল সামঞ্জস্য ভালো, আর schemastore.org ক্যাটালগের সব schema JSON।
তিন: আজই কাজ করে এমন তিনটি CLI পথ
একটি config.yaml নিই যেখানে schema 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
তিন পথের পার্থক্য শুধু parse ধাপে: প্রথম দুটি স্পষ্ট, দুই লাইনের; পাইপলাইন এক স্রোতে চলে; আর check-jsonschema ভেতরেই YAML→JSON কনভার্সন করে। schema ফাইল তিনটির জন্যই এক।
চার: এডিটরে রিয়েল-টাইম ভ্যালিডেশন: modeline ও SchemaStore
Red Hat-এর YAML এক্সটেনশন (yaml-language-server ভিত্তিক) VS Code-এ প্রায় ৩ কোটি ইনস্টল নিয়েছে এবং JSON Schema draft-04/07/2019-09/2020-12 সমর্থন করে। এটি যুক্ত করার তিন উপায়:
# উপায় ১: modeline — ফাইলের প্রথম লাইন schema নির্দেশ করে
# yaml-language-server: $schema=./schema.json
name: checkout
// উপায় ২ ও ৩: .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 workflow বা docker-compose-এর মতো পরিচিত ফাইল স্বয়ংক্রিয়ভাবে schemastore.org ক্যাটালগের সঙ্গে যুক্ত হয়, কোনো কনফিগারেশন ছাড়াই। schema-এর description ফিল্ড autocompletion ইঙ্গিত ও টুলটিপ হয়ে ওঠে, আর অনুপস্থিত required প্রপার্টি লাল আন্ডারলাইনে দেখা যায় — কনফিগের ভুল "ডিপ্লয়-পরবর্তী ডিবাগ" থেকে "আপনি টাইপ করছেন এই মুহূর্তে" চলে আসে। এতে আরও বোঝা যায় কেন SchemaStore, YAML-এর কোনো "schema মান" নয়: YAML-এর কোনো অফিসিয়াল schema স্ট্যান্ডার্ড নেই, আর JSON Schema হলো de facto মান।
পাঁচ: একটি schema নরওয়ে সমস্যাটি কীভাবে ধরত
প্রথম অংশের NO ঘটনায় ফিরে যাই। countries-কে এলিমেন্ট লেভেলে schema দিই:
{
"type": "object",
"required": ["name", "version", "countries"],
"properties": {
"countries": {
"type": "array",
"items": { "type": "string", "pattern": "^[A-Z]{2}$" }
}
}
}
PyYAML-এর তৈরি false স্ট্রিং নয়, তাই type: string সঙ্গে সঙ্গে ব্যর্থ; পার্সার এটিকে ছোট হাতের "no" পড়লেও pattern থামিয়ে দিত। আরও কড়া করতে enum হোয়াইটলিস্ট যোগ করুন। একই schema তৃতীয় অংশের CLI পথে CI-তে চলে, আর চতুর্থ অংশের modeline দিয়ে এডিটরে — দুই প্রান্তে এক চুক্তি।
yamllint-এর সঙ্গে কাজের ভাগাভাগি এক বাক্যে: yamllint-এর truthy নিয়ম (শুধু true/false গ্রহণযোগ্য, অন্য বুলিয়ান বানান চিহ্নিত হয়) লেখার স্টাইল শাসন করে এবং lint স্তরে flag: yes ধরে; JSON Schema ডেটার রূপ শাসন করে, পার্সার যা-ই হোক। ঘটনার দল শেষমেশ তিনটিই নিয়েছিল: স্ট্রিংয়ে কোটেশন, পাইপলাইনে yamllint truthy, টেমপ্লেটে দুই অক্ষরের স্ট্রিং যাচাই। দুই স্তরের প্রতিরক্ষা একে অপরকে ঢাকে না — পরিপূরক করে।
ছয়: Kubernetes ম্যানিফেস্টের ব্যাচ ভ্যালিডেশন
Kubernetes API নিজেই OpenAPI-তে বর্ণিত, আর kubernetes-json-schema প্রজেক্ট সেটিকে স্ট্যান্ডার্ড JSON Schema-তে কনভার্ট করে। Kubeconform এই রেজিস্ট্রি দিয়ে ব্যাচ ভ্যালিডেশন করে: ৪-কোর ল্যাপটপে ৩৫,১৩৯ ফাইল ও ৫০,৭১৪ রিসোর্স kubeconform -ignore-missing-schemas -n 8 -summary দিয়ে ৬.৭ সেকেন্ডে শেষ, একই কাজে kubeval ৩৫ সেকেন্ড নেয়। Helm-এর স্ট্যান্ডার্ড পদ্ধতি: আগে render, পরে ভ্যালিডেশন:
helm template my-app ./charts/my-app > rendered.yaml
kubeconform -strict -summary -kubernetes-version 1.28.0 rendered.yaml
-strict schema-তে অসংজ্ঞায়িত ফিল্ড বাতিল করে (টাইপো তাড়াতাড়ি দেখা যায়); CRD রিসোর্স -ignore-missing-schemas দিয়ে এড়ানো যায় বা -schema-location দিয়ে নিজস্ব রেজিস্ট্রি জুড়া যায়।
সাত: schema ভ্যালিডেশন যা পারে না: তিন সীমাবদ্ধতা
- পার্সার ভার্সনের ড্রিফট parse ধাপেই ঘটে। schema পার্সের ফল দেখে: PyYAML যে
NOপড়েছে তা এখনfalse, আর schema ভুল মানটি শুধুtype/patternদিয়ে আটকাতে পারে। মূল প্রতিকার কোটেশনই; schema-র কাছে পার্সার মেরামত আশা করবেন না। - লজিক্যাল ভুল পরিসরের বাইরে। selector-এ টাইপো বা অস্তিত্বহীন label নির্দেশকারী K8s selector — schema রূপ জানে, অর্থ জানে না। এটা admission webhooks, OPA পলিসি বা
kubectl apply --dry-run=server-এর ভূমি। - ডুপ্লিকেট কী নীরবে জিতে যায়। অনেক YAML পার্সার কী ডুপ্লিকেট সতর্কতা ছাড়া মেনে নেয় (শেষটি জেতে), তাই schema এমন ডেটা পায় যার একটি কী ইতিমধ্যে হারিয়েছে। yamllint-এর
key-duplicatesনিয়ম বা parse hook-ই সন্ধানকারী।
ডিপ্লয়-পূর্ব চেকলিস্ট: কোডের মতো স্ট্রিংয়ে কোটেশন → yamllint চালান (truthy + key-duplicates) → JSON Schema ভ্যালিডেশন CI ও এডিটর দুই জায়গায় → ক্লাস্টার রিসোর্সে বাড়তি --dry-run=server। এই চার ধাপে প্রথম অংশের নরওয়ে ঘটনা পাইপলাইনের দ্বিতীয় ধাপই পার হয় না।
FAQ
JSON Schema কি সরাসরি YAML ফাইল ভ্যালিডেট করতে পারে?
পারে — কিন্তু ভ্যালিডেট করে ফাইল parse-এর ডেটা, ফাইল নয়। YAML 1.2 হলো JSON-এর কঠোর সুপারসেট, দুটোই একই স্ট্রাকচারে parse হয়, তাই এক schema-ই JSON ও YAML দুয়ের কাজ করে। চার পথ থেকে একটি বাছুন — Python, Node, yq পাইপলাইন বা check-jsonschema — ফরম্যাট হাতে কনভার্ট না করে।
SchemaStore কী এবং কীভাবে ব্যবহার করবেন?
schemastore.org হলো JSON Schema ক্যাটালগ (catalog.json) যেখানে শত শত পরিচিত কনফিগ ফাইলের schema জড়ো আছে: package.json, GitHub workflow, docker-compose ইত্যাদি। YAML/JSON সমর্থনকারী এডিটর ফাইল স্বয়ংক্রিয়ভাবে এই ক্যাটালগের সঙ্গে যুক্ত করে, অথবা yaml.schemas-এ ম্যানুয়ালি URL ম্যাপ করতে পারেন। নিজের প্রজেক্টের schema ক্যাটালগে জমাও যায়।
yamllint ও JSON Schema কি একে অপরকে ডুপ্লিকেট করে?
না। yamllint লেখার স্টাইল পরীক্ষা করে (ইনডেন্ট, লাইনের দৈর্ঘ্য, truthy, ডুপ্লিকেট কী) টেক্সট স্তরে; JSON Schema ডেটা স্তরে ডেটার গঠন পরীক্ষা করে (টাইপ, required, enum, pattern)। নরওয়ে ঘটনার সংশোধন তালিকা দুটোই ব্যবহার করেছিল: truthy নিয়ম flag: yes-জাতীয় বানান ধরে, আর schema স্ট্রিং অ্যারেতে ঢুকে পড়া একটি false ধরে।
Kubernetes-এর জন্য: kubeconform নাকি kubectl dry-run?
দুটি আলাদা পেশা। Kubeconform অফলাইন ও ব্যাচে চলে, ক্লাস্টার লাগে না, কাঠামোগত ভুলের জন্য এর জায়গা CI-তে; dry-run=server সত্যিকার API সার্ভারের সঙ্গে কথা বলে এবং admission webhook ও কোটার সমস্যা ফাঁস করে, তবে ক্লাস্টার অ্যাক্সেস লাগে। স্ট্যান্ডার্ড সমন্বয়: CI-তে kubeconform, ডিপ্লয়ের আগে এক ঘূর্ণি --dry-run=server — দুই স্তরই রাখুন।
schema লেখা হয়ে গেলে আপনার YAML থেকে কনভার্ট হওয়া JSON অনলাইন JSON ভ্যালিডেটর-এ পেস্ট করে আগে এরর দেখুন; schema-র কীওয়ার্ড লেখার জন্য দেখুন JSON Schema গাইড; schema-কে CI-র টেস্টে পাহারা দিতে পড়ুন JSON Schema কনট্র্যাক্ট টেস্টিং; দৈনিক JSON↔YAML কনভার্সনের জন্য ব্যবহার করুন JSON YAML XML কনভার্টার।