JSON Schema

Każdy plik w data/ ma JSON Schema (draft-07) w schema/. Schematy są generowane z typów TypeScriptu, więc typy, schematy i dane nie mogą się rozjechać: CI kończy się błędem, gdy którekolwiek z trzech się nie zgadza.

Plik z danymi	Schemat
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 każdego schematu to jego URL na tej stronie, np. https://pieterjanscheir.github.io/belgica/schema/courts.schema.json. Są też w pakiecie npm jako belgica/schema/courts.schema.json.

Walidacja danych

Python

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

# Przypnij release tag, który zawiera schema/; dopóki pierwszy nie wyjdzie, użyj 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

Przyda się to głównie wtedy, gdy trzymasz własną kopię danych (fork z dodatkowymi rekordami, pobraną kopię w cache) i chcesz wiedzieć, czy nadal ma strukturę, jakiej oczekuje pakiet.

Generowanie typów dla innych języków

Ponieważ schematy są standardowe, możesz generować modele zamiast pisać je ręcznie: datamodel-code-generator dla Pythona (Pydantic), quicktype dla C#, Go, Javy, Kotlina, Swifta i innych.

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

datapackage.json

Katalog główny repozytorium zawiera datapackage.json, deskryptor Frictionless Data Package: standardowy plik metadanych dla otwartych zbiorów danych. Wymienia każdy plik z danymi wraz z tytułem, opisem, schematem, oficjalnymi źródłami, licencją i dwoma naszymi własnymi polami:

• lastReviewed: dzień, w którym zbiór danych był ostatnio sprawdzany ze źródłami;
• reviewEveryMonths: jak często trzeba go sprawdzać ponownie. Kontrola aktualności otwiera issue, gdy termin sprawdzenia zbioru minął.