Amsterdam Schema Specificatie

De meest recente aanpassing aan deze specificatie is:
§ 9.1 [2.2.0] dataclass atribuut toegevoegd (2023-01-12)

1. Introductie

Doelstelling
Alle data van gemeente Amsterdam binnen één machine verwerkbaar universeel format beschrijven, zodat het geautomatiseerd verwerkt en ontsloten kan worden. En zo vanuit de tada principes bij dragen aan een transparante, datagedreven organisatie.

Het Amsterdam Schema is een standaard voor het beschrijven van datasets. De structuur van de data kan samen met meta-informatie in een machineverwerkbaar format vastgelegd worden. Zo kunnen datasets automatisch verwerkt en ontsloten worden.

Dit document legt uit hoe een dataset volgens de Amsterdam Schema-standaard beschreven wordt.

Neem bijvoorbeeld een dataset over monumenten.
Van deze dataset kan worden vastgelegd:

dat het de object typen standbeelden en gebouwen heeft,
dat gebouwen de eigenschappen bouwjaar (getal), type (enum), functie (tekst) hebben.
en wat type en functie precies betekent.

Note: Een actueel overzicht van gepubliceerde Amsterdam Schema’s is te vinden op GitHub.

Note: Amsterdam Schema is gebaseerd op JSON Schema’s.

1.1. Overzicht

Een dataset wordt beschreven in één of meer JSON bestanden.

Binnen deze bestanden bestaan de volgende niveaus:

dataset: Een samenhangende collectie van data met één beheerder of beherende instantie. Zoals bedoeld in DCAT. Op dit niveau wordt voornamelijk meta-informatie over de herkomst en aard van de data meegegeven, zoals de naam, beschrijving, licentie en publicatiedatum. Een dataset bevat minstens één tabel.
tabel: Beschrijft een type object dat in de dataset voorkomt. Bevat een set van velden die beschrijft welke eigenschappen datarijen in deze tabel moeten of mogen bezitten.
veld: Beschrijft de eigenschappen van rijen in een tabel, zoals de naam en het datatype van een eigenschap. Vergelijkbaar met de kolommen van een database.

Note: Binnen Amsterdam Schema wordt de Data Catalog Vocabulary (hierna DCAT) standaard gebruikt. DCAT is een naamgevingsstandaard voor het publiceren van datacatalogi op het web.

2. Dataset

Met een dataset wordt een dataset zoals gedefinieerd in DCAT bedoeld. DCAT definieert een dataset als volgt:

Dataset A collection of data, published or curated by a single agent or identifiable community. The notion of dataset in DCAT is broad and inclusive, with the intention of accommodating resource types arising from all communities. Data comes in many forms including numbers, text, pixels, imagery, sound and other multi-media, and potentially other types, any of which might be collected into a dataset. (From Data Catalog Vocabulary (DCAT) - Version 2 § dcat-scope)

2.1. Verplichte attributen

Een dataset binnen Amsterdam Schema bestaat uit een JSON bestand met in ieder geval de volgende velden:

`id`	`identifier`	Unieke identifier voor deze dataset. Moet voldoen aan § 5 Naamgeving. Conform DCAT § resource_identifier.
`type`	`schema-type`	Type van dit bestand, in dit geval `"dataset"`.
`status`	string	Publicatiestatus van de dataset Toegestane waarden "beschikbaar" "niet_beschikbaar"
`auth`	string \| array	geautoriseerde scope(s). Voor openbare data: `"OPENBAAR"`. zie § 7.2 Autorisatie
`authorizationGrantor`	string	E-mailadres van de afdeling verantwoordelijk voor autorisatie op deze dataset. Dit is meestal de bronhouder. Aan dit adres worden authorisatie verzoeken gericht.
`creator`	string	Team, afdeling of organisatie die de data produceert, meestal de bronhouder. Wanneer data van meerdere bronhouders wordt gecomineerd, wordt hier de opdrachtgever bedoelt.
`owner`	string	Juridisch eigenaar van de data. Bijvoorbeeld `"Gemeente Amsterdam, Directie Wonen"` of `"Centraal Bureau voor de Statistiek"` Default: `"Gemeente Amsterdam"`
`publisher`	string \| publisher-ref	Het team verantwoordelijk voor het technisch ontsluiten van de data. Meestal het datateam. Conform DCAT § resource_publisher
`tables`	array	Tabellen in deze dataset. Moet minimaal 1 element bevatten. Valide elementen een tabel json object een referentie naar een JSON bestand van een tabel. Zie § 2.3 Tabelreferenties voor details.

Let op: Zie § 5 Naamgeving voor de eisen waaraan id moet voldoen.

Note: Als een dataset nog niet klaar is voor publicatie, zet de status dan op "niet_beschikbaar". Zo wordt de dataset nog niet zichtbaar in doelsystemen.

Een minimale dataset definitie. De 'title' en 'description' velden zijn niet verplicht, maar het is best practice ze toe te voegen.

{
  "id": "bekendeAmsterdammers",
  "type": "dataset",
  "title": "Bekende Amsterdammers",
  "description": "Een collectie van bekende Amsterdammers.\n (Een voorbeeld dataset)",
  "version": "1.0.0",
  "status": "beschikbaar",
  "publisher": "Team Bekende Amsterdammers",
  "creator": "myBronhouder",
  "auth": "OPENBAAR",
  "authorizationGrantor": "tba@amsterdam.nl",
  "owner": "Gemeente Amsterdam",
  "tables": [
    {
      "$ref": "personen/v1.0.0",
      "id": "personen"
    }
  ]
}

Best Practice Zet bij datasets met meer dan één tabel alle tabellen in hun een eigen bestand en gebruik tabel referenties. Dit komt de leesbaarheid ten goede en maakt versioning mogelijk.

2.2. Optionele attributen

Naast bovenstaande verplichte attributen mag een dataset ook de volgende eigenschappen bevatten.

`contactPoint`	`contact`	Contactgegevens van de persoon of afdeling verantwoordelijk voor eerstelijns ondersteuning bij deze dataset. Hier kunnen mensen met vragen over de dataset terecht. (Deze gegevens worden publiek zichtbaar.) Wanneer dit veld niet is gegeven, is impliciet de default waarde van toepassing. Default: `{"name": "Datapunt", "email": "datapunt@amsterdam.nl"}`
`title`	string	zie § 7.1 Omschrijving DCAT § Property:resource_title
`description`	string	zie § 7.1 Omschrijving DCAT § Property:resource_description
`provenance`	string	zie § 7.3 Provenance
`reasonsNonPublic`	array(`nonPubReason`)	een of meer gronden voor het niet openbaar maken van data obv uitzonderingen in Hoofdstuk 5 van de [Woo]. (Vanaf 1 mei 2022 verplicht wanneer `auth` niet gelijk is aan `"OPENBAAR"`) zie § 7.2 Autorisatie
`version`	`version-string`	Het versie nummer van deze dataset.
`homepage`	`uri`	Homepage van de dataset
`crs`	enum(string)	Coordinate reference System Opties "EPSG:28992" "EPSG:4326" "EPSG:7415" Dit veld is verplicht voor datasets waarvan één of meerdere tabellen één of meer § 4.3.6 geometrie velden bevatten en waarvan de crs niet al in de tabel of veld gedefinieerd is. Zie SDOW best practices § CRS-background voor meer informatie.

Best Practice Voeg altijd op zijn minst een title en description toe.

2.2.1. DCAT velden

Het is mogelijk op dataset niveau extra eigenschappen met meta-gegevens mee te geven. Dit kan indien gewenst worden gebruikt om automatisch een DCAT catalogus te genereren. De volgende velden zijn toegestaan:

`language`	string	Taal van de dataset volgens ISO 639-1 of ISO 639-2 Conform DCAT § resource_language
`dateCreated`	`date-time`	Datum van publicatie. Conform DCAT § resource_release_date
`dateModified`	`date-time`	Meest recente datum waarop de dataset is aangepast. Conform DCAT § resource_update_date
`accrualPeriodicity`	string	Frequentie waarmee de dataset gepubliceerd wordt. Conform DCAT § dataset_frequency
`spatialDescription`	string
`spatialCoordinates`	Geometry	Een GeoJSON geometry
`theme`	array (string)	Array van themas Conform DCAT § resource_theme
`hasBeginning`	`date-time`
`hasEnd`	`date-time`
`objective`	string
`temporalUnit`	string	Eenheid van temporaliteit Conform? DCAT § dataset_temporal_resolution
`spatial`	string
`legalBasis`	string
`keywords`	array (string)	Array van keywords Conform DCAT § resource_keyword
`license`	string	Licentie Conform DCAT § resource_license

Note: De intentie is dat alle relevante DCAT velden te modelleren zijn. Wanneer velden ontbreken die wel in de DCAT zijn opgenomen, zullen deze worden toegevoegd.

Niet alle DCAT velden zijn gemodelleerd. Daarnaast zijn komt van sommige velden de naamgeving niet overeen met de DCAT spec.

Sommige velden missen een beschrijving

2.3. Tabelreferenties

Tabelreferenties zijn verwijzingen naar JSON-bestanden waarin een tabel gedefinieerd wordt. Dit maakt het mogelijk om elke tabel in een dataset in een eigen bestand te definieeren. Tabel referenties zijn gebaseerd op JSON Schema § ref.

Een tabel referentie is een JSON object met in ieder geval de volgende attributen:

`id`	`identifier`	Binnen deze dataset unieke identifier voor deze tabel. Zou gelijk moeten zijn aan tabel.id. Moet voldoen aan § 5 Naamgeving.
`$ref`	`uri-reference`	URI-Reference naar JSON bestand met de tabel definitie zonder de bestandsextensie. De reference is altijd relatief aan de locatie van het dataset bestand.

Optioneel kan een object met actieve versies van de tabel worden meegegeven. Actieve versies zijn alle versies die actief worden onderhouden en ondersteund.

activeVersions

object

Dit object bevat elementen van de vorm:

"MAJOR.MINOR.PATCH": "path/to/tableVersion/file"

activeVersions moet in iedergeval een element bevatten voor de versie waaraan wordt verwezen in het $ref veld.

Wanneer activeVersions is gedefinieerd, wordt de versie waaraan verwezen wordt in $ref als de default versie beschouwd.

Zie § 3.5 Versionering voor meer details over versionering en versienummers.

Note: Eventuele non-default versies worden in de huidige versie van DSO-api nog niet opgenomen.

Elk tabel definitie bestand zou samen met andere versies van dezelfde tabel in een eigen map moeten staan waarvan de naam gelijk is aan de tabel id. De bestandsnaam van een tabel definite bestand zou gelijk moeten zijn aan het versienummer van de tabel voorafgegaan door 'v' met een '.json' extensie. Het pad gezien vanuit de locatie van het dataset bestand zou dus de volgende vorm moeten hebben:

<tabelid>/v<major>.<minor>.<patch>.json

Van deze bestandsnaam en padstructuur moet niet worden afgeweken behalve als daar een zwaarwegende reden voor is.

Voorbeeld van een dataset met twee tabel referenties.

Een locaties tabel in ./locaties/v1.0.0.json.
En een personen tabel in ./personen/v2.0.1.json, waarvan ook de oudere versie 1.3.0 beschikbaar is.

{  "id": "bekendeAmsterdammers",  "type": "dataset",  "title": "Bekende Amsterdammers",  "description": "Bekende historische personen die in Amsterdam hebben gewoond.\n (Een voorbeeld dataset)",  "status": "beschikbaar",  "owner": "Gemeente Amsterdam",  "publisher": "myDataTeam",  "creator": "myBronhouder",  "auth": "OPENBAAR",  "authorizationGrantor": "myDataTeam@amsterdam.nl",  "tables": [    {      "$ref": "personen/v2.0.1",      "id": "personen",      "activeVersions": {        "1.3.0": "personen/v1.3.0",        "2.0.1": "personen/v2.0.1"      }    },    {      "$ref": "locaties/v1.0.0",      "id": "locaties"    }  ]}

2.4. Publisherreferenties

Publisherreferenties zijn verwijzingen naar JSON-bestanden waarin een publisher gedefinieerd wordt. Publisher referenties zijn gebaseerd op JSON Schema § ref.

Een publisher referentie is een JSON object met 1 attribuut:

$ref uri-reference URI-Reference naar JSON bestand met de publisher definitie zonder de bestandsextensie. De reference is altijd van de vorm publishers/<BESTANDSNAAM>. Bijvoorbeeld: publishers/SOEB

3. Tabel

Een tabel definitie bevat het schema waaraan de er toe behorende datarijen moeten voldoen. Binnen het schema worden velden gedefinieerd die datarijen moeten of mogen bezitten. Daarnaast kan aan een tabel meta informatie en autorisatie instellingen worden meegegeven.

3.1. Verplichte attributen

Een tabel binnen Amsterdam Schema is een JSON object met in ieder geval de volgende attributen.

`id`	`identifier`	Naam van de tabel. Unieke (binnen de parent dataset) identifier voor deze tabel. Moet voldoen aan § 5 Naamgeving.
`type`	`schema-type`	Type van dit bestand, in dit geval `"table"`.
`version`	`version-string`	Het versie nummer van deze tabel. Zie § 3.5 Versionering
`schema`	object	Het schema van objecten in de tabel. zie § 3.3 Schema Valide elementen een schema-object een referentie naar een JSON bestand van een schema-object.

Let op: Zie § 5 Naamgeving voor de eisen waaraan id moet voldoen.

Voorbeeld van een minimale tabel definitie. De title en description velden zijn niet verplicht, maar het is best practice ze toe te voegen.

{  "id": "personen",  "type": "table",  "title": "Personen",  "description": "Bekende Amsterdamse personen",  "version": "1.0.0",  "schema": {    "$schema": "http://json-schema.org/draft-07/schema#",    "type": "object",    "required": [      "id",      "schema"    ],    "display": "naam",    "properties": {      "schema": {        "$ref": "https://schemas.data.amsterdam.nl/schema@v1.1.1#/definitions/schema"      },      "id": {        "type": "string",        "description": "Unieke aanduiding persoon"      },      "naam": {        "type": "string",        "description": "Volledige naam van de persoon"      }    }  }}

3.2. Optionele attributen

Een tabel mag daarnaast de volgende attributen bezitten:

`title`	string	zie § 7.1 Omschrijving Default: Gelijk aan `id`.
`description`	string	zie § 7.1 Omschrijving
`shortname`	string	Verkorte unieke naam van de tabel. zie § 5 Naamgeving
`derivedFrom`	array	De datasets waar deze view op gebaseerd is. e.g. `<dataset>:<tabel>`. Dit attribuut is enkel noodzakelijk wanneer de dataset een view is.
`auth`	string \| array	geautoriseerde scope(s). Default: gelijk aan waarde in dataset/`auth`, zie § 7.2 Autorisatie.
`reasonsNonPublic`	array(`nonPubReason`)	een of meer gronden voor het niet openbaar maken van data obv uitzonderingen in Hoofdstuk 5 van de [Woo]. (Vanaf 1 mei 2022 verplicht wanneer de dataset openbaar is maar het `auth` atribuut van de tabel niet gelijk is aan "OPENBAAR") zie § 7.2 Autorisatie
`provenance`	string	zie § 7.3 Provenance
`dateCreated`	`date-time`	Datum van publicatie.
`dateModified`	`date-time`	Meest recente datum waarop de tabel is aangepast.
`license`	string	Licentie
`temporal`	temporal-object	Definieert tijdsafhankelijke geldigheid van objecten. zie § 3.4 Temporaliteit
`crs`	enum(string)	Coordinate reference System Opties "EPSG:28992" "EPSG:4326" "EPSG:7415" Dit veld is verplicht voor tabellen waarin één of meer § 4.3.6 geometrie velden zitten en waarvoor niet op dataset-of veldniveau al een crs gedefinieerd is. Zie SDOW best practices § CRS-background voor meer informatie.
`dataclass`	enum(string)	Soort data in de tabel Opties "structured" "blob" "event" Default: `"structured"`

Best Practice Voeg altijd op zijn minst een title en description toe.

3.3. Schema

Het schema object beschrijft de eigenschappen van rijen in de tabel.

Een schema object moet in ieder geval de volgende attributen bezitten:

`$schema`	string	constant `"http://json-schema.org/draft-07/schema#"`
`type`	string	constant `"object"`
`required`	array (string)	Namen van velden die niet `null` mogen bevatten. Bevat minstens `"schema"`.
`display`	string	De naam van het veld dat titel van objecten bevat. Voor afnemers die een samenvattende titel van een object willen tonen. Default: gelijk aan `identifier`. Het veld dat hier genoemd wordt mag geen `auth` attribuut bevatten.
`properties`	object	Collectie van velden die rijen in de tabel mogen bezitten. Bevat daarnaast een 'schema.$ref' attribuut. Veldnamen moeten beginnen met een kleine letter gevolgd door een alfanumerieke reeks en moeten voldoen aan § 5 Naamgeving.
`properties.schema`	§ref	constant `{"$ref":"https://schemas.data.amsterdam.nl/schema@v1.2.0#/definitions/schema"}`

Daarnaast mag een schema object de volgende attributen bezitten:

`$id`	string
`additionalProperties`	bool	constant `false` Geeft aan dat objecten extra velden mogen hebben.
`mainGeometry`	string	De naam van het primaire geometrie veld. Default: `"geometry"` zie § 4.3.6 geometrie
`identifier`	string \| array (string)	Naam van het veld dat de unieke identifier van een rij is, of een array van veldnamen die samen een unieke key vormen. Het veld of de velden waar hier naar verwezen wordt moeten van het type string of het type integer zijn. en mogen geen `auth` attribuut bevatten.

Het identifier veld moet string zijn. De array optie wordt binnenkort verwijderd.

Voorbeeld van een schema.

Het display veld zorgt ervoor dat niet de "id" de maar de "naam" van een persoon als samenvattende titel wordt gebruikt.

{  "id": "personen",  "type": "table",  "title": "Personen",  "description": "Bekende Amsterdamse personen",  "version": "1.0.0",  "schema": {    "$schema": "http://json-schema.org/draft-07/schema#",    "type": "object",    "required": [      "id",      "schema"    ],    "display": "naam",    "properties": {      "schema": {        "$ref": "https://schemas.data.amsterdam.nl/schema@v1.1.1#/definitions/schema"      },      "id": {        "type": "string",        "description": "Unieke aanduiding persoon"      },      "naam": {        "type": "string",        "description": "Volledige naam van de persoon"      }    }  }}

3.4. Temporaliteit

Als een tabel objecten bevat die slechts beperkte tijd geldig zijn of waarvan over de tijd verschillende versies geldig zijn, wordt dit in de tabel definitie met het temporal object aangegeven.

Een temporal object heeft in ieder geval de volgende attributen.

`identifier`	string	Naam van het veld dat de versie van een object identificeert. De combinatie van dit veld en het veld waarnaar wordt verwezen in het `identifier` attribuut van schema moet uniek zijn voor elke regel in de tabel.
`dimensions.geldigOp`	array (string)	De namen van de velden die de geldigheid van een object begrenzen. Heeft 2 elementen.

Note: Momenteel wordt alleen de dimensie "geldigOp" ondersteund. In de toekomst kunnen hier andere dimensies zoals "inWerkingOp" en "beschikbaarOp" aan toegevoegd worden.

De array in temporal.dimensions.geldigOp bevat de namen van twee velden met begin en eind geldigheid van een object. Een object in de tabel is geldig binnen het gesloten interval ["beginGeldigheid", "eindGeldigheid"].

Als een tabel niet temporeel is kan het temporal object worden weggelaten.

Voorbeeld van een temporal object.

"temporal": {
    "identifier": "volgnummer",
    "dimensions": {
        "geldigOp": ["beginGeldigheid", "eindGeldigheid"]
    }
}

3.5. Versionering

Verschillende versies van een tabel worden van elkaar onderscheiden door middel van versienummers.

Een geversioneerde tabel moet in een eigen bestand staan. De bestandsnaam van de tabel zou gelijk moeten zijn aan het versienummer van de tabel voorafgegaan door 'v' met een '.json' extensie. Zie § 2.3 Tabelreferenties voor hoe in de dataset naar een tabel bestand moet worden verwezen.

Voor versienummers wordt gebruik gemaakt van semantic versioning. Dit betekent dat de versienummers betekenis hebben. Zo valt met een blik op het versienummer iets te zeggen over de aard van de gedane aanpassing.

Het versie nummer bestaat uit 3 getallen gescheiden door punten MAJOR.MINOR.PATCH:

major versie bumps vinden plaats bij veranderingen die niet backwards compatible zijn. Dit zijn alle aanpassingen waarbij het kan voorkomen dat bestaande data niet aan het nieuwe schema voldoet.
minor versies zijn volledig backwards compatible. Alle bestaande data, blijft geldig in het nieuwe schema.
patch versies bevatten alleen metadata aanpassingen, waarbij de datastructuur gelijk blijft.

Metadata aanpassingen zijn veranderingen aan een of meer van de volgende attributen:

"title" op dataset, tabel of veld niveau
"description" op dataset, tabel of veld niveau
"shortname" op dataset, tabel of veld niveau
"unit"
"display"

Backwards compatible veranderingen zijn:

een optioneel veld is toegevoegd.
input mogelijkheden van een veld zijn verruimd (zoals wanneer een waarde aan enum is toegevoegd, of een maximum of minimum is verruimd).
een verplicht veld is optioneel gemaakt

Niet backwards compatible zijn alle andere aanpassingen.

Voorbeelden van niet backwards compatible aanpassingen:

een nieuw verplicht veld is toegevoegd
een optioneel veld is verplicht gemaakt
een veld is verwijderd of hernoemd
input mogelijkheden van een veld zijn beperkt. (zoals wanneer een waarde uit een enum is verwijderd, of een maximum of minimum verkleind)

Zie § 2.3 Tabelreferenties voor het toevoegen van verschillende versies van een tabel.

Voorbeeld aan versie "1.2.1" van de personen tabel wordt een nieuw optioneel veld toegevoegd en aan een bestaand enum veld wordt een optie toegevoegd.

Dit zijn backwards compatible veranderingen dus het minor versie nummer wordt opgehoogd en de nieuwe versie wordt "1.3.0".

De nieuwe tabel wordt in een nieuw bestand personen/v1.3.0.json geplaatst.

personen/v1.2.1.json

{  "id": "personen",  "type": "table",  "title": "Personen",  "version": "1.2.1",  "description": "Bekende Amsterdamse personen",  "schema": {    "$schema": "http://json-schema.org/draft-07/schema#",    "type": "object",    "required": [      "id",      "schema"    ],    "display": "naam",    "properties": {      "schema": {        "$ref": "https://schemas.data.amsterdam.nl/schema@v1.1.1#/definitions/schema"      },      "id": {        "type": "string",        "description": "Unieke aanduiding persoon"      },      "naam": {        "type": "string",        "description": "Volledige naam van de persoon"      },      "beroep": {        "title": "beroep",        "description": "Reden, dat de persoon bekend is.",        "type": "string",        "enum": [          "voetballer",          "filosoof"        ]      }    }  }}

personen/v1.3.0.json

{  "id": "personen",  "type": "table",  "title": "Personen",  "version": "1.3.0",  "description": "Bekende Amsterdamse personen",  "schema": {    "$schema": "http://json-schema.org/draft-07/schema#",    "type": "object",    "required": [      "id",      "schema"    ],    "display": "naam",    "properties": {      "schema": {        "$ref": "https://schemas.data.amsterdam.nl/schema@v1.1.1#/definitions/schema"      },      "id": {        "type": "string",        "description": "Unieke aanduiding persoon"      },      "naam": {        "type": "string",        "description": "Volledige naam van de persoon"      },      "beroep": {        "title": "Beroep",        "description": "Reden, dat de persoon bekend is.",        "type": "string",        "enum": [          "voetballer",          "filosoof",          "beide"        ]      },      "geassocieerdeLocaties": {        "shortname": "locaties",        "title": "Locaties geassocieerd met de Persoon",        "description": "Locaties geassocieerd met de persoon. \nBijvoorbeeld een voormalige woon of verblijfplaats.",        "type": "array",        "relation": "bekendeAmsterdammers:locaties",        "items": {          "type": "string"        }      }    }  }}

Nu wordt in de tabel uit het vorige voorbeeld een veld hernoemd, krijgt een string veld een maximale lengte, wordt uit een enum veld een optie verwijderd en wordt een optioneel veld verplicht gemaakt.

Deze veranderingen zijn niet backwards compatible dus het major versie nummer wordt opgehoogd en de nieuwe versie wordt "2.0.0".

De nieuwe tabel wordt in een nieuw bestand personen/v2.0.0.json geplaatst.

personen/v1.3.0.json

{  "id": "personen",  "type": "table",  "title": "Personen",  "version": "1.3.0",  "description": "Bekende Amsterdamse personen",  "schema": {    "$schema": "http://json-schema.org/draft-07/schema#",    "type": "object",    "required": [      "id",      "schema"    ],    "display": "naam",    "properties": {      "schema": {        "$ref": "https://schemas.data.amsterdam.nl/schema@v1.1.1#/definitions/schema"      },      "id": {        "type": "string",        "description": "Unieke aanduiding persoon"      },      "naam": {        "type": "string",        "description": "Volledige naam van de persoon"      },      "beroep": {        "title": "Beroep",        "description": "Reden, dat de persoon bekend is.",        "type": "string",        "enum": [          "voetballer",          "filosoof",          "beide"        ]      },      "geassocieerdeLocaties": {        "shortname": "locaties",        "title": "Locaties geassocieerd met de Persoon",        "description": "Locaties geassocieerd met de persoon. \nBijvoorbeeld een voormalige woon of verblijfplaats.",        "type": "array",        "relation": "bekendeAmsterdammers:locaties",        "items": {          "type": "string"        }      }    }  }}

personen/v2.0.0.json

{  "id": "personen",  "type": "table",  "title": "Personen",  "version": "2.0.0",  "description": "Bekende Amsterdamse personen",  "schema": {    "$schema": "http://json-schema.org/draft-07/schema#",    "type": "object",    "required": [      "id",      "schema",      "geassocieerdeLocaties"    ],    "display": "naam",    "properties": {      "schema": {        "$ref": "https://schemas.data.amsterdam.nl/schema@v1.1.1#/definitions/schema"      },      "id": {        "type": "string",        "description": "Unieke aanduiding persoon",        "maxLength": 25      },      "volledigeNaam": {        "type": "string",        "description": "Volledige naam van de persoon"      },      "beroep": {        "title": "Beroep",        "description": "Reden, dat de persoon bekend is.",        "type": "string",        "enum": [          "voetballer",          "filosoof",          "zanger",          "schilder",          "wiskundige",          "schrijver"        ]      },      "geassocieerdeLocaties": {        "shortname": "locaties",        "title": "Locaties geassocieerd met de Persoon",        "description": "Locaties geassocieerd met de persoon. \nBijvoorbeeld een voormalige woon of verblijfplaats.",        "type": "array",        "relation": "bekendeAmsterdammers:locaties",        "items": {          "type": "string"        }      }    }  }}

Voorbeeld in versie 2.0.0" wordt een aantal metadata velden aangepast.

Deze veranderingen passen de data structuur niet aan dus het patch nummer wordt opgehoogd en de nieuwe versie wordt "2.0.1".

De nieuwe tabel wordt in een nieuw bestand personen/v2.0.1.json geplaatst het oude bestand mag e.v.t. verwijderd worden.

personen/v2.0.0.json

{  "id": "personen",  "type": "table",  "title": "Personen",  "version": "2.0.0",  "description": "Bekende Amsterdamse personen",  "schema": {    "$schema": "http://json-schema.org/draft-07/schema#",    "type": "object",    "required": [      "id",      "schema",      "geassocieerdeLocaties"    ],    "display": "naam",    "properties": {      "schema": {        "$ref": "https://schemas.data.amsterdam.nl/schema@v1.1.1#/definitions/schema"      },      "id": {        "type": "string",        "description": "Unieke aanduiding persoon",        "maxLength": 25      },      "volledigeNaam": {        "type": "string",        "description": "Volledige naam van de persoon"      },      "beroep": {        "title": "Beroep",        "description": "Reden, dat de persoon bekend is.",        "type": "string",        "enum": [          "voetballer",          "filosoof",          "zanger",          "schilder",          "wiskundige",          "schrijver"        ]      },      "geassocieerdeLocaties": {        "shortname": "locaties",        "title": "Locaties geassocieerd met de Persoon",        "description": "Locaties geassocieerd met de persoon. \nBijvoorbeeld een voormalige woon of verblijfplaats.",        "type": "array",        "relation": "bekendeAmsterdammers:locaties",        "items": {          "type": "string"        }      }    }  }}

personen/v2.0.1.json

{  "id": "personen",  "type": "table",  "title": "Personen",  "version": "2.0.1",  "description": "Bekende historische Amsterdammers",  "schema": {    "$schema": "http://json-schema.org/draft-07/schema#",    "type": "object",    "required": [      "id",      "schema",      "geassocieerdeLocaties"    ],    "display": "volledigeNaam",    "properties": {      "schema": {        "$ref": "https://schemas.data.amsterdam.nl/schema@v1.1.1#/definitions/schema"      },      "id": {        "type": "string",        "description": "Unieke aanduiding persoon",        "maxLength": 25      },      "volledigeNaam": {        "type": "string",        "description": "Volledige naam van de persoon"      },      "beroep": {        "title": "Beroep",        "description": "Primaire reden, dat de persoon bekend is.",        "type": "string",        "enum": [          "voetballer",          "filosoof",          "zanger",          "schilder",          "wiskundige",          "schrijver"        ]      },      "geassocieerdeLocaties": {        "shortname": "locaties",        "title": "Geassocieerde locaties",        "description": "Locaties geassocieerd met de persoon. \nBijvoorbeeld een voormalige woon of verblijfplaats.",        "type": "array",        "relation": "bekendeAmsterdammers:locaties",        "items": {          "type": "string"        }      }    }  }}

Om de nieuwe versie van de tabel aan de dataset toe te voegen, moet de tabel referentie in de dataset ook aangepast worden. De default versie van de tabel is nu "2.0.1".

In dit geval staat de versie "1.3.0" ook in activeVersions zodat de oudere versie van de data ook beschikbaar blijft. Dit is optioneel.

personen/dataset.json

{  "id": "bekendeAmsterdammers",  "type": "dataset",  "title": "Bekende Amsterdammers",  "description": "Bekende historische personen die in Amsterdam hebben gewoond.\n (Een voorbeeld dataset)",  "status": "beschikbaar",  "owner": "Gemeente Amsterdam",  "publisher": "myDataTeam",  "creator": "myBronhouder",  "auth": "OPENBAAR",  "authorizationGrantor": "myDataTeam@amsterdam.nl",  "tables": [    {      "$ref": "personen/v2.0.1",      "id": "personen",      "activeVersions": {        "1.3.0": "personen/v1.3.0",        "2.0.1": "personen/v2.0.1"      }    },    {      "$ref": "locaties/v1.0.0",      "id": "locaties"    }  ]}

Note: Deze semantic versioning standaard is geinspireerd door SchemaVer wat weer is gebaseerd op SemVer.

4. Veld

Een veld beschrijft een eigenschap die een rij in de tabel mag of moet (zie required) bezitten. Een veld is een concrete JSON Schema-typedefinitie waaraan ook meta-informatie kan worden meegegeven.

Zie § 4.3 Data types voor een overzicht van modelleerbare typen en hoe deze binnen Amsterdam Schema uitgedrukt kunnen worden.

Note: veld gebruikt een subset van [json-schema-validation]. Een aantal JSON Schema features waaronder union types wordt niet ondersteund.

Let op: Zie § 5 Naamgeving voor de eisen waaraan de namen van velden moeten voldoen.

4.1. Verplichte attributen

Een veld is een JSON object met in ieder geval één en niet meer dan één van de volgende twee attributen.

`type`	string	Data type van het veld. Volgens JSON Schema § rfc.section.6.1.1. Zie § 4.3 Data types voor details. Toegestane waarden "integer" "number" "boolean" "string" "null" "object" "array"
`$ref`	enum(`uri`)	URI van een GeoJSON geometry schema definitie. zie § 4.3.6 geometrie Opties "https://geojson.org/schema/Geometry.json" "https://geojson.org/schema/MultiPolygon.json" "https://geojson.org/schema/Polygon.json" "https://geojson.org/schema/Point.json" "https://geojson.org/schema/MultiLineString.json" "https://geojson.org/schema/LineString.json" "https://geojson.org/schema/MultiPoint.json"

Note: Let op, een veld moet dus een type of een $ref attribuut hebben, beide is niet toegestaan.

4.2. Toegestane attributen

Een veld definitie mag naast het verplichte attribuut optioneel de volgende meta-data attributen bevatten:

`title`	string	zie § 7.1 Omschrijving Default: Gelijk aan de naam van het veld.
`description`	string	zie § 7.1 Omschrijving
`auth`	string \| array	geautoriseerde scope(s). Default: gelijk aan waarde in tabel/`auth`, zie § 7.2 Autorisatie. Niet toegestaan in velden waarnaar wordt verwezen in `identifier` of `display`.
`reasonsNonPublic`	array(`nonPubReason`)	een of meer gronden voor het niet openbaar maken van data obv uitzonderingen in Hoofdstuk 5 van de [Woo]. (Vanaf 1 mei 2022 verplicht wanneer de tabel openbaar is maar het `auth` atribuut van het veld niet gelijk is aan "OPENBAAR") zie § 7.2 Autorisatie
`provenance`	string	zie § 7.3 Provenance
`shortname`	string	zie § 5 Naamgeving
`unit`	string \| object	De eenheid van de waarden in dit veld. zie § 4.5 Eenheden
`relation`	string	Beschrijft relaties tussen velden. zie § 4.4 Relaties
`uri`	`uri-reference`	Een verwijzing de definitie van de waarden in dit veld.
`crs`	enum(string)	Coordinate reference System Opties "EPSG:28992" "EPSG:4326" "EPSG:7415" Dit veld is verplicht voor § 4.3.6 geometrie velden waarvoor niet op dataset-of tabelniveau al een crs gedefinieerd is. Zie SDOW best practices § CRS-background voor meer informatie.

Best Practice Voeg altijd op zijn minst een 'title' en 'description' toe.

Naast bovenstaande attributen mag een veld uitsluitend de volgende subset van attributen uit JSON Schema bevatten:

`$comment`	string	Developer commentaar bij het veld.
`items`	veld	JSON Schema van de elementen in de array. (verplicht voor array type) In tegenstelling tot JSON Schema wordt een `array` hier niet ondersteund. Zie [#data-types-array].
`maximum`	number	Inclusieve maximum waarde (voor integer en number type)
`minimum`	number	Inclusieve minimum waarde (voor integer en number type)
`exclusiveMaximum`	integer	Exclusieve maximum waarde (voor integer en number type)
`multipleOf`	number	Waarde moet meervoud zijn van (voor integer en number type)
`minLength`	integer	Mimimum lengte (voor string type)
`maxLength`	integer	Maximum lengte (voor string type)
`contentEncoding`	string	Encoding (voor string type)
`properties`	object	Attributen van objecten (voor object type)
`enum`	array	Lijst van maximaal 1024 toegestane waarden.
`format`	string/object	String formats (voor string type) Conform JSON Schema § rfc.section.7.3. Opties "date-time" "time" "date" "duration" "email" "idn-email" "hostname" "idn-hostname" "ipv4" "ipv6" "uri" "uri-reference" "iri" "iri-reference" Object format (voor object type): "json"

Voorbeeld van een veld.

        "type": "string",
        "description": "Volledige naam van de persoon"
      },
      "beroep": {
        "title": "beroep",
        "description": "Reden, dat de persoon bekend is.",

Voorbeeld van een geometrie veld.

"locatie": {
    "title": "Locatie",
    "description": "Coordinaten van het middelpunt van het plein",
    "$ref" : "https://geojson.org/schema/Point.json"
}

4.3. Data types

Velden worden allemaal gemodelleerd als concrete JSON Schema type definieringen, deze moeten in doel-systemen naar de juiste veld/kolom-types getransformeerd worden. (Zie ook Type-specific keywords in de JSON Schema specificatie).

Deze sectie bevat een overzicht van de door Amsterdam Schema ondersteunde JSON Schema typen, voorbeelden van gebruik en welke (SQL) data typen gebruikt zouden moeten worden om de JSON Schema typen te interpreteren.

§ 4.3.1 integer	§ 4.3.5 tijd
§ 4.3.2 number	§ 4.3.6 geometrie
§ 4.3.3 boolean	§ 4.3.7 object
§ 4.3.4 string	§ 4.3.8 array

Note: UNION types worden niet ondersteund: een kolom kan niet meerdere typen waardes bevatten, behalve null. De anyOf operater is dus niet toegestaan
~~{"anyOf": [{ "type": "integer" }, { "type": "string"}]}~~

Note: Elk veld is nullable tenzij het als required property is opgegeven, zie required.

4.3.1. integer

Een integer bevat de (decimale representatie van) een 64-bits signed integer. Een integer in Amsterdam Schema heeft dus een range van [-(2^63), (2^63)-1], maar gebruik van getallen buiten het bereik [-(2^53)+1, (2^53)-1] wordt in lijn met RFC7159 § section-6 afgeraden omdat dit door veelgebruikte doelsystemen ([IEEE754]) niet wordt ondersteund. Als een maximum en/of minimum buiten de laatst genoemde range is ingesteld wordt een waarschuwing gegeven.

Dit veld bevat een 64-bits signed integer, zoals een "BIGINT" in SQL.

"aantalDuivenOpDeDam": {
    "title": "aantal duiven op de Dam",
    "description": "Het gemeten aantal duiven op de de Dam",
    "type": "integer"
}

Dit veld resulteert in een waarschuwing.

"zandkorrelsOpBlijburg": {
    "title": "zandkorrels op Blijburg",
    "description": "Het aantal aantal zandkorrels op het strand van Blijburg.",
    "type": "integer",
    "maximum": 1E19
}

Daar waar een kleiner bereik is gegeven door middel van een of meer van de attributen maximum, minimum of exclusiveMaximum kan een native datatype met een geschikt bereik worden toegepast. Zo kan een integer met een exclusiveMaximum < 2^(N-1) en minimum >= 2^(N-1) altijd worden geinterpreteerd als een N-bits signed integer.

Dit veld kan veilig als 32 bit signed integer (zoals een SQL INTEGER) worden geinterpreteerd. (2147483648 = 2^(32-1))

"hoogteTenOpzichteVanNormaalAmsterdamsPijl": {
    "title": "Hoogte ten opzichte van NAP",
    "shortname": "hoogteNAP"
    "description": "Hoogte van de locatie ten opzichte van NAP in cm.",
    "type": "integer",
    "exclusiveMaximum": 2147483648,
    "minimum": -2147483648,
    "unit": "cm"
}

Een integer met een minimum >= 0 en een exclusiveMaximum < 2^N kan altijd worden geinterpreteerd als een N-bits unsigned integer.

Dit veld kan veilig als 8 bit unsigned integer zoals een SQL TINYINT worden geinterpreteerd.

"weeknummer": {
    "title": "weeknummer",
    "description": "weeknummer",
    "type": "integer",
    "exclusiveMaximum": 256,
    "minimum": 0,
}

Het wordt aangeraden om de toegestane waarden in een veld altijd te beperken tot realistische waarden om fouten te voorkomen.

"decennium": {
    "title": "decennium",
    "description": "Een decennium in het bestaan van de stad.",
    "type": "integer",
    "exclusiveMaximum": 2121,
    "minimum": 1300,
    "multipleOf": 10
}

4.3.2. number

Number wordt gebruikt voor velden met reële getallen. Als geen multipleOf attribuut is meegegeven moet een number veld worden geinterpreteerd als een 64bits floating-point getal (double) zoals een SQL DOUBLE. Dit veld moet worden geinterpreteerd als een Double zoals een SQL DOUBLE.

"gevelHoek": {
    "title": "gevel hoek",
    "description": "Hoek van de gevel met de verticaal in graden",
    "type": "number"
}

Wanneer aan een number veld een multipleOf attribuut is meegegeven moet dit veld worden geinterpreteerd als fixed-point type met schaal=log(multipleOf)/log(0.1) (zodat multipleOf=0.1^schaal).

Dit veld moet worden geinterpreteerd als een fixed-point type met schaal=2 zoals een SQL DECIMAL(10,2).

"gevelHoek": {
    "title": "gevel hoek",
    "description": "Hoek van de gevel met de verticaal in graden",
    "type": "number",
    "multipleOf": 0.01
}

Als een maximum attribuut is meegegeven kan een native type met een geschikte precisie worden gebruikt. precisie = log(maximum + 1)/log(10) + schaal (zodat maximum=10^(precisie-schaal) -1).

Dit veld moet worden geinterpreteerd als een fixed-point type met schaal=2 en precisie>=4 zoals een SQL DECIMAL(4,2).

"gevelHoek": {
    "title": "gevel hoek",
    "description": "Hoek van de gevel met de verticaal in graden",
    "type": "number",
    "multipleOf": 0.01
    "maximum": 90
    "minimum": -90
}

Best Practice Beperk numerieke velden altijd tot realistische waarden met maximum, minimum of exclusiveMaximum om fouten te voorkomen, en doelsystemen de juiste datatypen te laten gebruiken.

4.3.3. boolean

Een veld van het type "boolean" wordt gebruikt voor boolean, (true, false) waarden.

"isGepubliceerd": {
    "title": "Is gepubliceerd",
    "description": "Dit artikel is gepubliceerd.",
    "type": "boolean",
}

4.3.4. string

String velden worden gebruikt voor tekst, enums, tijd, datum en binary data. Waarden in een string veld moeten standaard worden geinterpreteerd als van een string type zoals een SQL TEXT.

"beschrijving": {
    "title": "Beschrijving",
    "description": "Beschrijving van het pand.",
    "type": "string",
}

Waar een maxLength attribuut is meegegeven aan een string veld kan een geschikt limited width string type zoals een SQL VARCHAR worden gebruikt.

"bekendeUitspraak": {
    "title": "Bekende uitspraak",
    "description": "Bekende uitspraak van de persoon.",
    "type": "string",
    "maxLength": 50
}

Als een string veld een minLength en een maxLength attribuut van gelijke waarde heeft kan het veld worden geinterpreteerd als een fixed width string zoals een SQL CHAR.

"taalcode": {
    "title": "taalcode",
    "description": "Taalcode volgens de ISO639-2 standaard.",
    "type": "string",
    "maxLength": 3
    "minLength": 3
}

Wanneer in een text veld een beperkte set waarden is toegestaan door middel van het enum attribuut, zou het veld moeten worden geinterpreteerd als een enumerator type zoals een SQL ENUM.

Dit veld zou moeten worden geinterpreteerd als een enumerator zoals een SQL ENUM.

"beroep": {
    "title": "beroep",
    "description": "Beroep van de persoon.",
    "type": "string",
    "enum": ["voetballer", "filosoof", "beide"]
}

Een text veld met contentEncoding gelijk aan "base64" zou moeten worden geinterpreteerd als binary data.

Dit veld zou moeten worden geinterpreteerd als binary data, zoals een SQL VARBINARY.

"hash": {
    "title": "hash",
    "description": "SHA512 hash",
    "type": "string",
    "contentEncoding": "base64"
}

Wanneer een maxLength attribuut is meegegeven aan een string veld zou het veld moeten worden geinterpreteerd als een fixed width binary type zoals een SQL BINARY, met maxLength=4*ceil(bytes/3).

Dit veld zou moeten worden geinterpreteerd als fixed length binary data, zoals een SQL BINARY.

"hash": {
    "title": "hash",
    "description": "SHA512 hash",
    "type": "string",
    "contentEncoding": "base64",
    "maxLength": 88
}

4.3.5. tijd

Met het format attribuut kan een string veld worden geformatteerd als tijds of datum eenheid. Een string veld met een format gelijk aan "time", "date", "date-time" of "duration" zou moeten worden geinterpreteerd als een [ISO8601] conform Datum of tijd type zoals een SQL DATE, TIME of DATETIME.

Note: De maximale precisie van de tijdseenheden is microseconde.

Note: Bij een "date-time" wordt aangeraden om een tijdszone op te geven. Wanneer de tijdszone ontbreekt wordt een data-kwaliteit waarschuwing gegeven.

Dit veld zou moeten worden geinterpreteerd als een [ISO8601] Datum type in het format YYYY-MM-DD, zoals een SQL DATE.

"publicatieDatum": {
    "title": "publicatie datum",
    "description": "Datum van publicatie",
    "type": "string",
    "format": "date"
}

Dit veld zou moeten worden geinterpreteerd als een [ISO8601] conform tijd type, zoals een SQL TIME.

"publicatieTijd": {
    "title": "publicatie tijd",
    "description": "Tijd van publicatie",
    "type": "string",
    "format": "time"
}

Dit veld zou moeten worden geinterpreteerd als een [ISO8601] conform datum-tijd type, zoals een SQL DATETIME.

"tijdEnDatumVanPublicatie": {
    "title": "Tijd en datum van publicatie",
    "description": "Tijd en datum van publicatie",
    "type": "string",
    "format": "date-time"
}

Dit veld zou moeten worden geinterpreteerd als een [ISO8601] conform tijdsduur type, zoals een postgreSQL INTERVAL.

"duur": {
    "title": "Evenements duur",
    "description": "Tijdsduur dat het evenement open is voor publiek.",
    "type": "string",
    "format": "duration"
}

4.3.6. geometrie

Een geometrie veld wordt gedefinieerd als een verwijzing naar de relevante GeoJSON Schema definitie. Alle GeoJSON geometrie typen (Point, Polygon, Line String, Multi Point, Multi LineString, en Multi Polygon) worden ondersteund.

Voorbeeld van een geometrie veld.

      "lokatie": {
        "title": "Lokatie",
        "description": "Coordinaten van het middelpunt van het plein",
        "$ref": "https://geojson.org/schema/Point.json"
      },

Een tabel schema mag meerdere geometrie velden bezitten. Bijvoorbeeld de contour van een object in een Polygon en de centrale coordinaten van het object in een Point.

Doelsystemen die slechts één geometrie veld per object ondersteunen moeten gebruik maken van het veld waarnaar wordt verwezen in het mainGeometry attribuut van de tabel. Als de tabel geen expliciet mainGeometry attribuut heeft is dit de default waarde: "Geometry".

Note: Als een tabel één of meerdere geometrie velden heeft, maar geen van deze velden "Geometry" heet, moet één van de velden als primaire geometrie worden aangegeven in mainGeometry.

Note: Als een tabel een geometrie veld bevat, moet op dataset niveau het coordinaat referentie systeem worden aangegeven in het crs attribuut.

Voorbeeld van een tabel met meerdere geometrie velden. Het veld "locatie" is hier als primaire geometrie aangegeven in "mainGeometry".

{  "id": "pleinen",  "type": "table",  "title": "Pleinen",  "version": "1.0.0",  "description": "Pleinen van amsterdam. (Een voorbeeld tabel met geometrie velden)",  "mainGeometry": "lokatie",  "schema": {    "$schema": "http://json-schema.org/draft-07/schema#",    "type": "object",    "required": [      "id",      "schema"    ],    "display": "id",    "properties": {      "schema": {        "$ref": "https://schemas.data.amsterdam.nl/schema@v1.1.1#/definitions/schema"      },      "id": {        "type": "string",        "description": "Unieke aanduiding van het plein"      },      "naam": {        "type": "string",        "description": "Naam van het plein"      },      "lokatie": {        "title": "Lokatie",        "description": "Coordinaten van het middelpunt van het plein",        "$ref": "https://geojson.org/schema/Point.json"      },      "contour": {        "title": "Contour",        "description": "Polygoon van de contour van het plein.",        "$ref": "https://geojson.org/schema/Polygon.json"      }    }  }}

4.3.7. object

Een veld van type object kan gestructureerde data (objecten of structs) bevatten. Een objectveld met het format json mag willekeurige JSON-data bevatten. Alle overige objectenvelden moeten een attribuut properties bezitten waarin de structuur van de waarden in het veld wordt vastgelegd. Het properties attribuut is een object met daarin de veld definities van de eigenschappen van de datawaarden.

Note: Het properties attribuut moet geen object of array velden bevatten. Geneste data is in een gestructureerd object veld niet toegestaan.

Een voorbeeld van een object veld.

"adres": {
    "title": "Adres",
    "description": "Het adres.",
    "type": "object",
    "properties": {
        "functieAdres": {
            "type": "string",
            "title": "Functie adres",
            "description": "Aanduiding van het soort adres. Mogelijke waarden: W (woonadres), B (briefadres).",
            "enum": ["W", "B"]
        },
        "huisnummer": {
            "type": "integer",
            "exclusiveMaximum": 2147483648,
            "minimum": 0

        },
        "toevoeging": {
            "type": "string"
        },
        "postcode": {
            "description": "Volledige postcode zonder spaties.",
            "type": "string"
            "minLength": 6,
            "maxLength": 6
        },
        "straatnaam": {
            "type": "string"
        }
    }
}

Note: De velden in properties zijn altijd nullable.

Als een object veld een properties attribuut bevat (gestructureerd is), moet het in doelsystemen geinterpreteerd worden als een SQL STRUCT type. Als een object veld geen properties attribuut heeft (ongestructureerd is) kan het in doelsystemen slechts ongeindexeerd worden opgeslagen in bijvoorbeeld een JSON string.

Daarom moet het gebruik van object velden zonder properties attribuut waar mogelijk worden vermeden. Een config/properties veld van string keys naar string waarden is een voorbeeld van acceptabel gebruik van een ongestructureerd object veld.

4.3.8. array

Een veld van type array kan meerdere elementen van hetzelfde type bevatten, met mogelijke duplicatie. Een array veld moet een items attribuut hebben, dit moet een veld object zijn.

Note: De optie van een items array uit de JSON Schema specificatie wordt niet ondersteund. Een array kan dus slechts één type waarde bevatten (geen UNION types).

Het items attribuut is een veld object, maar de meta-data attributen title, description, auth, provenance, shortname en relation hebben in items geen effect en zouden moeten worden weggelaten.

Note: Een array van arrays is niet toegestaan. Dus items mag zelf niet het type array hebben.

Een array van integers.

"weeknummers": {
    "title": "weeknummers",
    "description": "Weeknummers.",
    "type": "array",
    "items": {
        "type": "integer",
        "exclusiveMaximum": 256,
        "minimum": 0,
    }
}

Een array van objecten.

"metingen": {
    "title": "metingen",
    "description": "Uitgevoerde metingen.",
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "meetonzekerheid": {
                "title": "Meetonzekerheid",
                "description": "Onzekerheid van de meting.",
                "type": "number",
                "minimum": 0
            },
            "waarde": {
                "title": "Waarde",
                "description": "De gemeten waarde.",
                "type": "number"
            }
        }
    }
}

Het is onduidelijk of unit in een array moet worden meegegeven in het items attribuut als veld.items.unit of in het hoofd object als veld.unit.

4.4. Relaties

Met het relation attribuut van een veld kunnen relaties tussen tabellen worden gedefinieerd. Dit kan zowel een relatie tussen tabellen in één dataset als tussen tabellen in verschillende datasets zijn. Met het relation-attribuut wordt verwezen naar het identifierveld van de andere tabel. Dit is vergelijkbaar met een foreign key relatie in SQL.

Het attribuut relation moet altijd een string bevatten van de vorm "<dataset-id>:<tabel-id>". Van de waarden in een relation veld wordt verwacht dat ze gelijk zijn aan de unieke identifier van een rij in de tabel waaraan gerefereerd wordt.

Note: Dit is niet verplicht, referentiële integriteit wordt niet afgedwongen. Het kan dus voorkomen dat relaties naar niet (meer) bestaande entiteiten verwijzen.

In het geval dat gerefereerd wordt aan een tabel zonder temporaliteit, moet het type van het verwijzende veld overeenkomen met het type van de identifier van de andere tabel.

Voorbeeld van een relatie veld voor een enkelvoudige relatie met de tabel "meetbouten" in de dataset "meetbouten".

"hoortBijMeetbout": {
    "title": "hoort bij meetbout",
    "description": "De meetbout waarop de meting is gedaan."
    "type": "string",
    "relation": "meetbouten:meetbouten"
}

Als gerefereerd wordt aan een tabel met temporaliteit, bestaat de unieke identifier van een object in die tabel uit twee velden; de tabel identifier en de temporele identifier (zie § 3.4 Temporaliteit). In dit geval moet het verwijzende veld van het type object zijn en twee properties bevatten, met namen en types die overeenkomen met de identifier en de temporal van het object waarnaar verwezen wordt.

Voorbeeld van een relatie veld voor een enkelvoudige relatie met de temporele tabel "wijken" in de dataset "gebieden".

"ligtInWijk": {
    "title": "ligt in wijk",
    "description": "De wijk waar de buurt in ligt.",
    "type": "object",
    "relation": "gebieden:wijken",
    "properties": {
        "identifier": {
            "type": "string"
        },
        "volgnummer": {
            "type": "string"
        }
    }
}

Voor meervoudige (Many-To-Many) relaties wordt een array veld gebruikt met een relation attibuut.

Voorbeeld van een relatieveld voor een meervoudige relatie met de tabel "referentiepunten" in de dataset "meetbouten".

"refereertAanReferentiepunten": {
    "shortname": "referentiepunten",
    "title": "refereert aan referentiepunten",
    "description": "De referentiepunten waar aan de meetbout refereert.",
    "type": "array",
    "relation": "meetbouten:referentiepunten",
    "items": {
        "type": "string"
    }
}

Voorbeeld van een relatieveld voor een meervoudige relatie met een temporele tabel "panden" in de dataset "bag".

"ligtInPanden": {
    "title": "ligt in panden",
    "relation": "bag:panden",
    "description": "De unieke landelijke aanduidingen van de panden waarvan het verblijfsobject onderdeel uitmaakt.",
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "identificatie": {
                "type": "string"
            },
            "volgnummer": {
                "type": "integer"
            }
        }
    }
}

4.5. Eenheden

Het is mogelijk om bij een veld de eenheid mee te geven in het unit attribuut als meta-informatie voor user interfaces. Dit is slechts bedoeld ter informatie van de eindgebruiker, er worden dus geen automatische bewerkingen (zoals bijvoorbeeld eenheid conversies) uitgevoerd op basis van dit veld.

Voor het definieren van een eenheid wordt standaard een string met de eenheid volgens de The Unified Code for Units of Measure codering gebruikt.

"unit": "mm/h"

Note: Zie deze link voor een overzicht van veelgebruikte eenheden in UCUM-format.

Voor valuta’s wordt de drieletterige codering ISO 4217 gebruikt binnen een UCUM 2.1§6 unitannotatie.

"unit": "{EUR}/h"

De eenheidscodering kan ook expliciet meegegeven worden door unit een object mee te geven. Een unit object moet de volgende attributen bevatten.

`type`	string	de eenheidscodering
`value`	string	de eenheid

"unit": {"type": "ucum", "value": "{EUR}/h"}

Zo kunnen ook andere eenheidscoderingen gebruikt worden.

"unit": {"type": "pint", "value": "meter"}

Best Practice Gebruik de UCUM-standaard om eenheden te coderen. Niet-standaard-coderingssystemen worden afgeraden.

5. Naamgeving

De data die in Amsterdam Schema wordt beschreven wordt publiek ontsloten en heeft veel externe afnemers. Het is dus heel belangrijk dat naamgeving correct, helder en eenduidig is, ook voor mensen die niet dagelijks met deze gegevens werken. Amsterdam Schema is ontworpen om door automatische systemen verwerkt te kunnen worden, ook daarom is het belangrijk dat de naamgeving aan een strak stramien voldoet.

Namen van datasets, tabellen en velden moeten:

1. gebruik maken van camelCase.
2. geen afkortingen of afbrekingen bevatten.
3. bestaan uit zelfstandige naamwoorden (met uitzondering van de namen van relatievelden).
4. uniek zijn binnen hun scope. (respectievelijk: De hele catalogus, de dataset of de tabel)

De namen van tabellen (zoals gegeven in id) en velden worden onderdeel van de URI waarop deze entiteiten ontsloten worden, en moeten daarom aan extra eisen voldoen.

5. Namen van tabellen moeten in meervoudsvorm zijn, behalve als sprake is van een enkelvoudige entiteit. Conform REST-API Design Rules § api-54.

6. Namen van velden moeten geen herhaling van de tabel naam bevatten. (Dus niet container.containerNummmer, maar container.nummer.)

Note: Gebruik duidelijke en begrijpelijke namen voor zowel datasets, tabellen als velden. De data wordt onsloten op een publieke API, dus de naamgeving moet zonder veel uitleg duidelijk zijn voor externe afnemers.

5.1. Shortname

Te lange namen in het schema kunnen problemen geven bij het aanmaken van tabellen en kolommen op basis van het schema. PostgreSQL staat bijvoorbeeld niet meer dan 63 tekens toe voor tabelnamen.

Op zowel tabel als veld niveau is het mogelijk om een alternatieve verkorte naam op te geven met het attribuut shortname. Het shortname attribuut mag wel afkortingen bevatten (regel 2 geldt niet) maar moet verder aan dezelfde eisen voldoen als de naam die erdoor wordt afgekort.

Gebruik van shortname in een tabel.

{
    "id": "maatschappelijkeActiviteiten",
    "shortname": "activiteiten",
    "type": "table"
    ...
}

Gebruik van shortname in een veld.

"registratieTijdstipMaatschappelijkeActiviteit": {
    "shortname": "registratieTijdstip",
    "type": "string",
    "format": "date-time"
}

6. Publisher

Een publisher definitie bevat een publisher object. Deze word onder andere gebruikt voor billing en tagging van resources die via het amsterdam schema worden aangevraagd.

6.1. Verplichte attributen

Een publisher binnen Amsterdam Schema is een JSON object met in ieder geval de volgende attributen.

id identifier Identifier van de publisher. Moet globaal uniek zijn en gelijk aan de file waarin het publisher object is opgeslagen.

type constante Type van dit bestand, in dit geval "publisher".

name string Naam van de publisher.

shortname resource-identifier Verkorte naam van de publisher (voor resources).

tags

object

Labels met metagegevens die aan resources van deze publisher moeten worden gehangen.

Valide elementen

`costcenter`	REQUIRED	string	Costcenter tag van de publisher
`team`		string	Team tag van de publisher

7. Generieke attributen

Deze attributen kunnen op elk niveau bestaan.

7.1. Omschrijving

Op elk niveau kan een semantische omschrijving toegevoegd worden d.m.v. de attributen title en description.

title	(string)	Naam van dit item.
description	(string)	Beschrijving van dit item, vrije tekst. Mag escape characters zoals newlines bevaten.

De title kan bijvoorbeeld in frontendapplicaties worden gebruikt als label voor een invoerveld. Het description veld is bedoeld voor bijvoorbeeld contextmenu’s (mouseover) bij een invoerveld of voor informatievelden.

title en description van een Dataset.

  "title": "Bekende Amsterdammers",
  "description": "Bekende historische personen die in Amsterdam hebben gewoond.\n (Een voorbeeld dataset)",

title en description van een Tabel.

  "title": "Locaties",
  "description": "Adressen in Amsterdam geassocieerd met een bekende Amsterdammer. \nBijvoorbeeld een voormalige woon of verblijfplaats",

title en description in een Veld.

          "Geboorteadres",
          "Werkplaats",

Note: Als een veld geen title-attibuut heeft, wordt de naam van het veld gebruikt.

7.2. Autorisatie

Op zowel dataset, tabel als veld niveau kan een "auth"-attribuut worden meegegeven om toegang tot een entitieit te beperken.

auth

string | array

geautoriseerde scope(s).

Het "auth"-attribuut bevat één of meer scopes, die leesrechten hebben op de entiteit waarop "auth" is gedefinieerd. Een scope is een groep gebruikers (medewerkers) met gedeelde rechten. Een gebruiker kan meerdere scopes hebben.

Een scope is een string bestaande uit een reeks lower of uppercase letters eventueel gescheiden door een forward slash (/).

Als het "auth"-attribuut een array bevat is elke scope in de array afzonderlijk geautoriseerd. Dus een gebruiker heeft slechts één van de scopes in een array nodig voor toegang.

Voorbeeld van een "auth" array op een veld. Zowel scope "LEVEL/X" als scope "LEVEL/Y" toegang tot het veld. Een gebruiker hoeft niet beide scopes te bezitten.

"aantalDuivenOpDeDam": {
    "title": "aantal duiven op de Dam",
    "description": "Het gemeten aantal duiven op de de Dam",
    "auth": ["LEVEL/X", "LEVEL/Y"]
    "type": "integer"
}

Op dataset niveau is het auth attribuut verplicht. Bij een openbare dataset krijgt het auth attribuut de waarde "OPENBAAR".

Als een tabel geen "auth" attribuut heeft is de scope van de tabel gelijk aan die van de dataset.

Als een veld geen "auth" attribuut heeft is de scope van het veld gelijk aan die van de tabel.

Op het eerste niveau waarop data niet openbaar wordt gemaakt moet met ingang van 1 mei 2022 een '"reasonsNonPublic"' attribuut bestaan. Dus als een dataset openbaar is, maar deze een tabel bevat waarop een auth attribuut met een andere waarde dan "OPENBAAR" bestaat. Moet in de betreffende tabel of tabellen een reasonsNonPublic attribuut bestaan.

In dit voorbeeld vindt autorisatie plaats op 3 niveaus. Scope "LEVEL/A" heeft dataset level autorisatie op gebieden, scope "LEVEL/B" heeft tabel level autorisatie op bouwblokken en scope "LEVEL/C" heeft autorisatie op veld beginGeldigheid.

Een user met scope "LEVEL/A" mag alles uit de dataset gebieden zien, behalve tabel bouwblokken.
Een user met scope "LEVEL/B" mag alle velden van tabel bouwblokken zien, behalve beginGeldigheid.
Een user met scope "LEVEL/C" mag veld beginGeldigheid zien.

{    "type": "dataset",    "id": "gebieden",    "title": "gebieden",    "auth": "LEVEL/A",    "status": "beschikbaar",    "crs": "EPSG:28992",    "tables": [        {        "id": "bouwblokken",        "mainGeometry": "geometrie",        "type": "table",        "version": "1.0.0",        "auth": "LEVEL/B",        "schema": {            "$id": "https://github.com/Amsterdam/schemas/gebieden/bouwblokken.json",            "$schema": "http://json-schema.org/draft-07/schema#",            "type": "object",            "additionalProperties": false,            "identifier": ["id"],            "required": ["schema", "id"],            "display": "id",            "properties": {            "schema": {                "$ref": "https://schemas.data.amsterdam.nl/schema@v1.1.1#/definitions/schema"            },            "id": {                "type": "string",                "description": "Unieke identificatie voor dit object, inclusief volgnummer"            },            "beginGeldigheid": {                "type": "string",                "format": "date",                "title": "Begin geldigheid",                "description": "De datum waarop het object is gecreëerd.",                "auth": "LEVEL/C"            },            "eindGeldigheid": {                "type": "string",                "format": "date",                "title": "Eind geldigheid",                "description": "De datum waarop het object is komen te vervallen.",                "provenance": "eindgeldigheid"            },            "ligtInBuurt": {                "type": "string",                "relation": "gebieden:buurten",                "provenance": "ligtinbuurt",                "title": "Ligt in buurt",                "description": "De buurt waar het bouwblok in ligt."            }            }        }        }    ]}

7.3. Provenance

Provenance als veld wordt gebruikt om programmatisch informatie op te slaan over de oorsprong van bepaalde data.

In beperkte vorm kan provenance ook gebruikt worden om automatisch verwerking van brongegevens in andere formaten te bewerkstelligen.

Provenance is beschikbaar op zowel dataset-, tabel- als veld-niveau. Het is een vrij veld maar door een object met 'type' te specificeren kunnen specifieke machine readable profielen geactiveerd worden t.b.v. automatische bronverwerking

7.3.1. Vrije invoer

Dataset: "provenance": "Deze dataset wordt handmatig verwerkt door ..."

Tabel: "provenance": "Deze tabel is gebaseerd op een CSV bestand aangeleverd door ..."

Veld: "provenance": "Ontbrekende IDs zijn m.b.v TextEdit vervangen door UUID hashes van de naam in UTF-8."

7.3.2. Postgres

Dataset: "provenance": { "type": "postgres", "schema": "ruimte" }

Tabel: "provenance": { "table": "verhardingen" }

Veld: "provenance": { "field": "lengte_m", "type": "NUMERIC(10,2)"}

7.3.3. Shapefile

Dataset: "provenance": { "type": "shapefile"}

Tabel: "provenance": { "file": "asbestdaken_daken.zip" }

Veld: "provenance": { "field": "perceel_id"}

8. Attribuuttypen

`identifier`	string	Een unieke identifier in de vorm van één of meer letters, startend met een kleine letter en eventueel gevolgd door een cijferreeks.
`resource-identifier`	string	Een unieke identifier in de vorm van één tot en met twaalf kleine letters.
`date-time`	(string)	Een als datetime geformatteerde string. Conform JSON Schema § rfc.section.7.3.1.
`uri`	(string)	Een als URI geformatteerde string. Conform JSON Schema § rfc.section.7.3.5.
`uri-reference`	(string)	Een als URI Reference geformatteerde string. Conform JSON Schema § rfc.section.7.3.5.
`schema-type`	(enum-string)	Het binnen Amsterdam Schema bekende JSON Schema type waaraan het object voldoet. Opties "dataset" "table" "publisher"
`reden-niet-publiek`	(enum-string)	Grond voor het niet openbaar maken van data op basis van de uitzonderingen in Hoofdstuk 5 van de Wet Open Overheid (Woo). Met `"5.1 1a"`, wordt bedoeld Wet Open Overheid Artikel 5.1, eerste lid, onderdeel a. De beschrijvingen volgend op de wetsverwijzing zijn niet volledig en dienen slechts ter illustratie. Kijk voor de exacte definitie van een uitzondering in hoofdstuk 5 van de Woo. Opties "5.1 1a: Gevaar voor eenheid van de Kroon", "5.1 1b: Gevaar voor staatsveiligheid", "5.1 1c: Vertrouwelijke of concurrentiegevoelige bedrijfs- en fabricagegegevens", "5.1 1d: Bevat persoonsgegevens", "5.1 1e: Bevat nationaal identificatienummer", "5.1 2a: Zwaarwegend belang: internationale betrekkingen", "5.1 2b: Zwaarwegende economische of financiële belangen van publiekrechtelijke lichamen (bevat geen mileu-informatie)", "5.1 2b: Zwaarwegende economische of financiële belangen van publiekrechtelijke lichamen (bevat mileu-informatie met betrekking op handelingen met een vertrouwelijk karakter)", "5.1 2c: Zwaarwegend belang: opsporing en vervolging van strafbare feiten", "5.1 2d: Zwaarwegend belang: inspectie, controle en toezicht door bestuursorganen", "5.1 2e: Zwaarwegend belang: eerbiediging van de persoonlijke levenssfeer", "5.1 2f: Zwaarwegend belang: vertrouwelijke of concurrentiegevoelige bedrijfs- en fabricagegegevens", "5.1 2g: Zwaarwegend belang: bescherming van het milieu waarop deze informatie betrekking heeft", "5.1 2h: Zwaarwegend belang: beveiliging van personen en bedrijven en het voorkomen van sabotage", "5.1 2i: Zwaarwegend belang: het goed functioneren van de Staat, andere publiekrechtelijke lichamen of bestuursorganen", "5.2 1: Bevat persoonlijke beleidsopvattingen (bevat geen milieu-informatie)", "5.2 4: Zwaarwegend belang: persoonlijke beleidsopvattingen (bevat milieu-informatie)", "nader te bepalen" De laatste optie ("nader te bepalen") is niet toegestaan wanneer `status`=`"beschikbaar"`.
`version`	(string)	Version string van de vorm " . . " of " . " (patch nummer is optioneel)
`contact`	(object)	Contactgegevens. Een object met de volgende optionele velden: `name` (string) Naam van het contact `email` (string) Email adres van het contact

9. Changelog

Dit is een chronologisch overzicht van aanpassingen aan de amsterdam-schema specificatie. Uitsluitend normatieve aanpassingen aan de specificatie worden vermeld. Aanpassingen aan voorbeelden, waarschuwingen of uitleg verschijnen dus niet in dit overzicht.

9.1. [2.2.0] dataclass atribuut toegevoegd (2023-01-12)

Doelstelling
UItzonderingsgronden WOO in lijn gebracht met versie van WOO die nu van kracht is.

Het dataclass attribuut is toegevoegd.

9.2. [2.1.5] dataclass atribuut toegevoegd (2023-01-10)

Doelstelling
Beschrijving en relatering van ongestructureerde data mogelijk maken.

De opties in attribuut reasonsNonPublic aangepast.
Verwijzing Wet Open Overheid geupdate.

9.3. [2.1.4] Publishers zijn zelfstandige objecten geworden (2022-12-21)

Doelstelling
Publishers zijn zelfstandige objecten geworden.

Het publisher attribuut is een ref geworden.
Het publisher object is toegevoegd.

9.4. [2.1.3] Auth attribuut verplicht op dataset niveau (2022-04-13)

Doelstelling
Alle datasets zijn openbaar tenzij obv de Wet Open Overheid. Maar om onbedoelde openbaarmaking te voorkomen, moet dit altijd expliciet ingevuld worden. Voor data die niet publiek is moet de uitzonderingsgrond worden vermeld.

Het auth attribuut is verplicht gemaakt.
Het dataset attribuut reasonsNonPublic is toegevoegd.
Het tabel attribuut reasonsNonPublic is toegevoegd.
Het veld attribuut reasonsNonPublic is toegevoegd.

9.5. [2.1.2] Auth attribuut niet toegestaan bij identifier en display velden (2022-04-13)

Doelstelling
De velden waar naar verwezen wordt in identifier en display moeten zichtbaar zijn voor iedereen die toegang heeft tot de tabel. Deze velden mogen dus geen auth bevatten.

De velden waar naar verwezen wordt in de identifier en display attributen mogen geen auth attribuut bevatten.

9.6. [2.1.1] Crs attribuut verplicht bij geometrie velden (2022-03-23)

Doelstelling
Het coordinaat referentie systeem van een dataset met geo data moet bekend zijn voor correct functioneren van doelsystemen.

Het crs veld is verplicht geworden wanneer één of meerdere tabellen een § 4.3.6 geometrie veld bevatten.

9.7. [2.1.0] Dataset contact gegevens (2022-03-17)

Doelstelling
Meerdere aanpassingen aan dataset velden voor contactgegevens. Met als doel om alle teams en organisaties die een rol hebben bij het ontsluiten van een dataset te vermelden. Zodat vragen over de dataset aan de juiste personen gericht kunnen worden.

Nieuw optioneel veld creator toegevoegd.
Het veld publisher heeft geen constant waarde meer. En bevat nu de naam van het datateam dat de dataset ontsluit.
Het veld contactPoint is nu optioneel en bevat een standaard waarde.