.NDJSON Newline-Delimited JSON
.ndjson

Newline-Delimited JSON

ملف NDJSON (JSON المحدد بأسطر جديدة) يحمل قيمة JSON واحدة صالحة في كل سطر، مفصولة بمحرف السطر الجديد. يُعرف أيضاً باسم JSON Lines (بامتداد .jsonl). يُستخدم في تصدير MongoDB وواجهة Elasticsearch للفهرسة الجماعية وتحميل بيانات BigQuery.

اقرأ المزيد ↓
بنية الصيغة
Header schema
Records structured data
نصبث2013
بواسطة FileDex
غير قابل للتحويل

NDJSON صيغة بيانات نصية. يعرض FileDex معلومات الصيغة ومرجعاً تقنياً للمطورين للتعامل مع ملفات JSON المحددة بأسطر جديدة.

أسئلة شائعة

ما هو ملف NDJSON وما استخداماته؟

ملف NDJSON هو ملف نصي بترميز UTF-8 يحمل قيمة JSON واحدة صالحة في كل سطر. يُستخدم في تصدير بيانات MongoDB وفهرسة Elasticsearch الجماعية وتحميل بيانات BigQuery وسجلات التطبيقات المنظمة. يُعرف أيضاً باسم JSON Lines بامتداد .jsonl وهما نفس الصيغة.

كيف أفتح ملف NDJSON وأتصفح محتواه؟

افتحه في أي محرر نصوص مثل VS Code — كل سطر كائن JSON مستقل يُعرض بتلوين صيغة JSON. لعرض منسّق من سطر الأوامر استخدم أداة jq التي تعالج كل سطر على حدة تلقائياً. للاستعلام بـ SQL استخدم DuckDB الذي يكتشف الصيغة ويسمح بتنفيذ استعلامات مباشرة على الملف.

ما الفرق بين NDJSON وJSON Lines؟

لا فرق تقني بينهما. NDJSON (مواصفة 2014 على GitHub) يستخدم امتداد .ndjson ونوع MIME application/x-ndjson. أما JSON Lines (مواصفة 2013 على jsonlines.org) فيستخدم امتداد .jsonl. قواعد الترميز والأسطر متطابقة. غيّر الامتداد من أحدهما للآخر وكل الأدوات المتوافقة تقرأه.

لماذا يختار Elasticsearch صيغة NDJSON للعمليات الجماعية؟

واجهة _bulk في Elasticsearch ترسل أسطراً متناوبة من بيانات وصفية للعملية ومصدر المستند. العقدة المنسّقة تحتاج فقط لقراءة سطر العملية الصغير لتوجيه المستند إلى الجزء الصحيح دون تحليل محتوى المستند الكامل. هذا يجعل التوجيه سريعاً حتى مع مستندات كبيرة.

هل ملف NDJSON يُعتبر JSON صالحاً؟

كل سطر على حدة هو JSON صالح، لكن الملف ككل ليس كذلك. مستند JSON يتطلب بنية خارجية مثل مصفوفة أو كائن. NDJSON لا يملك أقواساً خارجية — هو تسلسل قيم JSON مستقلة مفصولة بأسطر جديدة. الأدوات التي تتوقع مستند JSON واحداً سترفض ملف NDJSON.

كيف أتحقق من صلاحية ملف NDJSON؟

استخدم أداة jq بمُرشّح empty على الملف. الأمر يفحص كل سطر للتأكد من صلاحية JSON ويُبلّغ عن رقم السطر الأول غير الصالح مع وصف الخطأ. بديل آخر: DuckDB يُبلّغ عن أخطاء التحليل عند تحميل ملفات NDJSON عبر read_json_auto.

ما يميز .NDJSON

تسميتان لصيغة واحدة
NDJSON وJSON Lines متطابقتان
مواصفتان مستقلتان — NDJSON (عام 2014 بامتداد .ndjson) وJSON Lines (عام 2013 بامتداد .jsonl) — تصفان نفس الصيغة بأسماء وامتدادات وأنواع MIME مختلفة. المجتمعان توافقا لكن الازدواجية لا تزال تُربك المطورين.
محرك الانتشار
واجهة Elasticsearch الجماعية نشرت NDJSON عالمياً
Elasticsearch اختارت NDJSON لنقطة _bulk حتى تتمكن العقدة المنسّقة من تحليل أسطر العمليات الصغيرة لتوجيه المستندات دون تحليل المحتوى الكامل. هذا القرار عرّض ملايين المطورين للصيغة.
بلا سقف للحجم
ملفات NDJSON يمكن أن تنمو لمئات الجيجابايت
لأن NDJSON لا يملك أقواساً خارجية أو بنية إغلاق، الملف ينمو بلا حدود بإلحاق أسطر. ملف سجلات بحجم 500 جيجابايت صالح بنيوياً كملف بسطر واحد. المستهلك يقرأه بذاكرة ثابتة.
المواصفة الشبحية
ndjson.org لم يعد يستضيف المواصفة
نطاق ndjson.org الأصلي مُختطف اعتباراً من 2026. المواصفة الرسمية تعيش على GitHub في ndjson/ndjson-spec. مسودة سابقة سمحت بتعليقات // في NDJSON لكن هذا أُزيل للتوافق مع RFC 8259.

ملف NDJSON يحمل قيمة JSON واحدة في كل سطر من ملف نصي بترميز UTF-8. محرف السطر الجديد (0x0A) هو الحد الفاصل الوحيد بين السجلات — لا أقواس مربعة ولا فواصل بين الأسطر. هذه البساطة هي الميزة الجوهرية للصيغة.

اكتشف التفاصيل التقنية

مثال لملف NDJSON بثلاثة سجلات:

{"id":1,"name":"أحمد","role":"مهندس"} {"id":2,"name":"سارة","role":"مصممة"} {"id":3,"name":"خالد","role":"مدير"}

تسميتان لصيغة واحدة

مواصفتان مستقلتان تصفان نفس الصيغة تحت اسمين مختلفين. JSON Lines (نُشرت عام 2013 على jsonlines.org) تستخدم امتداد .jsonl وتقترح نوع MIME application/jsonl. أما NDJSON (نُشرت عام 2014 على GitHub) فتستخدم امتداد .ndjson ونوع MIME application/x-ndjson. القواعد التقنية متطابقة تماماً: ترميز UTF-8 إلزامي، قيمة JSON واحدة لكل سطر، محرف السطر الجديد كفاصل. مجتمعا المواصفتين اعترفا بالتطابق، لكن الازدواجية في التسمية لا تزال تُربك المطورين.

عملياً: غيّر امتداد ملف .jsonl إلى .ndjson أو العكس — كل الأدوات المتوافقة تعالجه بنفس الطريقة.

لماذا التحديد بأسطر: ميزة التدفق

مصفوفة JSON التقليدية تحيط جميع السجلات بأقواس مربعة وتفصلها بفواصل. لتحليلها، يحتاج البرنامج إلى تحميل الملف بالكامل في الذاكرة أو تتبع عمق تداخل الأقواس. لملف سجلات بحجم 50 جيجابايت، كلا الأسلوبين مكلف.

NDJSON يزيل البنية الخارجية كلياً. المستهلك يقرأ سطراً واحداً، يحلله كـ JSON، يعالجه، يتخلص منه، وينتقل للسطر التالي. استخدام الذاكرة يبقى ثابتاً بغض النظر عن حجم الملف. المُنتج يُلحق سجلاً جديداً بكتابة سطر واحد — لا حاجة للعودة وإدراج قبل قوس إغلاق. هذه الخاصية تجعل NDJSON الخيار الطبيعي لملفات السجلات وأنابيب البيانات وحمولات واجهات API الجماعية.

أدوات سطر الأوامر في Unix تتعامل مع NDJSON مباشرة لأن حدود السطر هي حدود السجل: wc -l يعدّ السجلات، head -n 100 يستخرج المئة الأولى، tail -f يبث السجلات الجديدة فور وصولها، وgrep يُرشّح حسب المحتوى.

Elasticsearch: محرك الانتشار

واجهة Elasticsearch للعمليات الجماعية (_bulk و_msearch) تتطلب NDJSON كصيغة جسم الطلب. كل طلب فهرسة جماعية يرسل أسطراً متناوبة من بيانات وصفية للعملية ومصدر المستند. ترويسة Content-Type يجب أن تكون application/x-ndjson. Elasticsearch اختارت هذه الصيغة لأن العقدة المنسّقة تحتاج فقط لتحليل سطر العملية الصغير لتوجيه المستند إلى الجزء الصحيح (Shard) — دون تحليل جسم المستند الكامل. هذا القرار التصميمي عرّض ملايين المطورين لصيغة NDJSON عبر حزمة ELK.

MongoDB وBigQuery والمنظومة السحابية

أداة mongoexport في MongoDB تكتب مستنداً واحداً لكل سطر — صيغة NDJSON. أداة mongoimport تقرأها. ترميز Extended JSON يحافظ على أنواع BSON (مثل ObjectId وDate) التي لا يستطيع JSON القياسي تمثيلها.

Google BigQuery يقبل ما يسميه "JSON المحدد بأسطر جديدة (ndJSON)" لتحميل البيانات من Cloud Storage، ويُصرّح في وثائقه أنها "نفس صيغة JSON Lines". الملفات المضغوطة بـ gzip محدودة بـ 4 جيجابايت ولا يمكن قراءتها بالتوازي.

خدمات AWS تُنتج وتستهلك NDJSON عبر المنظومة: CloudWatch Logs يخزن سجلات JSON منظمة، Kinesis Data Firehose يسلّم NDJSON إلى S3، وAthena يستعلم من ملفات NDJSON بـ SQL.

في منطقة الخليج، مراكز بيانات AWS وGoogle Cloud وAzure في البحرين والإمارات والسعودية تستخدم NDJSON في أنابيب البيانات السحابية بشكل يومي. مهندسو البيانات في المنطقة يتعاملون مع هذه الصيغة عند بناء خطوط ETL وأنظمة المراقبة.

قواعد الصيغة

  1. الترميز: UTF-8 إلزامي. علامة ترتيب البايتات (BOM) ممنوعة.
  2. محتوى السطر: قيمة JSON واحدة صالحة حسب RFC 8259 — كائنات ومصفوفات الأكثر شيوعاً، لكن السلاسل النصية والأرقام والقيم المنطقية وnull مسموحة.
  3. فاصل الأسطر: \n (0x0A). \r\n مقبول أيضاً.
  4. لا أسطر جديدة داخل القيم: السلاسل النصية يجب أن تُهرّب الأسطر الجديدة كـ \n.
  5. سطر جديد نهائي: مُوصى به. Elasticsearch يتطلبه.
  6. لا بنية خارجية: لا أقواس افتتاحية ولا أقواس إغلاق.

نوع MIME والتعرف على الملف

NDJSON لا يملك نوع MIME مسجلاً رسمياً لدى IANA. البادئة x- في application/x-ndjson تعني أنه غير مسجل. ثلاثة أنواع MIME تنتشر في الممارسة: application/x-ndjson (الأكثر استخداماً)، application/jsonl (مقترح من JSON Lines)، وapplication/json-seq (ينتمي لصيغة مختلفة تماماً — RFC 7464).

لأن NDJSON نص عادي بدون بايتات سحرية، التعرف على الملف يعتمد كلياً على الامتداد (.ndjson أو .jsonl) أو ترويسة Content-Type.

مقارنة .NDJSON مع البدائل

.NDJSON vs .JSON
دعم التدفق
NDJSON يعالج سطراً واحداً في كل مرة بذاكرة ثابتة. مصفوفات JSON تتطلب تحليل البنية بالكامل — يجب الوصول إلى قوس الإغلاق قبل اعتبار المصفوفة مكتملة.
 NDJSON أفضل
.NDJSON vs .JSON
عمليات الإلحاق
إلحاق سجل بـ NDJSON يتطلب استدعاء نظام append واحد. إلحاق سجل بمصفوفة JSON يتطلب قراءة الملف وإيجاد قوس الإغلاق والإدراج قبله وإعادة الكتابة.
 NDJSON أفضل
.NDJSON vs .CSV
مرونة المخطط
كل سطر NDJSON يمكن أن يحمل حقولاً مختلفة وكائنات متداخلة ومصفوفات. CSV يتطلب ترويسة أعمدة ثابتة ولا يستطيع تمثيل البنى المتداخلة.
 NDJSON أفضل
.NDJSON vs .CSV
توافق جداول البيانات
CSV يُفتح مباشرة في Excel وGoogle Sheets وجميع تطبيقات جداول البيانات. NDJSON يحتاج تحويلاً إلى CSV أو تحميلاً عبر لغة برمجة أو أداة SQL مثل DuckDB.
 CSV أفضل
.NDJSON vs .PARQUET
نسبة الضغط
تخزين Parquet العمودي مع ترميز القاموس وترميز طول التكرار يضغط 5-10 أضعاف أصغر من نص NDJSON. ملف سجلات NDJSON بحجم 10 جيجابايت قد يُضغط إلى 1-2 جيجابايت كـ Parquet.
 PARQUET أفضل
.NDJSON vs .PARQUET
قابلية القراءة البشرية
NDJSON نص UTF-8 عادي يُقرأ في أي محرر. Parquet ثنائي ويحتاج أدوات متخصصة (DuckDB أو pyarrow أو parquet-tools) لفحص محتوياته.
 NDJSON أفضل
.NDJSON vs .JSON LINES
التوافق بين الصيغتين
NDJSON (بامتداد .ndjson) وJSON Lines (بامتداد .jsonl) هما نفس الصيغة تحت اسمين مختلفين. غيّر امتداد ملف .jsonl إلى .ndjson وكل محلل متوافق يعالجه بنفس الطريقة.
 تعادل

المرجع التقني

نوع MIME
application/x-ndjson
المطوّر
Community standard
سنة التقديم
2013
معيار مفتوح
نعم — عرض المواصفات

البنية الثنائية

NDJSON صيغة نصية بترميز UTF-8 بدون بنية ثنائية ولا بايتات سحرية ولا ترويسة ملف. كل سطر يحتوي قيمة JSON واحدة صالحة حسب RFC 8259 منتهية بمحرف السطر الجديد (0x0A). السطر الجديد هو الفاصل الوحيد بين السجلات — لا فواصل ولا أقواس. السلاسل النصية في JSON يجب أن تُهرّب الأسطر الجديدة الحرفية كتسلسل الحرفين \n. الملف لا يملك بنية خارجية: لا قوس افتتاحي ولا قوس إغلاق. علامة ترتيب البايتات (BOM) ممنوعة صراحةً في مواصفة JSON Lines.

2006أنماط JSON المحدد بأسطر تظهر في أنابيب معالجة السجلات في Unix قبل أي مواصفة رسمية2013نشر مواصفة JSON Lines على jsonlines.org محددةً امتداد .jsonl وقواعد UTF-8 والأسطر الجديدة2014نشر مواصفة NDJSON على GitHub (ndjson/ndjson-spec) محددةً امتداد .ndjson ونوع MIME application/x-ndjson؛ Elasticsearch تعتمد NDJSON لواجهة الفهرسة الجماعية2017Elasticsearch تُرسّم application/x-ndjson كنوع Content-Type المفضل لنقاط البيانات الجماعية2022DuckDB يضيف قراءة NDJSON الأصلية عبر read_json_auto() ممكّناً استعلامات SQL مباشرة على ملفات NDJSON2023OpenAI تعتمد JSONL كصيغة إلزامية لرفع بيانات تدريب الضبط الدقيق (Fine-tuning) مما يُدخل NDJSON إلى عالم تعلم الآلة2024منصات المراقبة (Datadog وGrafana Loki وFluentd) تتوحد على NDJSON كصيغة تبادل السجلات المنظمة عبر حدود المُصنّعين
طباعة كل سجل في ملف NDJSON بتنسيق مقروء أخرى 
jq '.' input.ndjson

jq يعالج كل سطر كقيمة JSON مستقلة ويطبعها بمسافات بادئة. لا يحتاج أي علامات خاصة — jq يتعامل مع NDJSON تلقائياً بمعالجة كل سطر على حدة.

عدّ السجلات في ملف NDJSON أخرى 
wc -l data.ndjson

كل سجل NDJSON يشغل سطراً واحداً بالضبط، لذا عدد الأسطر يساوي عدد السجلات. يفترض أن الملف ينتهي بسطر جديد نهائي (الاصطلاح القياسي).

ترشيح أسطر NDJSON حسب قيمة حقل أخرى 
jq 'select(.level == "error")' logs.ndjson

يُخرج فقط الأسطر التي يساوي فيها حقل level قيمة error. كل سطر يُقيَّم مستقلاً — لا تراكم في الذاكرة. مفيد لتحليل السجلات في ملفات بحجم عدة جيجابايت.

تحويل NDJSON إلى مصفوفة JSON أخرى 
jq -s '.' input.ndjson > output.json

علامة --slurp تقرأ جميع الأسطر في الذاكرة وتلفها في مصفوفة JSON. الناتج مستند JSON واحد صالح. تحذير: يحمّل الملف بالكامل في الذاكرة العشوائية.

استعلام NDJSON بـ SQL عبر DuckDB أخرى 
duckdb -c "SELECT level, count(*) FROM 'logs.ndjson' GROUP BY level;"

DuckDB يكتشف صيغة NDJSON تلقائياً وينفذ استعلامات SQL مباشرة على الملف دون استيراد. يدعم المعالجة خارج الذاكرة للملفات الأكبر من الذاكرة المتاحة.

منخفض

نقاط الضعف

  • قنابل تحليل JSON: كائنات متداخلة بعمق كبير أو سلاسل نصية طويلة جداً في سطر واحد قد تستنفد ذاكرة المحلل أو عمق المكدس مسببة حجب الخدمة في التطبيقات المستهلكة
  • حقن عبر محتوى غير مُهرَّب: أسطر NDJSON تحتوي محارف تحكم غير مُهرَّبة قد تُربك المحللات التي تدمج الأسطر في صيغ ثانوية (SQL أو HTML أو أوامر سطر الأوامر)
  • استنفاد الذاكرة: سطر NDJSON واحد يحتوي كائن JSON بحجم عدة جيجابايت ليس له حد حجم على مستوى الصيغة — المحللات بدون حماية طول السطر ستحاول تحميله بالكامل في الذاكرة

الحماية: لا يقوم FileDex بتحليل أو تنفيذ أو معالجة محتوى NDJSON على الخادم. هذه الصفحة توفر مرجعاً للصيغة فقط. لا يتم تقييم أي بيانات مرفوعة من المستخدم كـ JSON.

jq أداة
معالج JSON لسطر الأوامر يتعامل مع NDJSON تلقائياً — كل سطر إدخال يُعالج كقيمة JSON مستقلة دون أي علامات خاصة
DuckDB أداة
محرك SQL تحليلي يقرأ NDJSON أصلياً عبر read_json_auto() ويدعم استعلامات SQL مباشرة على الملف مع معالجة خارج الذاكرة
Elasticsearch خدمة
محرك بحث وتحليلات يتطلب NDJSON كصيغة جسم الطلب لواجهات _bulk و_msearch — أكبر محرك منفرد لانتشار NDJSON
أداة mongoexport تُنتج NDJSON افتراضياً (مستند واحد لكل سطر) وmongoimport تستهلكه مع Extended JSON لحفظ أنواع BSON
pandas مكتبة
مكتبة تحليل بيانات Python تقرأ NDJSON عبر pd.read_json(path, lines=True) وتكتبه عبر df.to_json(path, orient='records', lines=True)