JSON Schema

Elk bestand in data/ heeft een JSON Schema (draft-07) in schema/. De schema's worden gegenereerd uit de TypeScript-types, zodat de types, de schema's en de data niet uit elkaar kunnen groeien: CI faalt wanneer een van de drie het oneens is.

Databestand	Schema
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

De $id van elk schema is zijn URL op deze site, bv. https://pieterjanscheir.github.io/belgica/schema/courts.schema.json. Ze zitten ook in het npm-package als belgica/schema/courts.schema.json.

De data valideren

Python

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

# Pin een releasetag die schema/ bevat; tot de eerste uit is, gebruik 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

Dit wil je vooral wanneer je een kopie van de data bijhoudt (een fork met extra records, een gecachete download) en wilt weten of ze nog de structuur heeft die het package verwacht.

Types genereren voor andere talen

Omdat de schema's standaard zijn, kun je modellen genereren in plaats van ze met de hand te schrijven: datamodel-code-generator voor Python (Pydantic), quicktype voor C#, Go, Java, Kotlin, Swift en meer.

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

datapackage.json

De root van de repository heeft een datapackage.json, een Frictionless Data Package-descriptor: het standaard metadatabestand voor open datasets. Het vermeldt elk databestand met zijn titel, beschrijving, schema, officiële bronnen, licentie, en twee velden van onszelf:

• lastReviewed: de dag waarop de dataset voor het laatst tegen haar bronnen is gecontroleerd;
• reviewEveryMonths: hoe vaak ze opnieuw gecontroleerd moet worden. De actualiteitscontrole opent een issue wanneer een dataset achterstallig is.