JSON Schema

Ogni file in data/ ha un JSON Schema (draft-07) in schema/. Gli schemi sono generati dai tipi TypeScript, quindi tipi, schemi e dati non possono divergere: la CI fallisce quando uno dei tre non concorda con gli altri.

File di dati	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

Il $id di ogni schema è il suo URL su questo sito, per esempio https://pieterjanscheir.github.io/belgica/schema/courts.schema.json. Si trovano anche nel package npm come belgica/schema/courts.schema.json.

Validare i dati

Python

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

# Fissa un release tag che includa schema/; finché non esce il primo, usa 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

Ti servirà soprattutto quando conservi una copia dei dati (un fork con record in più, un download in cache) e vuoi sapere se ha ancora la struttura che il package si aspetta.

Generare tipi per altri linguaggi

Poiché gli schemi sono standard, puoi generare i modelli invece di scriverli a mano: datamodel-code-generator per Python (Pydantic), quicktype per C#, Go, Java, Kotlin, Swift e altri.

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

datapackage.json

La root del repository contiene un datapackage.json, un descrittore Frictionless Data Package: il file di metadati standard per i dataset aperti. Elenca ogni file di dati con titolo, descrizione, schema, fonti ufficiali, licenza e due campi nostri:

• lastReviewed: il giorno in cui il dataset è stato verificato l'ultima volta rispetto alle sue fonti;
• reviewEveryMonths: ogni quanto deve essere verificato di nuovo. Il controllo di aggiornamento apre una issue quando un dataset è in ritardo.