من JSON5 إلى JSONC: تجربة تنسيق JSON أكثر مرونة

عندما يجعلك JSON الصارم تصحح الأخطاء حتى وقت متأخر من الليل بسبب فاصلة مفقودة واحدة، ربما حان الوقت للتعرف على أقاربه الأكثر تسامحاً — JSON5 و**JSON with Comments (JSONC)**.

ما هو JSON5؟

JSON5 هو امتداد لـ JSON يتضمن ميزات من ECMAScript 5.1، بما في ذلك المفاتيح غير المقتبسة، والفواصل الزائدة، والسلاسل النصية بعلامات اقتباس مفردة، والتعليقات، والأرقام الست عشرية. يتم صيانته من قبل المجتمع وصُمم لجعل ملفات التكوين المكتوبة يدوياً أكثر قابلية للقراءة وتسامحاً من JSON الصارم.

ما هو JSONC؟

JSONC (JSON with Comments) هو امتداد أدنى لـ JSON القياسي يضيف دعماً لتعليقات السطر الواحد (//) والتعليقات متعددة الأسطر (/* */)، بالإضافة إلى الفواصل الزائدة. تصونه Microsoft، وهو التنسيق الأصلي لإعدادات VS Code وملف tsconfig.json وملفات تكوين TypeScript الأخرى.

لماذا نحتاج JSON “المتسامح”

• عوائق القراءة: يحظر JSON القياسي التعليقات والفواصل الزائدة وعلامات الاقتباس المفردة وغيرها، مما يضر بوضوح ملفات التكوين والعروض التوضيحية.
• معاناة التعاون الجماعي: ملفات JSON الضخمة بدون ملاحظات مضمنة صعبة الصيانة؛ تعديل بسيط يمكن أن يكسر الملف بأكمله.
• واقع DevOps: تقوم أنابيب Kubernetes وCI/CD بدمج أو توليد JSON ديناميكياً باستمرار؛ الصياغة المتسامحة تقلل الإصلاحات اليدوية.

JSON5 مقابل JSONC في لمحة

الميزة	JSON (صارم)	JSON5	JSONC
تعليقات // سطر واحد	لا	نعم	نعم
تعليقات /* */ متعددة الأسطر	لا	نعم	نعم
فواصل زائدة	لا	نعم	نعم
سلاسل نصية بعلامات اقتباس مفردة	لا	نعم	لا
مفاتيح غير مقتبسة	لا	نعم	لا
علامات رقمية + / -	لا	نعم	لا
أرقام ست عشرية / ثنائية	لا	نعم	لا
جهة الصيانة	ECMA	المجتمع (A. Rauschmayer)	Microsoft / VS Code

في جملة واحدة: JSON5 يبدو كحرفي كائن JavaScript، بينما JSONC هو مجرد JSON قياسي مع تعليقات.

أمثلة على الصياغة

JSON العادي (صارم)

{
  "name": "Go Tools",
  "features": ["Base64", "JSON Formatter"]
}

مثال JSON5

// Project config
{
  name: 'Go Tools',      // single quotes & unquoted keys
  features: [
    'Base64',
    'JSON Formatter',    // trailing comma
  ],
  version: 1.0,          // non-string number allowed
}

مثال JSONC

{
  // Project name
  "name": "Go Tools",
  // Feature list
  "features": [
    "Base64",
    "JSON Formatter", // trailing comma
  ]
}

دعم التنسيق والتحليل

السيناريو	JSON5	JSONC	المكتبات / الأدوات الموصى بها
المتصفح	بوليفيل JSON5.parse()، Prettier مع محلل json5 مدمج (>= v1.13)	دعم أصلي في VS Code settings.json	—
Node.js	حزمة json5 من npm	comment-json، jsonc-parser	دعم تنسيق سطر الأوامر وتحليل AST
بيئة التطوير	إضافات VS Code وWebStorm	دعم أصلي في VS Code، إضافة WebStorm	Prettier يمكنه توحيد التنسيق
CI / فحص الكود	eslint-plugin-json5	eslint-plugin-jsonc	دمج مع Husky وlint-staged
أداة عبر الإنترنت	منسق JSON من Go Tools (يجمّل ويتحقق من JSON5/JSONC)	نفسه	منسق JSON

تنسيق سريع في VS Code

أضف إلى settings.json:

"[jsonc]": {
  "editor.defaultFormatter": "esbenp.prettier-vscode"
}

ثم اضغط Alt + Shift + F لتجميل أي ملف JSONC.

ملفات تكوين واقعية

JSON5 وJSONC مستخدمان بالفعل على نطاق واسع في ملفات التكوين التي تواجهها يومياً. إليك أمثلة عملية:

TypeScript (tsconfig.json — JSONC)

{
  // Strict mode catches more bugs at compile time
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "module": "ESNext",
    "outDir": "./dist",
    // Path aliases for cleaner imports
    "paths": {
      "@/*": ["./src/*"],
      "@tests/*": ["./tests/*"],
    },
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"],
}

يستخدم ملف tsconfig.json في TypeScript تنسيق JSONC أصلياً — التعليقات والفواصل الزائدة تعمل مباشرة. هذا أحد أكثر ملفات JSONC شيوعاً في أي مشروع JavaScript/TypeScript.

تكوين ESLint المسطح (eslint.config.json — JSONC)

{
  "rules": {
    // Warn on console.log, but allow console.error
    "no-console": ["warn", { "allow": ["error", "warn"] }],
    "semi": ["error", "always"],
    "quotes": ["error", "double"],
  }
}

Babel (babel.config.json5 — JSON5)

{
  // Single quotes and unquoted keys make it more readable
  presets: [
    ['@babel/preset-env', {
      targets: '> 0.25%, not dead',
      modules: false,  // Let bundler handle modules
    }],
  ],
  plugins: [
    '@babel/plugin-transform-runtime',
  ],
}

إعدادات مساحة عمل VS Code (.vscode/settings.json — JSONC)

{
  // Editor preferences
  "editor.fontSize": 14,
  "editor.tabSize": 2,
  "editor.formatOnSave": true,

  // Language-specific overrides
  "[typescript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
  },
  "[jsonc]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode",
  },
}

نصائح عملية ومحاذير

1. حوّل قبل الإنتاج

لا تزال المتصفحات تتطلب JSON الصارم لـ JSON.parse. استخدم أدوات خطوة البناء لإزالة التعليقات والفواصل الزائدة:

// Node.js build script: convert JSON5 config to strict JSON
import JSON5 from 'json5';
import { readFileSync, writeFileSync } from 'fs';

const config = JSON5.parse(readFileSync('config.json5', 'utf8'));
writeFileSync('config.json', JSON.stringify(config, null, 2));

لأدوات التجميع، استخدم rollup-plugin-json5 أو vite-plugin-json5 للتعامل مع التحويل تلقائياً أثناء البناء.

2. الأمان والموثوقية

التسامح يمكن أن يخفي حقولاً مشبوهة. تحقق دائماً من التكوين باستخدام JSON Schema أو zod قبل استهلاكه:

// Validate config shape with zod after parsing
import { z } from 'zod';
import JSON5 from 'json5';

const ConfigSchema = z.object({
  port: z.number().min(1).max(65535),
  host: z.string(),
  debug: z.boolean().default(false),
});

const raw = JSON5.parse(readFileSync('config.json5', 'utf8'));
const config = ConfigSchema.parse(raw); // Throws if invalid

3. اتفاقيات الفريق

• صرّح في README أن ملفات *.json5 للتكوين فقط؛ حزم الإصدار يجب أن تشحن .json صارم.
• وحّد قواعد Prettier لتجنب الفروقات المزعجة.
• استخدم .editorconfig لفرض مسافات بادئة متسقة عبر ملفات JSON وJSON5 وJSONC.

4. الأداء

تحليل JSON5/JSONC يضيف تبعيات وعبئاً طفيفاً — مناسب لأدوات سطر الأوامر والتطوير، لكن قسه للإنتاج. حزمة json5 من npm حجمها ~8 كيلوبايت مصغرة، والتحليل أبطأ بنحو 2-5 مرات من JSON.parse الأصلي. لملفات التكوين المحملة مرة عند بدء التشغيل، هذا ضئيل. للمسارات الساخنة التي تحلل آلاف الكائنات في الثانية، التزم بـ JSON الصارم.

الأسئلة الشائعة

ما الفرق بين JSON5 وJSONC؟

يوسع JSON5 تنسيق JSON بصياغة شبيهة بـ JavaScript: مفاتيح غير مقتبسة، فواصل زائدة، تعليقات سطر واحد وكتلة، أرقام ست عشرية، وسلاسل نصية متعددة الأسطر. JSONC أبسط — يضيف فقط تعليقات السطر الواحد (//) والكتلة (/* */) إلى JSON القياسي. اختر JSONC لملفات التكوين حيث تكفي التعليقات؛ اختر JSON5 عندما تحتاج صياغة أغنى.

هل يمكنني استخدام JSON5 أو JSONC في واجهات API الإنتاجية؟

لا — JSON5 وJSONC مصممان لملفات التكوين، وليس لتبادل البيانات. يجب أن تستخدم واجهات API تنسيق JSON القياسي (RFC 8259) للتوافقية القصوى. احجز JSON5/JSONC لملفات التكوين المحلية مثل tsconfig.json و.vscode/settings.json أو تكوين البيئة حيث تهم القراءة البشرية أكثر من التحليل الآلي.

هل يدعم VS Code تنسيق JSON5 أصلياً؟

يدعم VS Code تنسيق JSONC أصلياً (ملفات إعداداته تستخدم JSONC)، لكنه لا يدعم JSON5 مباشرة. لـ JSON5، ثبّت إضافة مخصصة مثل “JSON5 syntax” من سوق VS Code. يمكنك أيضاً ربط ملفات .json5 بوضع لغة JSON5 في إعداداتك.

كيف أحول JSON5 إلى JSON قياسي؟

استخدم حزمة json5 من npm: JSON5.parse() تقرأ JSON5، ثم JSON.stringify() تُخرج JSON قياسي. لاستخدام سطر الأوامر، شغّل npx json5 < input.json5 > output.json. يمكن للأدوات عبر الإنترنت مثل منسق JSON لدينا أيضاً التحقق من صحة المخرجات المحولة لضمان صحتها.

هل JSONC هو نفسه JSON with Comments؟

نعم — JSONC يرمز إلى “JSON with Comments” وهو التنسيق المستخدم من قبل VS Code وTypeScript (tsconfig.json) وأدوات Microsoft الأخرى. يتبع مواصفات JSON القياسية مع إضافة تعليقات // و/* */ فقط. تزيل المحللات التعليقات قبل المعالجة، لذا بنية البيانات الناتجة مطابقة لـ JSON القياسي.

لمزيد من أدوات المطورين القائمة على المتصفح بما في ذلك ترميز Base64 وتوليد التجزئة وتحويل الطوابع الزمنية، راجع دليل أدوات المطورين الأساسية.

الخلاصة

الموازنة بين القراءة والصرامة هي صراع تطوير كلاسيكي. يحسّن JSON5 وJSONC تجربة الكتابة، ومع خط أنابيب البناء والتحقق المناسب، يمكنك الاستمتاع بمزايا “JSON المتسامح” بأمان.

المراجع

• JSON5 GitHub
• JSONC spec (VS Code)
• Prettier parser docs
• comment-json