آیا JSON میتواند کامنت داشته باشد
جمع‌بندی: RFC 8259 نحو کامنت ندارد، پس `//` و کامنت بلوکی باعث پرتاب خطا توسط JSON.parse می‌شوند. از JSON5 یا JSONC، فیلد `_comment`، توضیح Schema یا YAML استفاده کنید.
جمع‌بندی: هرگز در JSON استاندارد کامنت نگذارید؛ برای پیکربندی محلی که فقط انسان ویرایشش می‌کند از JSONC یا JSON5 استفاده کنید، وقتی فایل از مرز سیستم‌ها عبور می‌کند توضیحات را به description در JSON Schema ببرید، و وقتی حجم حاشیهنویسی رشد کرد به YAML یا TOML روی آورید.
نه.
هر پارسر سازگار با استاندارد این را رد می‌کند:
{
"port": 8080 // local development only
}
Chrome گزارش می‌دهد SyntaxError: Unexpected token }. پارسر به / رسید که نمی‌تواند هیچ مقدار JSON را شروع کند و متوقف شد.
چرا استاندارد عمداً کامنت را حذف کرده است
RFC 8259 شش مقدار تعریف می‌کند: شیء، آرایه، عدد، رشته، true/false، null. هیچ تولید کامنتی وجود ندارد.
کامنت‌ها زودتر پیشنهاد شدند و به دلیلی مشخص رد شدند: وقتی کامنت قانونی شود، کسی از آن برای حمل دستورها استفاده می‌کند — includeهای شرطی، متغیرهای قالب — و هر پارسر گویش خودش را پیدا می‌کند. همکنشپذیری در نخستین گام می‌شکند. JSON عمداً فقط داده است و چیزی اجراشدنی درونش ندارد.
چهار راه برای نگه داشتن یادداشت‌ها
۱. از یک ابرمجموعه استفاده کنید. JSON5 و JSONC هر دو سبک کامنت را می‌پذیرند. settings.json و tsconfig.json در VS Code از نوع JSONC هستند.
هزینه‌اش واقعی است: JSON.parse همچنان ردشان می‌کند و APIها، خطوط لاگ و صف‌های پیام معمولاً فقط JSON استاندارد را می‌پذیرند. کامنت شما بی‌صدا حذف می‌شود یا در جایی پایین‌دست خطا می‌دهد.
۲. یادداشت را در داده بگذارید.
{
"_comment": "port assigned by ops, do not change",
"port": 8080
}
همه‌جا کار می‌کند، اما مدل را آلوده می‌کند: هر مصرف‌کننده باید بداند کدام کلیدها را نادیده بگیرد و تعریف نوع شما فیلدی پیدا می‌کند که واقعاً داده نیست.
۳. از description در Schema استفاده کنید. description برای انسان و ابزار است. اعتبارسنج‌ها آن را نشان می‌دهند، ویرایشگرها هنگام hover نمایش می‌دهند و هرگز وارد payload نمی‌شود. این تنها گزینه‌ای است که بدون شکستن سازگاری از نگهداری بلندمدت جان سالم به در می‌برد.
۴. قالب فایل را عوض کنید. اگر فایل برای ویرایش دستی وجود دارد، YAML یا TOML بومی از کامنت پشتیبانی می‌کنند. جنگیدن با JSON اینجا اتلاف تلاش است.
انتخاب
| موقعیت | پاسخ |
|---|---|
| ارسال به سیستم دیگر، از طریق API یا صف | بدون کامنت؛ در Schema یا مستندات بیرونی مستند کنید |
| پیکربندی‌ای که فقط انسان و ویرایشگر می‌خوانند | JSONC، با پسوند .jsonc |
| نیاز به ابزار همه‌جاگیر و توضیح درون‌خطی | JSON استاندارد به‌همراه description در Schema |
| پیکربندی طولانی با حاشیهنویسی زیاد | به YAML روی آورید |
پرسش‌های متداول
چرا فیلد _comment مدل را آلوده می‌کند؟
چون بخشی از داده می‌شود. هر مصرف‌کننده باید بداند کدام کلیدها را نادیده بگیرد و تعریف نوع فیلدی پیدا می‌کند که واقعاً داده کسب‌وکار نیست.
آیا توضیح باید در description یک JSON Schema باشد؟
بله. description بیرون از payload می‌ماند، در حالی که اعتبارسنج‌ها آن را نشان می‌دهند و ویرایشگرها هنگام hover نمایش می‌دهند، پس تنها گزینه‌ای است که بدون شکستن سازگاری از نگهداری بلندمدت جان سالم به در می‌برد.
آیا JSONC یا JSON5 میتواند توسط JSON.parse تجزیه شود؟
نه. JSON.parse همچنان کامنت را رد می‌کند و APIها، خطوط لاگ و صف‌های پیام معمولاً فقط JSON استاندارد را می‌پذیرند، پس کامنت حذف می‌شود یا در جایی پایین‌دست خطا می‌دهد.
ابزارها
- پارسر JSON5 — پیکربندی دارای کامنت را جای‌گذاری کنید و ساختار حل‌شده را ببینید
- قالب‌بند و اعتبارسنج JSON — JSON غیرقانونی با خط و ستون گزارش می‌شود، پس کامنت خطادار آشکار است