انتقل إلى المحتوى
Numio

تحويل JSON Schema إلى تعريفات Protobuf — Numio

يحوّل JSON Schema من نوع object إلى تعريف message بصيغة proto2. تُرقَّم الحقول بترتيب الخصائص؛ تصبح الخصائص المطلوبة "required" والبقية "optional" والمصفوفات "repeated"، وتصبح الكائنات المتداخلة رسائل message متداخلة مع حقل يستخدمها.

لديك JSON Schema لحدث وتريد مسودة أولى لرسالة .proto تعدّلها لخط gRPC أو Kafka.

JSON Schema

Protobuf

متى تستخدمها

  • لديك JSON Schema لحدث وتريد مسودة أولى لرسالة .proto تعدّلها لخط gRPC أو Kafka.
  • تريد التحقق من كيفية مطابقة الحقول العددية والنصية البسيطة في مخطط موجود مع أنواع protobuf قبل أن تكتب الرسالة بنفسك.

طريقة الاستخدام

  1. الصق JSON Schema يحتوي على "type": "object" في الجذر. يُؤخذ اسم الرسالة من "title" بصيغة PascalCase (أو من مفتاح "name")؛ وإن غاب كلاهما فالاسم Root.
  2. يجري التحويل في متصفحك؛ ولا توجد إعدادات.
  3. انسخ نص proto2 من لوحة Protobuf وراجع الأنواع قبل استخدامه في ملف .proto.

JSON Schema

{
  "title": "Order",
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "quantity": { "type": "integer" },
    "price": { "type": "number" },
    "paid": { "type": "boolean" },
    "tags": { "type": "array", "items": { "type": "string" } },
    "shipping": { "type": "object", "properties": { "city": { "type": "string" } } }
  },
  "required": ["id", "quantity"]
}

Protocol Buffers (proto2)

syntax = "proto2";

message Order {
  message Shipping {
    optional string city = 1;
  }

  required string id = 1;
  required int32 quantity = 2;
  optional double price = 3;
  optional bool paid = 4;
  repeated string tags = 5;
  optional Shipping shipping = 6;
}

التفاصيل والقيود

يجري التحويل في متصفحك بمحوّل الموقع الخاص؛ ولا يُرسَل المخطط إلى خادم.

يُطابَق integer مع int32 (أو int64 مع format int64 أو حدود خارج نطاق 32 بت)، وnumber مع double (أو float مع format float)، وboolean مع bool. وتُطابَق أنواع عناصر المصفوفات بالطريقة نفسها.

تصبح قيم enum النصية enum متداخلًا بقيم UPPER_SNAKE مسبوقة ببادئة، وتصبح مخططات additionalProperties إلى map<string, T>، ويشير $ref المحلي إلى definitions أو $defs إلى رسالة في المستوى الأعلى.

تؤول مصفوفات المصفوفات، وoneOf/anyOf ذات الفروع المتعددة غير null، والخصائص بلا نوع إلى string. ويُبلَّغ عن $ref يشير إلى ملف آخر كخطأ.

FAQ

هل يُنشئ proto3؟

لا. يبدأ الناتج دائمًا بـ syntax = "proto2" ويستخدم التسميات required/optional.

كيف يُختار اسم الرسالة؟

من "title" في الجذر بعد تحويله إلى PascalCase، فيصبح "Example Schema" إلى ExampleSchema، أو من مفتاح "name". وإن غاب كلاهما فاسم الرسالة Root. وتُسمّى الرسائل وقيم enum المتداخلة باسم خاصيتها.

كيف تُعالَج الحقول القابلة لـ null مثل ["string", "null"]؟

يُحذف جزء null ويستخدم الحقل النوع المتبقي، مثل optional double height لـ ["number", "null"]. فالحقول الاختيارية في proto2 يمكن أن تغيب أصلًا.

هل يُرفع مخططي إلى خادم؟

لا. تحوّل هذه الصفحة المخطط في المتصفح ولا تستدعي أي API على الخادم.

المواصفات والمراجع