5. نموذج البيانات
5.1 البنية العليا
يجب أن تتضمن وثيقة UEARM v0.1 الحقول العليا التالية:
| الحقل |
نوع البيانات |
إلزامي |
الوصف |
schema_version |
نص |
نعم |
إصدار مخطط البيانات |
action_id |
نص |
نعم |
معرّف الفعل الاقتصادي |
created_at |
تاريخ ووقت |
نعم |
وقت إنشاء الوثيقة |
identity |
كائن |
نعم |
الهوية ومصدر الطلب |
economic_action |
كائن |
نعم |
العملية الاقتصادية المطلوبة |
delegated_authority |
كائن |
نعم |
التفويض ونطاق السلطة |
policy |
كائن |
نعم |
مراجع السياسات |
execution_context |
كائن |
نعم |
بيئة التنفيذ |
governance |
كائن |
نعم |
قرار الحوكمة |
execution |
كائن |
نعم |
حالة التنفيذ |
evidence |
مصفوفة |
نعم |
سجلات الأدلة |
outcome |
كائن |
نعم |
النتيجة الحالية |
extensions |
كائن |
لا |
الامتدادات الخاصة بالتطبيق |
5.2 الهوية ومصدر الطلب (Identity & Provenance)
يجب أن يحتوي كائن الهوية على:
initiator_id: معرّف الجهة المبادرة.
initiator_type: نوع الجهة المبادرة.
request_id: معرّف الطلب.
تشمل أنواع الجهات المبادرة الأولية:
HUMAN
AI_AGENT
ORGANIZATION
SYSTEM
ينبغي حفظ مصدر الطلب وسلسلة التفويض عند الحاجة.
ولا يجوز اعتبار ادعاء الهوية غير المتحقق منه إثباتاً مستقلاً للهوية الموثوقة.
5.3 الفعل الاقتصادي (Economic Action)
يجب أن يحتوي كائن الفعل الاقتصادي على:
action_type: نوع الفعل.
resource: المورد الاقتصادي المعني.
parameters: معلمات الفعل.
تشمل أنواع الأفعال الأولية:
PROCUREMENT - المشتريات.
FINANCIAL_TRANSFER - التحويل المالي.
CAPITAL_ALLOCATION - تخصيص رأس المال.
PAYMENT_INITIATION - بدء الدفع.
RESOURCE_ALLOCATION - تخصيص الموارد.
CONTRACTUAL_COMMITMENT - الالتزام التعاقدي.
يجوز إضافة أنواع أخرى وفق آلية امتدادات موثقة أو إصدار لاحق.
يحدد حقل المورد الحساب أو الأصل أو العقد أو المورد الاقتصادي المرتبط بالفعل.
5.4 المعلمات الاقتصادية (Economic Parameters)
عندما يتضمن الفعل قيمة مالية، يجب تمثيل المبلغ كسلسلة عشرية نصية.
مثال صحيح:
"amount": "15000.00"
ولا يوصى بتمثيله باستخدام رقم فاصلة عائمة:
"amount": 15000.00
وذلك لتجنب الاعتماد على الحسابات الثنائية التقريبية في قرارات التفويض المالي.
يجب ربط المبلغ برمز عملة صريح، ويوصى باستخدام الرموز الأبجدية المعتمدة في ISO 4217.
يجب التمييز بين:
- المبلغ المطلوب.
- الحد الأقصى المصرح به.
- المبلغ المحجوز، عند تطبيق الحجز.
- المبلغ المنفذ.
- المبلغ الذي تمت تسويته، عند إثبات التسوية.
ولا يجوز دمج هذه القيم في حقل واحد.
5.5 السلطة المفوضة (Delegated Authority)
يجب أن يتضمن كائن التفويض:
- معرّف التفويض.
- الجهة المانحة للسلطة.
- الوكيل المصرح له.
- أنواع الأفعال المسموح بها.
- الحد المالي، عند انطباقه.
- العملة، عند وجود قيد عملة.
- فترة الصلاحية.
- حالة التفويض الحالية.
ينبغي أن يتضمن التفويض مرجعاً إلى المستند أو السجل الذي يثبت منح السلطة.
يجب التحقق من أن التفويض يشمل نوع الفعل ومعلماته الاقتصادية.
ولا يجوز تفسير التفويض بإجراء المشتريات على أنه تفويض تلقائي بإجراء التحويلات المالية.
5.6 السياسات والقيود (Policy & Constraints)
يجب أن يحدد كائن السياسات مراجع السياسات المطبقة.
عند إجراء تقييم للسياسات، ينبغي حفظ:
- معرّف السياسة.
- إصدار السياسة.
- وقت التقييم.
- مرجع سياق التقييم.
- نتيجة التقييم.
مجرد وجود مرجع لسياسة لا يثبت أنها خضعت للتقييم بنجاح.
5.7 سياق التنفيذ (Execution Context)
ينبغي أن يتضمن سياق التنفيذ:
- معرّف البيئة.
- معرّف نظام التنفيذ.
- المنطقة أو الولاية التنظيمية عند الحاجة.
- الطابع الزمني للسياق.
- مرجع سياق التزامن أو المعاملة.
يجب تقليل البيانات السياقية إلى الحد الضروري للفعل ومتطلبات الحوكمة.
5.8 قرار الحوكمة (Governance Decision)
يجب أن يتضمن كائن الحوكمة:
- معرّف القرار.
- قيمة القرار.
- وقت اتخاذ القرار.
- سبب القرار.
القيم الأولية للقرار:
ADMIT - قبول السماح بالانتقال إلى التنفيذ.
REJECT - رفض.
ESCALATE - تصعيد للمراجعة أو الموافقة الإضافية.
يجب ربط قرار ADMIT بالفعل والتفويض اللذين جرى تقييمهما.
وأي تغيير جوهري في معلمات الفعل يستلزم إعادة تقييم التفويض.
ولا يجوز تفسير ADMIT على أنه دليل على وقوع التنفيذ.
5.9 حالة التنفيذ (Execution State)
يجب أن يحتوي كائن التنفيذ على:
- الحالة الحالية.
- وقت آخر انتقال للحالة.
وينبغي أن يتضمن أيضاً:
- معرّف محاولة التنفيذ.
- مفتاح منع التكرار.
- معرّف المنفذ.
- حالة الإلغاء.
- مرجع إيصال التنفيذ.
يجب الاحتفاظ بسجل قابل للتدقيق لجميع انتقالات الحالات، حتى إذا كانت الوثيقة الرئيسية تعرض الحالة الأخيرة فقط.
5.10 الأدلة والتحقق (Evidence & Verification)
ينبغي أن يتضمن كل سجل دليل:
- معرّف الدليل.
- نوع الدليل.
- مصدر الدليل.
- وقت الالتقاط.
- معرّف الحدث أو المعاملة المرتبطة.
- مرجع سلامة الدليل، عند توفره.
تشمل أنواع الأدلة المحتملة:
COMMAND_RECORD
AUTHORIZATION_RECORD
POLICY_DECISION
EXECUTION_RECEIPT
SYSTEM_ACKNOWLEDGEMENT
SETTLEMENT_CONFIRMATION
STATE_TRANSITION
CANCELLATION_RECORD
يجب الفصل بين:
- 1. تسجيل الدليل.
- 2. التحقق من سلامة الدليل.
- 3. التحقق المستقل من الادعاء الذي يدعمه الدليل.
ولا يجوز اعتبار الدليل المسجل دليلاً متحققاً منه تلقائياً.
5.11 النتيجة (Outcome)
يجب أن يمثل كائن النتيجة أحدث حالة معروفة.
القيم الأولية:
PENDING
COMPLETED
PARTIALLY_COMPLETED
REJECTED
FAILED
CANCELLED
EXPIRED
UNRESOLVED
ينبغي أن تشير النتيجة إلى الأدلة التي تدعم تصنيفها.
ولا يعني اكتمال عملية التنفيذ بالضرورة اكتمال التسوية المالية أو الاقتصادية.
6. مخطط JSON للإصدار UEARM v0.1
يحدد مخطط JSON التالي العقد البنيوي الأولي للمواصفة.
يستخدم المخطط مسودة JSON Schema Draft 2020-12.
يتحقق هذا المخطط من البنية والحقول والقيود الأساسية، لكنه لا يحل محل التحقق التطبيقي من التفويض والسياسات وانتقالات الحالات والمعاني الاقتصادية.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://ouamarkom.com/spec/uearm/0.1/schema.json",
"title": "UEARM Economic Action",
"description": "Proposed Unified Economic Action Representation Model v0.1",
"type": "object",
"additionalProperties": false,
"required": [
"schema_version",
"action_id",
"created_at",
"identity",
"economic_action",
"delegated_authority",
"policy",
"execution_context",
"governance",
"execution",
"evidence",
"outcome"
],
"properties": {
"schema_version": {
"type": "string",
"const": "0.1"
},
"action_id": {
"$ref": "#/$defs/identifier"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"identity": {
"type": "object",
"additionalProperties": false,
"required": [
"initiator_id",
"initiator_type",
"request_id"
],
"properties": {
"initiator_id": {
"type": "string",
"minLength": 1
},
"initiator_type": {
"type": "string",
"enum": [
"HUMAN",
"AI_AGENT",
"ORGANIZATION",
"SYSTEM"
]
},
"request_id": {
"$ref": "#/$defs/identifier"
},
"provenance_ref": {
"type": "string"
}
}
},
"economic_action": {
"type": "object",
"additionalProperties": false,
"required": [
"action_type",
"resource",
"parameters"
],
"properties": {
"action_type": {
"type": "string",
"minLength": 1
},
"resource": {
"type": "object",
"required": [
"resource_type",
"resource_id"
],
"properties": {
"resource_type": {
"type": "string"
},
"resource_id": {
"type": "string"
}
},
"additionalProperties": false
},
"parameters": {
"type": "object",
"minProperties": 1
},
"requested_amount": {
"$ref": "#/$defs/money"
},
"beneficiary_id": {
"type": "string"
}
}
},
"delegated_authority": {
"type": "object",
"additionalProperties": false,
"required": [
"grant_id",
"granting_principal",
"authorized_agent",
"permitted_action_types",
"status",
"valid_from",
"valid_until"
],
"properties": {
"grant_id": {
"$ref": "#/$defs/identifier"
},
"granting_principal": {
"type": "string",
"minLength": 1
},
"authorized_agent": {
"type": "string",
"minLength": 1
},
"permitted_action_types": {
"type": "array",
"minItems": 1,
"uniqueItems": true,
"items": {
"type": "string"
}
},
"maximum_amount": {
"$ref": "#/$defs/money"
},
"status": {
"type": "string",
"enum": [
"ACTIVE",
"REVOKED",
"EXPIRED",
"SUSPENDED"
]
},
"valid_from": {
"type": "string",
"format": "date-time"
},
"valid_until": {
"type": "string",
"format": "date-time"
},
"authority_reference": {
"type": "string"
},
"revocation_reference": {
"type": "string"
}
}
},
"policy": {
"type": "object",
"additionalProperties": false,
"required": [
"policy_ids"
],
"properties": {
"policy_ids": {
"type": "array",
"items": {
"type": "string"
},
"uniqueItems": true
},
"policy_version": {
"type": "string"
},
"evaluation_reference": {
"type": "string"
}
}
},
"execution_context": {
"type": "object",
"additionalProperties": false,
"required": [
"environment_id",
"execution_system_id"
],
"properties": {
"environment_id": {
"type": "string"
},
"execution_system_id": {
"type": "string"
},
"region": {
"type": "string"
},
"context_reference": {
"type": "string"
}
}
},
"governance": {
"type": "object",
"additionalProperties": false,
"required": [
"decision_id",
"decision",
"decided_at",
"reason_code"
],
"properties": {
"decision_id": {
"$ref": "#/$defs/identifier"
},
"decision": {
"type": "string",
"enum": [
"ADMIT",
"REJECT",
"ESCALATE"
]
},
"decided_at": {
"type": "string",
"format": "date-time"
},
"reason_code": {
"type": "string"
},
"authority_snapshot_ref": {
"type": "string"
},
"policy_evaluation_ref": {
"type": "string"
}
}
},
"execution": {
"type": "object",
"additionalProperties": false,
"required": [
"state",
"updated_at"
],
"properties": {
"state": {
"type": "string",
"enum": [
"CREATED",
"PENDING",
"AUTHORIZED",
"REJECTED",
"EXECUTING",
"PARTIALLY_EXECUTED",
"COMPLETED",
"FAILED",
"CANCEL_REQUESTED",
"CANCELLED",
"EXPIRED"
]
},
"updated_at": {
"type": "string",
"format": "date-time"
},
"attempt_id": {
"type": "string"
},
"idempotency_key": {
"type": "string"
},
"executor_id": {
"type": "string"
},
"executed_amount": {
"$ref": "#/$defs/money"
},
"cancel_reference": {
"type": "string"
}
}
},
"evidence": {
"type": "array",
"items": {
"$ref": "#/$defs/evidence"
}
},
"outcome": {
"type": "object",
"additionalProperties": false,
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"PENDING",
"COMPLETED",
"PARTIALLY_COMPLETED",
"REJECTED",
"FAILED",
"CANCELLED",
"EXPIRED",
"UNRESOLVED"
]
},
"settled_amount": {
"$ref": "#/$defs/money"
},
"outcome_reference": {
"type": "string"
},
"verified_at": {
"type": "string",
"format": "date-time"
},
"verification_reference": {
"type": "string"
}
}
},
"extensions": {
"type": "object"
}
},
"$defs": {
"identifier": {
"type": "string",
"minLength": 1,
"maxLength": 128
},
"money": {
"type": "object",
"additionalProperties": false,
"required": [
"amount",
"currency"
],
"properties": {
"amount": {
"type": "string",
"pattern": "^(0|[1-9][0-9]*)(\\.[0-9]+)?$"
},
"currency": {
"type": "string",
"pattern": "^[A-Z]{3}$"
}
}
},
"evidence": {
"type": "object",
"additionalProperties": false,
"required": [
"evidence_id",
"evidence_type",
"source",
"captured_at"
],
"properties": {
"evidence_id": {
"$ref": "#/$defs/identifier"
},
"evidence_type": {
"type": "string",
"minLength": 1
},
"source": {
"type": "string",
"minLength": 1
},
"captured_at": {
"type": "string",
"format": "date-time"
},
"event_reference": {
"type": "string"
},
"integrity_reference": {
"type": "string"
},
"verification_status": {
"type": "string",
"enum": [
"NOT_VERIFIED",
"INTEGRITY_CHECKED",
"INDEPENDENTLY_VERIFIED",
"REJECTED"
]
}
}
}
}
}
6.1 متطلبات التحقق من المخطط
يجب على التطبيق:
- 1. التحقق من الوثيقة وفق إصدار المخطط المعلن.
- 2. رفض الوثائق التي تفتقد حقولاً إلزامية.
- 3. رفض أنواع البيانات والقيم غير الصحيحة.
- 4. رفض المبالغ المالية ذات التنسيق غير الصحيح.
- 5. رفض أسماء الخصائص المكررة عند مرحلة تحليل JSON.
- 6. تنفيذ التحقق الدلالي بعد التحقق البنيوي.
- 7. توثيق آلية التعامل مع إصدارات المخطط غير المدعومة.
قد تتعامل بعض أدوات JSON Schema مع الكلمة "format" بوصفها وصفاً أو تعليقاً لا شرط تحقق إلزامياً. لذلك يجب التحقق من صحة التواريخ والتنسيقات الحساسة صراحةً في طبقة التطبيق.