Structured Outputs و Schema Validation

1. مسئله واقعی: JSON معتبر هنوز نتیجه معتبر نیست

وقتی یک مدل متنی شبیه JSON برمی‌گرداند، فقط یکی از چند مرز لازم را رد کرده‌ایم. یک workflow قابل اتکا باید حداقل چهار لایه را جدا نگه دارد: terminal state مدل، parseability، schema conformance و domain invariants. خروجی‌ای که در هر لایه شکست می‌خورد نباید با coercion یا مقدار پیش‌فرض به یک object «قابل‌قبول» تبدیل شود. این درس قرارداد را طوری طراحی می‌کند که refusal، incomplete، parse error، schema error و semantic/domain error همگی stateهای مجزا و قابل تست بمانند.

2. Contract را قبل از provider تعریف کن

قرارداد برنامه باید مستقل از provider نوشته شود: فیلدهای لازم، نوع هر فیلد، enumها، رفتار با property اضافه، nullability، نسخه schema و invariantهای سطح کسب‌وکار. در سناریوی Lab، classifier باید {category, priority, requires_human, evidence_ids} برگرداند. این شکل، contract برنامه است؛ این‌که provider آن را با json_schema، tool schema یا روش دیگری تولید می‌کند یک capability جداست. نتیجه این جداسازی آن است که تغییر provider باعث تغییر ضمنی business contract نمی‌شود.

3. Terminal state قبل از parse بررسی می‌شود

قبل از هر json.loads باید بدانیم response واقعاً data completion است یا یک terminal state متفاوت. REFUSAL، INCOMPLETE و COMPLETE را یکی نکن. refusal داده classifier نیست؛ incomplete نیز object ناقص نیست که بتوان آن را حدس زد و تکمیل کرد. harness ابتدا terminal state را طبقه‌بندی می‌کند و فقط در حالت COMPLETE به parse می‌رود. این کار از خطای رایج «هر چیزی که داخل response آمده را JSON فرض کن» جلوگیری می‌کند.

4. Parseability فقط syntax را ثابت می‌کند

اگر متن parse شد، فقط می‌دانیم syntax JSON قابل خواندن است. هنوز هیچ شاهدی نداریم که فیلد لازم وجود دارد، enum مجاز است، نوع درست است یا property اضافه ممنوع رعایت شده است. به همین دلیل نتیجه parse باید یک فیلد مستقل مثل PARSE_OK یا PARSE_ERROR داشته باشد. در failure report نیز raw payload identity و خطای parse ثبت می‌شود تا downstream مجبور نباشد از exception خام معنی بسازد.

5. Schema Validation باید deterministic باشد

پس از parse، object باید در برابر یک schema version مشخص بررسی شود. required properties، typeها، enumها، array item type و additional properties باید به‌صورت deterministic enforce شوند. در Lab، schema v1 چهار فیلد اصلی را لازم می‌داند و property ناشناخته را رد می‌کند. هدف این نیست که provider را دوباره‌سازی کنیم؛ هدف این است که برنامه شاهد مستقل و قابل تکرار برای contract خودش داشته باشد.

6. Strict provider feature جای validator برنامه را نمی‌گیرد

Structured-output یا strict tool feature می‌تواند احتمال خطاهای ساختاری را پایین بیاورد، اما مرز مسئولیت برنامه را حذف نمی‌کند. provider ممکن است فقط subset خاصی از JSON Schema را پشتیبانی کند، capability بین modelها فرق کند، یا terminal state غیر-data برگرداند. بنابراین schema provider-facing و schema application-facing باید mapping صریح داشته باشند. اگر feature پشتیبانی نشد، state UNSUPPORTED_CAPABILITY باید حفظ شود؛ نباید بی‌سر و صدا به JSON mode یا free text سقوط کنیم مگر policy آن را صریحاً مجاز کرده باشد.

7. Domain invariant بعد از schema می‌آید

Schema می‌تواند بگوید evidence_ids آرایه‌ای از stringهاست، اما نمی‌تواند به‌تنهایی ثابت کند هر ID واقعاً در evidence set مجاز وجود دارد. همین‌طور می‌توان invariant گذاشت که اگر priority=high باشد requires_human=true لازم است. این‌ها قواعد application هستند و باید بعد از schema validation اجرا شوند. خروجی schema-valid که invariant را می‌شکند، DOMAIN_INVALID است؛ نه موفقیت ناقص.

8. Typed failure بهتر از exception پراکنده است

هر failure باید class مشخص، retryability مشخص و promotion decision مشخص داشته باشد. نمونه‌ها: PROVIDER_REFUSAL، RESPONSE_INCOMPLETE، PARSE_ERROR، SCHEMA_INVALID و DOMAIN_INVALID. downstream به‌جای تفسیر متن exception، روی همین typeها تصمیم می‌گیرد. retry نیز باید بر اساس failure class باشد؛ parse/schema failure ممکن است با prompt/model/schema remediation حل شود، در حالی که domain failure ممکن است نیازمند اصلاح داده یا human/application correction باشد.

9. Additional properties و enum drift را جدی بگیر

دو خطای پرریسک، propertyهای پیش‌بینی‌نشده و enum drift هستند. اگر downstream بر مجموعه محدود enumها branch می‌زند، مقدار جدید بدون version change می‌تواند رفتار را بشکند. همچنین property اضافه ممکن است نشان دهد prompt یا provider shape تغییر کرده است. در contract سخت، additionalProperties: false یا معادل deterministic آن باعث می‌شود drift زود و قابل مشاهده شکست بخورد، نه این‌که وارد سیستم شود و بعداً خطای مبهم بسازد.

10. Nullable با optional یکی نیست

فیلدی که optional است ممکن است اصلاً وجود نداشته باشد؛ فیلد nullable می‌تواند وجود داشته باشد و مقدار null بگیرد. در transfer این درس، schema v2 فیلد due_at را optional و nullable می‌کند. harness باید تفاوت absence، null و string معتبر را حفظ کند. تبدیل خودکار absence به null یا برعکس، اگر contract چنین اجازه‌ای نداده باشد، یک mutation معنایی است و باید ممنوع بماند.

11. Schema version بخشی از provenance است

هر validation record باید schema version را نگه دارد. بدون آن، عبارت «این خروجی validate شد» ناقص است. وقتی v2 enum priority را کوچک‌تر می‌کند، fixture قدیمی با priority=low ممکن است زیر v1 معتبر و زیر v2 نامعتبر باشد. این incompatibility باید به‌صورت صریح ثبت شود. evidence مربوط به v1 نباید به v2 ارث برسد مگر harness واقعاً همان payload را دوباره در برابر v2 آزموده باشد.

12. Promotion gate چهار مرحله دارد

در این درس promotion gate به‌ترتیب کار می‌کند: 1) terminal state باید data-complete باشد؛ 2) payload باید parse شود؛ 3) object باید schema-valid باشد؛ 4) domain invariantها باید پاس شوند. هر مرحله failure خودش را تولید می‌کند و مرحله بعد اجرا نمی‌شود مگر قبلی پاس شده باشد. این ترتیب باعث می‌شود یک domain checker روی payload ناقص یا یک schema validator روی refusal اجرا نشود و evidence chain قابل ممیزی بماند.

13. Retry، remediation و human correction را جدا کن

همه failureها retryable نیستند. INCOMPLETE معمولاً می‌تواند با policy محدود retry شود؛ refusal ممکن است نیازمند تغییر task/policy باشد و نباید blind retry شود. SCHEMA_INVALID می‌تواند trigger برای اصلاح prompt/model/schema mapping باشد. DOMAIN_INVALID اغلب به داده یا تصمیم انسانی/برنامه‌ای برمی‌گردد. harness باید retryability و remediation class را همراه failure ثبت کند تا loop بی‌نهایت و هزینه پنهان ایجاد نشود.

14. Lab: هشت fixture deterministic

Lab هشت fixture دارد: baseline contract-valid، JSON نامعتبر، missing required field، چند violation ساختاری شامل type/enum/property اضافه، refusal، incomplete، schema-valid با evidence ID نامجاز، و transfer زیر schema v2 با enum تنگ‌تر. برای هر case هشت خروجی ثابت ثبت می‌شود: terminal state، parse result، schema conformance، domain result، promotion decision، failure class، retryability و compatibility result. اجرای مرجع باید دقیقاً 64 assertion را پاس کند.

15. Exit checklist و transfer

قبل از خروج بررسی کن: contract versioned است؛ terminal states از data جدا هستند؛ parse و schema و domain validation قاطی نشده‌اند؛ failureها typed هستند؛ unsupported capability به success تبدیل نشده؛ retry policy bounded است؛ schema version در evidence ثبت شده؛ و promotion فقط بعد از چهار gate انجام می‌شود. سپس transfer را اجرا کن: schema v2 due_at nullable را اضافه و enum priority را محدود می‌کند. fixtureهای قدیمی و جدید را دوباره اجرا کن و مشخص کن هر failure retry می‌خواهد، تغییر prompt/model/schema می‌خواهد یا correction انسانی/برنامه‌ای.