JSON Schema

لكل ملف في data/ مخطط JSON Schema (draft-07) في schema/. تُولَّد المخططات من أنواع TypeScript، فلا يمكن أن تتباعد الأنواع والمخططات والبيانات: يفشل CI حين يختلف أي من الثلاثة.

ملف البيانات	المخطط
data/judicial-areas.json	judicial-areas.schema.json
data/arrondissements.json	arrondissements.schema.json
data/cantons.json	cantons.schema.json
data/canton-boundaries.json	canton-boundaries.schema.json
data/municipalities.json	municipalities.schema.json
data/regions.json	regions.schema.json
data/provinces.json	provinces.schema.json
data/courts.json	courts.schema.json
data/prisons.json	prisons.schema.json
data/houses-of-justice.json	houses-of-justice.schema.json
data/postal-codes.json	postal-codes.schema.json
data/interest-rates.json	interest-rates.schema.json

قيمة $id لكل مخطط هي رابطه على هذا الموقع، مثل https://pieterjanscheir.github.io/belgica/schema/courts.schema.json. وهي موجودة أيضًا في حزمة npm باسم belgica/schema/courts.schema.json.

التحقق من البيانات

Python

import json
from urllib.request import urlopen
from jsonschema import validate  # pip install jsonschema

# ثبّت release tag يتضمن schema/؛ وإلى أن يصدر أول واحد، استخدم main
TAG = "main"
BASE = f"https://raw.githubusercontent.com/pieterjanscheir/belgica/{TAG}"
courts = json.load(urlopen(f"{BASE}/data/courts.json"))
schema = json.load(urlopen(f"{BASE}/schema/courts.schema.json"))
validate(courts, schema)

TypeScript

import { Ajv } from 'ajv'
import addFormats from 'ajv-formats'
import courts from 'belgica/data/courts.json' with { type: 'json' }
import schema from 'belgica/schema/courts.schema.json' with { type: 'json' }

const ajv = new Ajv()
addFormats(ajv)
ajv.validate(schema, courts) // true

ستحتاج إلى هذا غالبًا حين تحتفظ بنسخة من البيانات (fork فيه سجلات إضافية، أو تنزيل مخزَّن مؤقتًا) وتريد أن تعرف أنها لا تزال بالبنية التي تتوقعها الحزمة.

توليد الأنواع للغات أخرى

لأن المخططات قياسية، يمكنك توليد النماذج بدلًا من كتابتها يدويًا: datamodel-code-generator لـPython (Pydantic)، وquicktype لـC# وGo وJava وKotlin وSwift وغيرها.

datamodel-codegen --input courts.schema.json --input-file-type jsonschema --output courts.py

datapackage.json

في جذر المستودع ملف datapackage.json، وهو واصف Frictionless Data Package: ملف البيانات الوصفية القياسي لمجموعات البيانات المفتوحة. يسرد كل ملف بيانات بعنوانه ووصفه ومخططه ومصادره الرسمية وترخيصه، وحقلين خاصين بنا:

• lastReviewed: آخر يوم رُوجعت فيه مجموعة البيانات مقابل مصادرها؛
• reviewEveryMonths: كم مرة يجب مراجعتها من جديد. يفتح فحص الحداثة issue حين تتأخر مراجعة مجموعة بيانات.