داده، SQL، قراردادها و ماشین حالت · فصل ۵ — JSON Schema، OpenAPI، AsyncAPI، Protobuf و gRPC · 69
JSON Schema 2020-12 برای Contracts و Content
داده را ذخیره یا query می‌کند اما constraint، consistency، compatibility و recovery را به یک contract مهندسی تبدیل نمی‌کند. موضوع جاری: «JSON Schema 2020-12 برای Contracts و Content». می‌تواند «JSON Schema 2020-12 برای Contracts و Content» را برای یک domain محدود مدل کند و constraint، compatibility یا recovery evidence لازم را مشخص کند.
خلاصهٔ درس
داده را ذخیره یا query می‌کند اما constraint، consistency، compatibility و recovery را به یک contract مهندسی تبدیل نمی‌کند. موضوع جاری: «JSON Schema 2020-12 برای Contracts و Content».
می‌تواند «JSON Schema 2020-12 برای Contracts و Content» را برای یک domain محدود مدل کند و constraint، compatibility یا recovery evidence لازم را مشخص کند.
خروجی این درس
می‌تواند «JSON Schema 2020-12 برای Contracts و Content» را برای یک domain محدود مدل کند و constraint، compatibility یا recovery evidence لازم را مشخص کند.
پیش‌نیازها
_Locale: fa-IR · Lesson: DAT-012 · Public order: 69_
خروجی و artifact کاری
این درس برای ساختن رکورد راستی‌آزمایی قرارداد JSON Schema نسخه ۱ است: یک artifact تصمیم که مشاهده، فرض، محدودیت و evidence موردنیاز را از هم جدا می‌کند. هدف حفظ یک مدل قابل‌انتقال است، نه حفظ‌کردن نام ابزارها.
می‌تواند «JSON Schema 2020-12 برای Contracts و Content» را برای یک domain محدود مدل کند و constraint، compatibility یا recovery evidence لازم را مشخص کند.
مدل مرزی
JSON Schema 2020-12 می‌تواند contract ساختاری machine-checkable بسازد، اما validation به dialect اعلام‌شده، vocabularyها، configuration validator و assertionهای واقعاً نوشته‌شده محدود است. valid بودن instance همه business invariantها را ثابت نمی‌کند. contract مفید fixture مثبت، fixture منفی عمدی و تصمیم compatibility برای هر تغییر schema دارد.
در هر بخش سه برچسب نگه دارید: «مشاهده‌شده»، «استنباط محدود» و «نیازمند بررسی». اگر evidence در دسترس نیست، نتیجه را unknown ثبت کنید؛ نام ابزار یا pass شدن یک happy path جای evidence را نمی‌گیرد.
1. Dialect را اعلام کنید
با $schema meta-schema مورد نظر را مشخص کنید. بدون dialect صریح، دو ابزار ممکن است keyword یا vocabulary پشتیبانی‌شده را متفاوت تفسیر کنند.
2. Assertion و annotation را جدا کنید
keywordهایی مانند type، required و bound عددی validity را محدود می‌کنند. metadataهایی مانند title، description و بسیاری از کاربردهای format الزام domain مورد انتظار را خودکار ایجاد نمی‌کنند.
3. Object و array را آگاهانه مدل کنید
برای object، propertyهای required و extension policy را تعیین کنید. برای array، prefixItems tuple-like را از items تکرارشونده جدا کنید و uniqueness/size را فقط با نیاز domain اضافه کنید.
4. داده ردشونده را هم تست کنید
schemaای که فقط fixture valid دیده، مرز خود را ثابت نکرده است. field غایب، type غلط، property ناشناخته، عدد مرزی و union مبهم باید probe عمدی باشند.
5. Compatibility جهت دارد
سخت‌کردن schema consumer می‌تواند داده قدیمی را رد کند؛ آزادکردن producer می‌تواند داده‌ای بسازد که consumer قدیمی نمی‌پذیرد. تغییر را با جهت producer/consumer و retained data بسنجید.
روش پنج‌مرحله‌ای
- مرز instance و invariantهایی را که واقعاً structural هستند بنویسید.
- draft 2020-12 را pin کنید و کوچک‌ترین مجموعه assertion لازم را بسازید.
- در کنار fixtureهای مثبت، برای هر boundary تعیین‌کننده یک fixture منفی بسازید.
- suite را با configuration validator انتخاب‌شده اجرا و رفتار
formatو referenceها را ثبت کنید. - برای هر schema diff اثر producer و consumer را جدا classify و invariantهای application-only را بیرون schema نگه دارید.
مثال حل‌شده
یک content card به id، kind و title نیاز دارد و kind یکی از دو payload shape را انتخاب می‌کند. contract، draft 2020-12 را اعلام می‌کند، با oneOf و requiredهای متقابلاً انحصاری ambiguity را کم می‌کند، object نام‌دار extensions را باز و property ناشناخته top-level را بسته نگه می‌دارد. تست‌ها article و video معتبر، title غایب، payload مبهم و key ناشناخته را پوشش می‌دهند. افزودن extension اختیاری جدا از requiredکردن field قبلی ارزیابی می‌شود.
ماتریس تصمیم و evidence
| موضوع | مرز/مالک | evidence | تصمیم یا محدودیت |
|---|---|---|---|
| dialect | 2020-12 | وجود $schema | فرض اجرایی ناشناخته رد شود |
| fieldهای required | id/kind/title | fixture مثبت و missing-field | assertion ساختاری |
| extension | bag نام‌دار باز | top-level ناشناخته رد شد | extensibility محدود |
| format | رفتار configuration ثبت شد | نمونه date-like نامعتبر | assertion بیش‌ازحد ادعا نشود |
| تغییر schema | افزودن field اختیاری | suite قدیم/جدید | classification جهت‌دار |
خطاهای محتمل و روش اصلاح
- تعمیم validation به همه invariantهای business
- فرض assertion بودن format در هر implementation
- یکی‌گرفتن schema identifier با policy نسخه داده
- بستن property ناشناخته بدون توجه به extensibility
برای هر مورد، ادعا را محدود کنید، یک counterexample بسازید و بنویسید کدام مشاهده می‌تواند آن را تأیید یا رد کند.
تمرین انتقال
سناریو را طوری تغییر دهید که یکی از فرض‌های مثال دیگر برقرار نباشد. بدون کپی‌کردن تصمیم قبلی، رکورد راستی‌آزمایی قرارداد JSON Schema نسخه ۱ را دوباره بسازید؛ سپس تفاوت decision rule و تفاوت دادهٔ ورودی را توضیح دهید.
این درس چه چیزی را ثابت نمی‌کند
این درس certification، تضمین production یا پوشش همه implementationها را ادعا نمی‌کند. نتیجه فقط در مرز سناریو، sourceهای تاریخ‌دار و observationهای ثبت‌شده معتبر است.
خودسنجی
- [ ] آیا مسئولیت‌ها را از نام framework یا tool جدا کرده‌ام؟
- [ ] آیا دست‌کم یک failure probe و نتیجه موردانتظار آن را نوشته‌ام؟
- [ ] آیا fact، inference و design choice از هم مشخص‌اند؟
- [ ] آیا non-claim و evidence گمشده را ثبت کرده‌ام؟
- [ ] آیا transfer را روی context تغییرکرده و بدون پاسخ آماده انجام داده‌ام؟
منابع و مرز تازگی
sourceها در 2026-09-19 طبق Bible منجمدشده مرور شده‌اند. تاریخ review_due یک trigger برای بازبینی نسخه‌ای است؛ هیچ بسته‌ای نباید درجا و بدون نسخه جدید تغییر کند.
- JSONSCHEMA-SPEC — Official specification index; current published JSON Schema version and document set. (https://json-schema.org/specification; review: 2026-12-31)
- JSONSCHEMA-2020-12 — Draft 2020-12 overview, meta-schema and release semantics. (https://json-schema.org/draft/2020-12; review: 2026-12-31)
- JSONSCHEMA-CORE — Core dialect, vocabulary, reference and schema-resource semantics. (https://json-schema.org/draft/2020-12/json-schema-core; review: 2026-12-31)
- JSONSCHEMA-VALIDATION — Validation and format vocabulary semantics. (https://json-schema.org/draft/2020-12/json-schema-validation; review: 2026-12-31)
ارزیابی
پاسخ‌نامه‌ی این درس در بسته‌ی آموزش وجود ندارد؛ خودت جواب بده و صادقانه علامت بزن. «نیاز به مرور» درس را به صف تکرار می‌فرستد.
DAT-012-S1 retrieval
DAT-012-S2 application
DAT-012-S3 diagnosis
DAT-012-S4 decision
DAT-012-S5 transfer
ملاک‌های ارزیابی (rubric)
| Dimension | Critical | Sufficient evidence |
|---|---|---|
| contract/protocol correctness | yes | Explanation preserves version/dialect, compatibility/reliability and evidence semantics. |
| evidence quality | yes | Positive, negative and change/repair observations are traceable and separated from inference. |
| scope discipline | yes | Adjacent outcomes and unsupported tool/runtime generalizations are deferred. |
| transfer independence | yes | Changed-context task is solved without decisive scaffold. |
A submission passes only when every critical dimension is sufficient and the learner states missing evidence honestly. AI suggestions are not observed evidence; the learner remains accountable for the final bounded judgment.
منابع و تازگی
مطالعهٔ موارد (case studies)
فایل‌های آزمایشگاه
با fixture امن محلی، رکورد راستی‌آزمایی قرارداد JSON Schema نسخه ۱ را بسازید. ابتدا prediction را بنویسید؛ سپس baseline و failure probeهای اعلام‌شده را ثبت کنید و observation مثبت و منفی را نگه دارید. transfer را بدون کپی تصمیم مثال انجام دهید.
starter عمداً classification یا risk decision نهایی را انتخاب نمی‌کند. evaluate_record.py و evidence template را تکمیل کنید. اجرای python3 ../run_checks.py فقط environment و شکل fileها را بررسی می‌کند و تصمیم محتوایی شما را grade نمی‌کند.
مرز ایمنی: No production system/data, no external account/service dependency, and all failure probes must be bounded and deterministic.
رسانه و اسلایدهای درس
فایل‌های آموزشی (دانلود)