31:T425,md`Dit document beschrijft hoe OIS/Datapunt in de toekomst data verwerkt, opslaat en publiceert, en het beschrijft de rol van het nieuwe Team Dataservices in dit proces. __Dit is een werkbestand: een hoop ideeën, maar niets is nog af!__ We willen deze plannen graag uitwerken in nauwe samenwerking met de Datasquads, softwarearchitecten en andere teams binnen OIS. Dit document is een interactief [Observable-notebook](https://observablehq.com/@observablehq/five-minute-introduction?collection=@observablehq/introduction). Commentaar en suggesties kunnen worden toegevoegd door op het menu ${icons.vdots} in de linkermarge van een _cell_ te klikken en voor de optie ${icons.comment} Comment te kiezen. Voor meer informatie over het toevoegen van suggesties aan een Observable-notebook, zie [_Suggestions and Comments_](https://observablehq.com/@observablehq/suggestions-and-comments?collection=@observablehq/introduction). In dit document onderscheiden we 4 stappen tussen brondata en afnemer, __Verzamelen__, __Verwerken__, __Opslaan__ en __Publiceren__: `32:T682,viewof diagram = dot` digraph G { ${dotHead} source[shape=none, width=0, height=0, label=""]; subgraph cluster_0 { ${subgraphHead} label="Verzamelen"; href="#sectionCollect"; data[label="Data", href="#sectionCollectData"]; model[label="Modelleren", href="#sectionCollectModel"]; {rank=same; data; model; } } subgraph cluster_1 { label="Verwerken"; href="#sectionProcess"; ${subgraphHead} import[label="Importeren", href="#sectionProcessImport"]; enrich[label="Verrijken & \\nAggregeren", href="#sectionProcessEnrich"]; schema[label="Amsterdam Schema", href="#sectionProcessSchema"]; {rank=same; import; schema; } } subgraph cluster_2 { label="Opslaan"; href="#sectionStorage"; ${subgraphHead} database[label="Database", href="#sectionStorageDatabase"]; logging[label="Logging", href="#sectionStorageLogging"]; {rank=same; database; logging; } } subgraph cluster_3 { label="Publiceren"; href="#sectionPublish"; ${subgraphHead} apis[label="API's & Search", href="#sectionPublishApis"]; authorization[label="Autorisatie", href="#sectionPublishAuthorization"]; {rank=same; apis; authorization;} } user[shape=none, width=0, height=0, label=""]; source -> data; data -> import; model -> data; import -> enrich; enrich -> database; database -> enrich; import -> schema; schema -> import; schema -> model; schema -> enrich[constraint=false]; database -> apis; apis -> logging[constraint=false]; authorization -> logging[constraint=false]; authorization -> apis; apis -> authorization; apis -> user; }`33:T42b,md` | Dataset | Bijzonderheden | | ---------------------------- |:--------------------------------------------------------- | | Gebieden (buurten, wijken | Hiëriarchisch & geografisch | | Raadsbesluiten | Niet geografisch! Moeten ze ook doorzoekbaar zijn? | | Tellusdata | Heel veel data, veel updates! Eerst aggregeren? | | Onderzoeken OIS | Documenten, grafieken. Per onderwerp, vaak per jaar. | | Drukteradar | Verschillende bronnen. Veel data, veel updates | | Data over processen en financiën | Veel data. Niet geografisch. | | Panoramafoto's | Momenteel ingewikkelde API die zorgt voor ordelijk kaartbeeld (niet teveel foto's naast elkaar | | BAG | Complex datamodel. Ontsloten via GOB. | | BRP | Persoonsgegevens. Autorisatie! | `34:T45e,md` Verder moet de manier van beschrijven voldoen aan de volgende eisen: - Aansluiten bij GOB-model; - Aansluiten bij en uitbreiden van [Stelselpedia](https://www.amsterdam.nl/stelselpedia/); - Gebruikmaken van URI's; - Vastleggen en afdwingen van relaties tussen objecten; - Het moet mogelijk zijn om de data en de omschrijving te converteren naar RDF/Linked Data; - We moeten aansluiten bij andere standaarden (bv. VNG, Rijksoverheid); - Het moet mogelijk zijn om nieuwe datasets te modelleren door het samenstellen van componenten uit een bibliotheek met standaardtypes (geometrie, adressen, relaties, evt. grootheden als meter, temperatuur, etc.). Voor het ontwikkelen van het Amsterdam Schema kunnen we kiezen uit een aantal bestaande technologiën: - [RDF/OWL](https://en.wikipedia.org/wiki/Web_Ontology_Language) - [XSD (XML Schema Definition)](https://en.wikipedia.org/wiki/XML_Schema_(W3C)) - [SHACL](https://www.w3.org/TR/shacl/) - GOB heeft z'n eigen JSON-taal: [\`gobmodel.json\`](https://github.com/Amsterdam/GOB-Core/blob/master/gobcore/model/gobmodel.json) - [JSON Schema](https://json-schema.org/) `35:T67c,md` Het Amsterdam Schema wordt gebruikt om datasets te beschrijven, API's te genereren, en een aantal eigenschappen van objecten binnen een dataset af te dwingen: - Elk object heeft een uniek \`id\`. - Elk object zit in één dataset, ook deze dataset heeft een uniek \`id\`. - Elke dataset heeft een set _classes_ (bv. \`pand\`, \`verblijfsobject\`). - Elk object heeft een aantal verplichte velden, bijvoorbeeld \`dateCreated\`, \`dateUpdated\`, \`authorizationScope\` etc. - Elk object heeft een \`id\`, deze is uniek binnen deze object-class. Van een object-ID kan een ID gemaakt worden dat uniek is binnen de dataset door de class toe te voegen, bijvoorbeeld: \`pand:0363100012236081\` - Van een object-ID kan een ID dat uniek is binnen alle datasets door zowel het dataset-ID als de class toe te voegen, bijvoorbeeld: \`bag:pand:0363100012236081\` - De basis-URI van Amsterdam Schema is bv. \`https://resource.data.amsterdam.nl/\`. - Op deze manier is van een object-ID zowel een URN als een URL te maken, bijvoorbeeld: - \`urn:bag:pand:0363100012236081\` - \`https://resource.data.amsterdam.nl/bag/pand/0363100012236081\` - Relaties worden gemodelleert door objecten naar één of meerdere andere objecten te laten verwijzen. Elke verwijzing heeft een \`class\`. - _**One-to-one**_: een object kan via een URI naar een ander object verwijzen. - _**Many-to-one**_: meerdere objecten kunnen naar dezelfde URI verwijzen. - _**One-to-many**_: een object kan een lijst van URI's bevatten, en zo naar meerdere andere objecten verwijzen. - _**Many-to-many**_: meerdere objecten kunnen via zo'n lijst naar dezelfde (en andere) objecten verwijzen. `36:T4c7,md` __Wij stellen voor JSON Schema te gebruiken voor het Amsterdam Schema!__ JSON Schema is: - [Eenvoudig te leren en gebruiken](https://json-schema.org/understanding-json-schema)! - Uitbreidbaar! - En je kunt JSON Schema's samenstellen uit verschillende bestaande componenten. - JSON Schema is makkelijker te lezen en schrijven dan XSD! - Er zijn goede tools voor beschikbaar, voor alle programmeertalen! - Minder academisch dan OWL/SHACL/RDF! - Eenvoudig te converteren naar JSON-LD! - Leuk! - We gebruiken JSON in de output van onze REST-API's. En JSON is ook handig als invoerformaat, en als intern formaat (bv. op eventuele _event bus_). Ook in PostgreSQL kunnen we JSON opslaan in een \`jsonb\`-veld. Kortom: JSON Schema past naadloos! Ook is het eenvoudig om het GOB-model [te converteren naar JSON Schema](https://observablehq.com/@bertspaan/gob-model-amsterdam-schema). Zie ook: - [Amsterdam Schema Playground 🎠](https://observablehq.com/@bertspaan/amsterdam-schema-playground) - [Amsterdam Schema Importwizard 🧙‍♀️](https://observablehq.com/@bertspaan/amsterdam-schema-importwizard) - [Amsterdam Schema Validator 👩🏼‍🏫](https://observablehq.com/@bertspaan/amsterdam-schema-validator) `37:Tabc,classProperty = md`#### JSON Schema ⟷ Linked Data Stel, we gebruiken [Turtle](https://en.wikipedia.org/wiki/Turtle_(syntax)) om een gemeentelijke gebruiksregel te definiëren: \`\`\`ttl @prefix : . @prefix gebruiksregels: . @prefix subjecten: . gebruiksregels:1 a :Gebruiksregel ; :documentnummer "1234a" ; :geldtVoor ( subjecten:1 subjecten:2 ) . \`\`\` Gebruiksregel \`gebruiksregels:1\` heeft een _one-to-many_-relatie met gemeentelijke subjecten, in dit geval \`subjecten:1\` en \`subjecten:2\`. De relatie heeft de volgende eigenschappen: - een __naam/class__, in dit geval \`geldtVoor\`; - de relatie verwijst naar een of meerdere __URI's__; - ook is belangrijk te weten naar __welk class objecten de relatie verwijst__. Met o.a. OWL en SHACL is deze restrictie te modeleren. JSON Schema is niet specifiek ontworpen om linked data te modeleren. Hoe kunnen we dit toch doen? Dit is dezelfde gebruiksregel, in JSON: \`\`\`json { "id": "1", "dataset": "gemeente", "class": "gebruiksregel", "documentnummer": "1234a", "geldtVoor": [ "urn:amsterdam:gemeente:subjecten:1", "urn:amsterdam:gemeente:subjecten:2" ] } \`\`\` Door een URI-type te definiëren in Amsterdam Schema kunnen _one-to-one_-relaties als volgt worden gemodelleerd: \`\`\`json { "geldtVoor": { "$ref": "https://schemas.data.amsterdam.nl/v0.1#/definitions/uri" , "description": "Subject waarvoor deze gebruiksregel geldt." } } \`\`\` En _one-to-many_-relaties op deze manier: \`\`\`json { "geldtVoor": { "type": "array", "items": { "$ref": "https://schemas.data.amsterdam.nl/v0.1#/definitions/uri" }, "description": "Subjecten waarvoor deze gebruiksregel geldt." } } \`\`\` Eén ding ontbreekt nu nog: we weten niet naar welk type object zo'n relatie verwijst. In de nieuwe versie van JSON Schema, versie \`draft-handrews-*-02\`, staat het toe een eigen [_vocabulary_](https://json-schema.org/work-in-progress/WIP-jsonschema-core.html#rfc.section.3.2) te definiëren die nieuwe _keywords_ toevoegt. Als we een nieuw keyword \`ams.class\` toevoegen die de URI van het type bevat waarnaar een relatie verwijst, ziet het JSON Schema er zo uit: ~~~json { "geldtVoor": { "type": "array", "items": { "ams.class": "https://schemas.data.amsterdam.nl/v0.1/gemeente/subjecten", "$ref": "https://schemas.data.amsterdam.nl/v0.1#/definitions/uri" }, "description": "Subjecten waarvoor deze gebruiksregel geldt." } } ~~~ __De nieuwe JSON Schema-versie is nog niet af, maar voorlopig werkt deze manier prima!__ `38:T952,md` We hebben veel ervaring met PostgreSQL. Het ligt voor de hand een eerste versie van een uniform opslagsysteem te ontwikkelen dat van deze database gebruik maakt. __Voorstel: PostgreSQL, alle data in twee tabellen. Eén voor objecten, één voor relaties.__ Objecten: | Veld | Type | Index | Omschrijving | | ----------------- |:--------------| -------| ------------------------------------ | | \`id\` | \`text\` | B-tree | | | \`dataset\` | \`text\` | B-tree | | | \`class\` | \`text\` | B-tree | | | \`title\` | \`text\` | \`GIN (to_tsvector('dutch', title)\` | | | \`data\` | \`jsonb\` | GIN | | | \`authscope\` | \`text\` | … | | | \`date_created\` | \`timestamp\` | … | | | \`date_modified\` | \`timestamp\` | … | | | \`geometry\` | \`geometry\` | GiST | | Met [_partitioning_](https://www.postgresql.org/docs/9.1/ddl-partitioning.html) kunnen we de opslag per dataset of class wellicht efficiënter maken. Relaties: | Veld | Type | Index | Omschrijving | | -------------- |:-------------| -------| ------------------------------------ | | \`dataset\` | \`text\` | B-tree | | | \`class\` | \`text\` | B-tree | | | \`from\` | \`text\` | B-tree | | | \`to\` | \`text\` | B-tree | | | \`authscope\` | \`text\` | … | | Ook is er een tabel nodig voor alle datasets en de classes per dataset, hiervoor kunnen we wellicht gebruik maken het bestaande DCAT-systeem. Ook moeten we per dataset en class de vereiste autorisatie opslaan. #### Andere opties - PostgreSQL: relationeel, een tabel voor objecten van één class, - Combinatie van PostgreSQL en Elasticsearch, - En er zijn nog honderd andere manieren om dit te doen… 🤷‍♂️ `39:T70f,md` Momenteel zijn er, onder andere, API's voor de volgende vragen: - [Monumenten in buurt van locatie](https://api.data.amsterdam.nl/geosearch/monumenten/?monumenttype=isnot_pand_bouwblok&lat=52.3750261&lon=4.8908243&radius=25) - [Openbare ruimten met naam _"nieuwmarkt"_](https://api.data.amsterdam.nl/atlas/search/openbareruimte/?q=nieuwmarkt&subtype=weg) - [Objecten die beginnen met de tekst _"maurits"_](https://api.data.amsterdam.nl/typeahead?q=maurits) - [De Gashouder (pand \`0363100012236081\`)](https://api.data.amsterdam.nl/bag/pand/0363100012236081/) - [BAG-objecten binnen polygoon](https://api.data.amsterdam.nl/dataselectie/bag/?page=1&dataset=ves&shape=%5B%5B4.891918326492057%2C52.37676667637703%5D%2C%5B4.890400342526303%2C52.37484110823072%5D%2C%5B4.894344876682296%2C52.37246269435355%5D%2C%5B4.896589598647593%2C52.37713346625333%5D%5D) - [Lijst van DCAT-datasets](https://api.data.amsterdam.nl/dcatd/datasets?offset=0&limit=100) - [Pand waarin adres Rokin 22 ligt](https://api.data.amsterdam.nl/bag/pand/?verblijfsobjecten__id=0363010011259041) - [Monument _"Admiraliteitszeemagazijn"_](https://api.data.amsterdam.nl/monumenten/monumenten/?betreft_pand=0363100012170236) - [Adressen in Banne Buiksloot](https://data.amsterdam.nl/data/bag/adressen/?modus=volledig&filters=%7B%22buurtcombinatie_naam%22%3A%22Banne%20Buiksloot%22%7D) (met [_facets/aggregations_](https://www.elastic.co/guide/en/elasticsearch/reference/current/search-aggregations.html)) - [Panoramafoto's in de buurt van foto \`TMX7316010203-000227_pano_0000_000522\`](https://api.data.amsterdam.nl/panorama/panoramas/TMX7316010203-000227_pano_0000_000522/adjacencies/?newest_in_range=true&tags=mission-bi) Wat is de overlap tussen al deze _endpoints_? Kunnen we een API ontwerpen die al deze functionaliteit bundelt?`3a:Tf1e,md` Een voorbeeld van hoe we REST-API’s uniform zouden kunnen opzetten: | Omschrijving | Endpoint | | ----------------------------- |:--------------------------------------------------------------------- | | Metadata over enkele dataset | \`/v2/\{dataset\}\` | | Lijst van objecten | \`/v2/\{dataset\}/\{class\}\` | | Eén object | \`/v2/\{dataset\}/\{class\}/\{id\}\` | | Objecten in de buurt van punt | \`/v2/\{dataset\}/\{class\}?near=52.362,4.922\&distance=25m\` | | | \`/v2/\{dataset\}/\{class\}?near=121560,487341&srid=28992\&distance=1km\` | | Zoek \`n\` dichtstbijzijnde objecten | \`/v2/\{dataset\}/\{class\}?near=121560,487341&srid=28992\` | | | \`/v2/\{dataset\}?near=52.362,4.922\&distance=25m&class=\{class\}\` | | Gebruik WKT \`SRID=4326;POINT(4.922 52.362)\` | \`/v2/\{dataset\}/\{class\}near=SRID%3D4326%3BPOINT%284.922%2052.362%29\` | | Gebruik WKT \`POINT(4.922 52.362)\` | \`/v2/\{dataset\}/\{class\}near=POINT%284.922%2052.362%29\&srid=4326\` | | In de buurt van object | \`/v2/\{dataset\}/\{class\}?near=urn:amsterdam:gebieden:buurt:44d\` | | | \`/v2/\{dataset\}/\{class\}?near=urn:amsterdam:gebieden:buurt:44d\&distance=100m\` | | | \`/v2/\{dataset\}/\{class\}?near=urn:amsterdam:gebieden:buurt:44d\&distance=2km\` | | Objecten in een ander object | \`/v2/\{dataset\}/\{class\}?contained_by=\{urn\}\` | | Objecten in een rechthoek | \`/v2/\{dataset\}/\{class\}?contained_by=52.362,4.922,52.421,4.810\&srid=4326\` | | Objecten in een WKT-polygoon | \`/v2/\{dataset\}/\{class\}?contained_by=\{wktPolygon\}\` | | Objecten die een object doorsnijden | \`/v2/\{dataset\}/\{class\}?intersects_with=\{urn\}\` | intersects_with=urn:amsterdam:gebieden:wijk:west | Objecten met relatie | \`/v2/\{dataset\}/\{class\}?urn:amsterdam:bag:inPand=urn:amsterdam:bag:pand:0363100012236081\` | - De basis-URL van de API is \`https://api.data.amsterdam.nl\`. - \`\{id\}\` is hier het _interne ID_ van het object (uniek binnen een dataset). Je kunt hier een [URN](https://en.wikipedia.org/wiki/Uniform_Resource_Name) van maken door de datasetidentifier en de class toe te voegen, bijvoorbeeld: \`urn:amsterdam:bag:pand:0363100012236081\`. - In plaats van de volledige URN kan in sommige gevallen ook een kortere versie gebruikt worden: - \`0363100012236081\`; - \`pand:0363100012236081\`; of - \`bag:pand:0363100012236081\`. - De basis-URI van de objecten in de API is bv. \`https://resource.data.amsterdam.nl\`. Zie [Amsterdam Schema](#sectionProcessSchema). - Ook andere [OGC-relaties](https://gisforthought.com/projects/postgis_tutorial/spatial_relationships.html) ondersteunen. - Wellicht ook kijken naar 't [DE-9IM-model](https://postgis.net/workshops/postgis-intro/de9im.html). - In PostGIS kunnen we de functie [\`ST_DWithin\`](https://postgis.net/docs/ST_DWithin.html) gebruiken - De \`near\`-parameter werkt als volgt: - Accepteert coördinaat (twee getallen, door komma gescheiden), [WKT-geometrie](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry), of URN van een object. - \`srid\`: default is 4326, ook 28992 is mogelijk, en eventueel andere coördinaatsystemen - \`distance\`: getal met eenheid. Bijvoorbeeld \`25m\`. Eenheid kan zijn \`m\` of \`km\`. We kunnen zelf software schrijven die de data op deze manier publiceert, maar we kunnen ook kijken naar bestaande tools. Bijvoorbeeld: - [PostgREST](http://postgrest.org/en/v5.2/index.html) - [PostGraphile](https://github.com/graphile/postgraphile) `3b:T79c,html` `3c:[] 2f:{"title":"Werkbestand Team Dataservices","cells":[{"id":0,"value":"html`

Werkbestand Team Dataservices

`","pinned":false,"hidden":false,"mode":"ojs"},{"id":492,"value":"$31","pinned":false,"hidden":false,"mode":"ojs"},{"id":411,"value":"md`_De blokken en componenten in onderstaand diagram verwijzen naar hoofdstukken in dit notebook. Klik op een blok of component om naar dit hoofdstuk te gaan._`","pinned":false,"hidden":false,"mode":"ojs"},{"id":853,"value":"$32","pinned":false,"hidden":false,"mode":"ojs"},{"id":1428,"value":"md`NB: het __terugmelden__ van de resultaten van de import en het gebruik van data naar de beheerder is nog niet in dit schema opgenomen.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":153,"value":"sectionCollect = heading`Verzamelen`","pinned":false,"hidden":false,"mode":"ojs"},{"id":440,"value":"sectionCollectData = md`### Data`","pinned":false,"hidden":false,"mode":"ojs"},{"id":162,"value":"md`\nTeam Dataservices verzamelt zelf geen data. Andere teams leveren data volgens bepaalde specificaties en standaarden, het [Amsterdam Schema](#sectionProcessSchema). Deze teams kunnen ervoor kiezen eigen ETL-software te gebruiken, zolang de uitvoer maar voldoet aan het schema. Dataservices zorgt voor de import, opslag en publicatie van de data.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":156,"value":"sectionCollectModel = md`### Modelleren`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1816,"value":"md`Het modelleren van data gebeurt aan de hand van het [Amsterdam Schema](#sectionProcessSchema). Team Dataservices ontwerpt dit schema, documentatie, voorbeelden en tools waarmee data kan worden gecontrolleerd en geconverteerd.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1354,"value":"currently`\n- Verschilt per project. Data wordt op verschillende manieren aangeleverd, per project wordt data getransformeerd, met weinig consistentie in identifiers, veldnamen en dataklassen.\n- [GOB](https://github.com/Amsterdam/GOB) uniformiseert dit proces voor basisregistraties.\n- [Various Small Datasets](https://github.com/Amsterdam/various_small_datasets) is een project om voor een tal van kleinere datasets uniforme opslag en publicatie te verzorgen.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":789,"value":"requirements`\n- Ontwikkelen van het [Amsterdam Schema](#sectionProcessSchema) waarmee databronnen op een generieke manier kunnen worden gemodelleerd.\n- Ontwikkelen van en adviseren over instrumenten voor het modeleren van data volgens het Amsterdam Schema.\nOntwikkelen van automatische processen en ETL-tools voor het importeren en verrijken van data (vergelijkbaar wat GOB doet voor de basisregistraties).\n- Tools om veel voorkomende dataformaten (zoals bijvoorbeeld Shapefiles, CSV-bestanden, etc.) te converteren en importeren.\n- Een bibliotheek met voorbeeldschema's en _best practices_ (een _cookbook_👩‍🍳!).\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":532,"value":"begin`\nWe kunnen beginnen door de ETL-code in een paar projecten van de applicatiecode te scheiden en schema's voor deze data te maken. We kunnen beginnen met bijvoorbeeld de volgende projecten:\n\n- [Panorama-foto's](https://github.com/Amsterdam/panorama/tree/master/web/panorama/panorama/etl),\n- [Monumenten](https://github.com/Amsterdam/monumenten/tree/master/src/monumenten/importer),\n- [Bouwdossiers](https://github.com/Amsterdam/stadsarchief/tree/master/src/stadsarchief/datasets/bouwdossiers),\n- Datasets die worden verzameld en gemodelleerd in de huidige Datasquads,\n- Datasets van [maps.amsterdam.nl](https://maps.amsterdam.nl/) die daar ook worden beheerd.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1276,"value":"seeAlso`\nDe Datasquads gebruiken momenteel eigen ETL-tools:\n - [Pentaho Data](https://www.hitachivantara.com/en-us/products/big-data-integration-analytics/pentaho-data-integration.html)\n - [FME](https://www.safe.com/fme/fme-desktop)\n\nZie ook: [werkafspraken Datasquads](https://dokuwiki.datapunt.amsterdam.nl/doku.php?id=start:werkafspraken:datasquads).\n` ","pinned":false,"hidden":false,"mode":"ojs"},{"id":174,"value":"sectionProcess = heading`Verwerken`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1069,"value":"md`In dit gedeelte gebeurt het volgende:\n\n- Via een [Import-API](#sectionProcessImport) kunnen datasets worden toegevoegd en geüpdatet;\n- De datasets worden gecontroleerd aan de hand van het [Amsterdam Schema](#sectionProcessSchema);\n- Er worden [verrijkingen en aggregaties](#sectionProcessEnrich) uitgevoerd;\n- De datasets worden daarna opgeslagen in een database.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":184,"value":"sectionProcessImport = md`### Import`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1638,"value":"md`Hier komen ideeën over het ontwerp van een import-API:\n\n- Sommige datasets zullen via de objectstore worden geïmporteerd,\n- Andere wellicht via een speciale REST-API.\n- Hoe zorgt dit systeem dat het bij bulk-imports niet alleen weet welke objecten worden toegevoegd of gewijzigd, maar ook welke worden verwijderd? Het moet dan steeds de hele import vergelijken met alle bestaande objecten. Hoe doen we dit?\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":67,"value":"sectionProcessSchema = md`### Amsterdam Schema`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1641,"value":"md`\nWe hebben een manier nodig om alle data die die door ons verwerkt en gepubliceerd wordt op een uniforme maar flexibele manier te modelleren en beschrijven. We verwerken zeer uiteenlopende data. Veel data is geografisch (gekoppeld aan een locatie of een adres), maar er zijn ook datasets zoals raadsbesluiten en statistisch onderzoek die niet op deze manier op te slaan of te publiceren zijn. Eén ding hebben alle datasets gemeen: ze gaan over Amsterdam.\n\nKunnen we een technologie en een manier van beschrijven vinden die voor al deze data werkt?`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1343,"value":"$33","pinned":false,"hidden":false,"mode":"ojs"},{"id":475,"value":"$34","pinned":false,"hidden":false,"mode":"ojs"},{"id":1203,"value":"$35","pinned":false,"hidden":false,"mode":"ojs"},{"id":1661,"value":"$36","pinned":false,"hidden":false,"mode":"ojs"},{"id":1825,"value":"$37","pinned":false,"hidden":false,"mode":"ojs"},{"id":1164,"value":"md`#### Meta-schema\n\nElke dataset bestaat dus, naast [DCAT-metadata](https://www.w3.org/TR/vocab-dcat/) en de data zelf, uit een JSON Schema die de data beschrijft. Ook kunnen we een JSON Schema ontwerpen om zo'n datasetschema zélf te valideren. Bijvoorbeeld:\n\n- Elk object is een \\`https://schema.data.amsterdam.nl/v0.1#/definitions/object\\`\n- Elke \\`property\\` heeft een [\\`description\\`](https://json-schema.org/understanding-json-schema/reference/generic.html).\n- Elk object heeft een class, gedefinieerd door de dataset: \\`https://schemas.data.amsterdam.nl/v0.1/bag#/definitions/class\\`.\n- Een object kan in de root (dus niet dieper in geneste properties) een relatie met een ander object (of meerdere objecten) leggen. Deze relaties hebben een \\`class\\`.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1167,"value":"md`#### Voorbeelden\n\nHieronder volgen een paar voorbeelden die laten zien hoe validatie aan de hand zo'n JSON Schema werkt. De schema's zelf staan [onderin dit notebook](#jsonSchemas).\n\n__Je kunt de JSON-data hieronder zelf aanpassen!__ Na elke aanpassing wordt de data automatisch gevalideerd. Probeer bijvoorbeeld velden toe te voegen, te wijzigen, of bijvoorbeeld het bouwjaar te veranderen van een getal in een string.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1698,"value":"md`#### Een BAG-pand:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":374,"value":"viewof bagSource = {\n const value = JSON.stringify(bagPandObject, null, 2)\n return codeView({mode: 'jsx', value})\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":362,"value":"{\n let results = await validate(JSON.parse(bagSource), bagPandSchema)\n\n if (!results.valid) {\n throw new Error(JSON.stringify(results.errors, null, 2))\n }\n \n return html`Dit is een correct BAG-pandobject!`\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1701,"value":"md`#### Panoramafoto:`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1148,"value":"viewof panoramaImageSource = {\n const value = JSON.stringify(panoramaImageObject, null, 2)\n return codeView({mode: 'jsx', value})\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1154,"value":"{\n let results = await validate(JSON.parse(panoramaImageSource), panoramaImageSchema)\n\n if (!results.valid) {\n throw new Error(JSON.stringify(results.errors, null, 2))\n }\n \n return html`Dit is een correcte panoramafoto!`\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1706,"value":"md`#### Pandschema (validatie via metaschema):`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1465,"value":"viewof bagPandSchemaSource = {\n const value = JSON.stringify(bagPandSchema, null, 2)\n return codeView({mode: 'jsx', value})\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1470,"value":"{\n let results = await validate(JSON.parse(bagPandSchemaSource), amsterdamObjectMetaSchema)\n\n if (!results.valid) {\n throw new Error(JSON.stringify(results.errors, null, 2))\n }\n \nreturn html`Dit is een correct Amsterdam Object JSON Schema!`\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1251,"value":"sectionProcessEnrich = md`### Verrijken & Aggregeren`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1328,"value":"md`\nSommige datasets moeten worden verrijkt of geaggregeerd voor ze gepubliceerd worden. Denk bijvoorbeeld aan de volgende processen:\n\n- Zoeken van BAG-adres bij adrestekst;\n- Vinden van geografische hiërarchie in dataset;\n- Het doen van analyses door data te groeperen en koppelen.\n\nOok voor deze verrijkingen kunnen we een JSON Schema ontwikkelen:\n\n- Elke verrijking wordt uitgevoerd op een bepaalde \\`timestamp\\`, door bepaalde versie van een script.\n- Door voorbeeld een _hash_ van de oorspronkelijke data in de verrijking op te slaan kan worden bijgehouden of een verrijking nog geldig is.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1377,"value":"currently`\n- In elk project gebeurt dit nu op een andere manier.\n- Er is geen afstemming over het modelleren van data.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":965,"value":"requirements`\n- Ontwikkelen van het Amsterdam Schema waarmee databronnen op een generieke manier kunnen worden gemodelleerd.\n- Ontwikkelen van automatische processen voor het importeren en verrijken van data (vergelijkbaar wat GOB doet voor de basisregistraties).\n- Ontwikkeling van een Import-API.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":968,"value":"begin`\n- Ontwerpen van het eerste versie van [Amsterdam Schema op GitHub](https://github.com/Amsterdam/amsterdam-schema),\n- Schema's maken voor een aantal bestaande datasets,\n- Aantal verrijkingsscripts ontwikkelen die de nieuwe GOB-API gebruiken om data te koppelen met BAG,\n- Eerste versie van Import-API, die simpelweg data inleest van de _object store_.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":983,"value":"seeAlso`\n\n- [URI-strategie digitaal stelsel](https://aandeslagmetdeomgevingswet.nl/digitaal-stelsel/technisch-aansluiten/standaarden/api-uri-strategie)\n- [NYC Space/Time Directory Architecture](http://spacetime.nypl.org/architecture/)\n` ","pinned":false,"hidden":false,"mode":"ojs"},{"id":268,"value":"sectionStorage = heading`Opslaan`","pinned":false,"hidden":false,"mode":"ojs"},{"id":610,"value":"md`\nHet opslaan van de data kan op veel manieren. In elk geval zijn er uiteindelijk zoekindexes nodig om de data efficiënt te kunnen benaderen. Als we goede afspraken over interne datamodellen en API's kunnen we simpel beginnen, en eventueel later technieken zoals _event sourcing_ toepassen. \n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":272,"value":"sectionStorageDatabase = md`### Database`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1327,"value":"$38","pinned":false,"hidden":false,"mode":"ojs"},{"id":1011,"value":"sectionStorageLogging = md`### Logging`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1063,"value":"md`Ook moeten we bijgehouden wie welke data opvraagt, wanneer dit gebeurt, en welke versie. Dat kan vast met Kibana!` ","pinned":false,"hidden":false,"mode":"ojs"},{"id":1379,"value":"currently`\n- Vrijwel alle API's gebruiken Django met een PostgreSQL-database;\n- En soms Elasticsearch voor zoeken op tekst en_autocomplete_.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":973,"value":"requirements`\n\n- Het verzorgen van opslag van getransformeerde en verrijkte data;\n- Ontwerp en implementatie van loggingsysteem.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":975,"value":"begin`\n- Implementatie van eerste versie van PostgreSQL-systeem.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1270,"value":"seeAlso`\n\n…\n` ","pinned":false,"hidden":false,"mode":"ojs"},{"id":13,"value":"sectionPublish = heading`Publiceren`","pinned":false,"hidden":false,"mode":"ojs"},{"id":481,"value":"md`\nDe belangrijkste taak van Team Dataservices: het publiceren van alle data op een uniforme en efficiënte manier, die bovendien eenvoudig in het gebruik is.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":624,"value":"$39","pinned":false,"hidden":false,"mode":"ojs"},{"id":635,"value":"sectionPublishApis = md`### API's & Search`","pinned":false,"hidden":false,"mode":"ojs"},{"id":461,"value":"md`\nIn elk geval moeten we data op de volgende manieren publiceren:\n\n- REST-API's voor lijsten en losse objecten, met filter- en zoekfunctionaliteit;\n- Voldoen aan de eisen van Basisinformatie uit het bestand _Requirements api basis- en kernregistraties_.\n- Toegang tot hele datasets in één keer, aanbieden van downloads van losse bestanden;\n- OGC: WFS en WMS;\n- Kaarttiles.\n\nDoor het Amsterdam Schema wordt de opslag van de data een stuk uniformer. We kunnen een aantal vaste uitvoerformaten ontwerpen, bijvoorbeeld:\n\n- JSON-LD\n- \n- JSON API\n- [GeoJSON](https://geojson.org/) \\`FeatureCollection\\` (in RD met CRS, en WGS84);\n- [IIIF-manifest](https://iiif.io/api/presentation/2.0/) voor collecties en documenten (bijvoorbeeld bouwdossiers);\n- WFS en WMS;\n- [NDJSON](http://ndjson.org/) voor losse bestanden. Voordeel: handig gebruik maken van _command-line_-tools zoals bijvoorbeeld \\`grep\\`, \\`head\\`, \\`sort\\`, en [\\`jq\\`](https://stedolan.github.io/jq/).\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1080,"value":"md`#### REST-API's`","pinned":false,"hidden":false,"mode":"ojs"},{"id":638,"value":"$3a","pinned":false,"hidden":false,"mode":"ojs"},{"id":1575,"value":"md`#### Search`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1765,"value":"md`PostgreSQL ondersteunt [_full text search_](https://www.postgresql.org/docs/11/textsearch.html), en met [PostGIS](https://postgis.net/) kunnen we zoeken op afstanden en locatie. Als dit niet genoeg is, bijvoorbeeld voor _facets/aggregations_ moeten we overwegen naast PostgreSQL ook Elasticsearch te implementeren.`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1572,"value":"md`#### GraphQL`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1772,"value":"md`Omdat alle opgeslagen data aan een basisdatamodel voldoet, kunnen we GraphQL-publicatie eenvoudig toevoegen. [GOB doet dit ook](https://github.com/Amsterdam/GOB-API/tree/develop/src/gobapi/graphql).`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1578,"value":"md`#### Andere API's`","pinned":false,"hidden":false,"mode":"ojs"},{"id":691,"value":"md`\n[SPARQL](https://en.wikipedia.org/wiki/SPARQL)? _Time series_-database? Kan ook!\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1017,"value":"sectionPublishAuthorization = md`### Autorisatie`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1564,"value":"md`\n- We kunnen gebruik maken van functionaliteit van PostgeSQL:\n - Rechten per dataset, type, object en relatie opslaan in \\`authscope\\`-veld. En query's aanpassen met:\n - [\\`INSTEAD OF\\`-triggers](https://www.postgresql.org/docs/11/plpgsql-trigger.html), en:\n - [\\`CREATE RULE\\`](https://www.postgresql.org/docs/11/sql-createrule.html).\n- Of we kunnen een tussenlaag maken (tussen publieke API en database), die verzoeken bewerkt of afwijst, afhankelijk van de rechten van de aanvrager.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1382,"value":"currently`\n- Elke API is een apart Django-project, veelal gemaakt met [Django REST framework](https://www.django-rest-framework.org/), en allemaal werken ze net weer een beetje anders.\n- Voor geografisch zoeken of zoeken op tekst zijn er aparte projecten.\n- Voor een lijst met bestaande API's, zie [api.data.amsterdam.nl/api](https://api.data.amsterdam.nl/api/).\n- Ook is de de datasetcatalogus, met nog meer data, in nog meer verschillende formaten: [data.amsterdam.nl/datasets](https://data.amsterdam.nl/datasets/).\n- Er zijn slechts 3 autorisatieniveau's: open, voor ambtenaren, of via een IP-whitelist.\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":831,"value":"requirements`\n- Ontwikkelen van specificaties voor API's;\n- Onder andere, een REST-API om alle data te benaderen: \n - Lijsten en objecten\n - Filteren op eigenschappen\n - Zoeken op tekst en locatie\n- Het aansluiten van autorisatie en logging op dit hele proces.\n- API om losse bestanden voor datacatalogus te genereren.\n- MapServer voor WFS en WMS\n- Onderzoek implementatie GraphQL.\n- Plan voor het aansluiten van onze API's op externe API's. Hoe gaan we om met het doorgeven van zoekvragen aan andere externe API's? Wat doen we:\n - Alle data opnemen?\n - Alleen relevante data opnemen?\n - Vraag doorsturen en resultaten samenvoegen?\n - De client zelf de vraag laten doorsturen?\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":835,"value":"begin`\n- We kunnen beginnen met het implementeren van een eerste versie van de REST-API beschreven in [API's & Search](#sectionPublishApis).\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":722,"value":"seeAlso`\n- [API strategie voor de Nederlandse overheid](https://geonovum.github.io/KP-APIs)\n- [Forum Standaardisatie: Geo-Standaarden](https://www.forumstandaardisatie.nl/standaard/geo-standaarden)\n- [Datamodel BAG](https://bag.basisregistraties.overheid.nl/datamodel)\n- [CitySDK Linked Data API](http://citysdk.waag.org/)\n- [JSON-LD](https://json-ld.org/)\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":501,"value":"md`## Data & functies voor dit notebook`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1057,"value":"md`Dit document is een interactief notebook, gemaakt met [Observable](https://observablehq.com/). Door links in de marge van een stuk tekst, data of code te klikken klapt zo'n _cel_ open, en kun je de inhoud aanpassen. Net als bij een spreadsheet worden daarna automatisch alle cellen die van deze cel afhankelijk zijn güpdatet. Voor meer informatie over interactieve Observable-notebooks, zie de [Five-Minute Introduction](https://observablehq.com/@observablehq/five-minute-introduction?collection=@observablehq/introduction).\n\n__De cellen hieronder zijn nodig om dit notebook goed weer te geven. Ze bevatten JSON Schema's, CSS en geïmporteerde JavaScript-modules.__\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":355,"value":"jsonSchemas = md`### JSON Schema's`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1438,"value":"amsterdamObjectMetaSchema = d3.json('https://ams-schema.glitch.me/meta/object@v0.1')","pinned":false,"hidden":false,"mode":"ojs"},{"id":1898,"value":"md`__TODO: restrictie toevoegen zodat alleen _root properties_ via URI's relaties kunnen leggen. Dit is niet mogelijk in geneste objecten!__`","pinned":false,"hidden":false,"mode":"ojs"},{"id":1121,"value":"panoramaImageSchema = ({\n $schema: \"http://json-schema.org/draft-07/schema#\",\n $id: \"https://ams-schema.glitch.me/dataset/panorama/image.objects@v0.1\",\n type: \"object\",\n required: ['id', 'type', 'dataset'],\n properties: {\n id: {\n $ref: 'https://ams-schema.glitch.me/schema@v0.1#/definitions/id'\n },\n dataset: {\n $ref: 'https://ams-schema.glitch.me/schema@v0.1#/definitions/dataset'\n }, \n class: {\n $ref: 'https://ams-schema.glitch.me/schema@v0.1#/definitions/class'\n },\n timestamp: {\n type: 'string',\n format: 'date-time'\n },\n filename: {\n type: 'string' \n },\n data: {\n type: 'object',\n additionalProperties: { \n not: {\n anyOf: [\n { type: 'object' },\n { type: 'array' }\n ]\n }\n }\n }\n }\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":291,"value":"bagPandSchema = d3.json('https://ams-schema.glitch.me/dataset/bag/panden.objects')","pinned":false,"hidden":false,"mode":"ojs"},{"id":1140,"value":"md`### Voorbeelddata`","pinned":false,"hidden":false,"mode":"ojs"},{"id":295,"value":"bagPandObject = ({\n dataset: 'bag',\n class: 'pand',\n id: '0363100012236081',\n pandnaam: 'Gashouder',\n bouwjaar: 1902,\n verblijfsobjecten: [\n 'urn:amsterdam:bag:vbo:0363010000992810',\n 'urn:amsterdam:bag:vbo:0363010000992812'\n ],\n buurt: 'urn:amsterdam:gebieden:buurt:03630000000548'\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":1144,"value":"panoramaImageObject = ({\n id: 'tmx7316010203-000702_pano_0000_002842',\n class: 'image',\n dataset: 'panorama',\n timestamp: '2018-05-02T09:28:47.102710Z',\n filename: 'pano_0000_002842.jpg',\n sequence: 'TMX7316010203',\n previousImage: 'tmx7316010203-000702_pano_0000_002841',\n nextImage: 'tmx7316010203-000702_pano_0000_002843',\n geometry: {\n type: 'Point',\n coordinates: [\n 4.8900637,\n 52.3877012,\n 47.6610536\n ]\n },\n data: {\n missionType: 'bi',\n missionYear: 2018,\n surface: 'land',\n missionDistance: 5\n }\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":42,"value":"md`### Constanten en imports`","pinned":false,"hidden":false,"mode":"ojs"},{"id":444,"value":"colors = ({\n red: '#ec0000',\n blue: '#26c8ff',\n yellow: '#fffb16',\n orange: '#ff9011',\n green: '#00aa00'\n})","pinned":false,"hidden":false,"mode":"ojs"},{"id":744,"value":"brighten = (color) => {\n color = d3.color(color).brighter(.5)\n color.opacity = 0.15\n return color.toString()\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1959,"value":"toDataUrl = (svg) => {\n const str = new XMLSerializer().serializeToString(svg)\n const base64 = window.btoa(str)\n \n return `data:image/svg+xml;base64,${base64}`\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":1945,"value":"andreas = svg`\n\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":810,"value":"requirements = section('requirements', 'Wat gaat Team Dataservices doen?')","pinned":false,"hidden":false,"mode":"ojs"},{"id":535,"value":"begin = section('begin', 'Hoe kunnen we beginnen?')","pinned":false,"hidden":false,"mode":"ojs"},{"id":1260,"value":"seeAlso = section('see-also', 'Meer informatie')","pinned":false,"hidden":false,"mode":"ojs"},{"id":1350,"value":"currently = section('currently', 'Hoe gebeurt dit nu?')","pinned":false,"hidden":false,"mode":"ojs"},{"id":805,"value":"section = function (cls, heading) {\n return (text) => html`

${md`

${heading}

\n \n ${text}`}

`\n}","pinned":false,"hidden":false,"mode":"ojs"},{"id":839,"value":"heading = (text) => html`

${text}

`","pinned":false,"hidden":false,"mode":"ojs"},{"id":51,"value":"$3b","pinned":false,"hidden":false,"mode":"ojs"},{"id":1108,"value":"subgraphHead = `\n style=\"dashed,filled\";\n fillcolor=white;\n penwidth=2;\n color=\"${colors.red}\";\n margin=20;\n`","pinned":false,"hidden":false,"mode":"ojs"},{"id":46,"value":"dotHead = `\n rankdir=LR;\n graph[pad=0, ranksep=.5, nodesep=.5, splines=ortho];\n node[shape=record, style=filled, fillcolor=white];\n\n graph[fontname=\"monospace\", fontsize=14];\n node[fontname=\"monospace\", fontsize=12, margin=\"0.25,0.055\"];\n edge[fontname=\"monospace\", fontsize=10];`","pinned":false,"hidden":false,"mode":"ojs"},{"id":2,"value":"dot = require('@observablehq/graphviz@0.2')","pinned":false,"hidden":false,"mode":"ojs"},{"id":372,"value":"import {codeView} from '@benatkin/codemirror-iframe'","pinned":false,"hidden":false,"mode":"ojs"},{"id":312,"value":"Ajv = require('ajv@6.10.0/dist/ajv.bundle.js')","pinned":false,"hidden":false,"mode":"ojs"},{"id":736,"value":"d3 = require('d3@v5')","pinned":false,"hidden":false,"mode":"ojs"},{"id":1970,"value":"import {validate} from '@bertspaan/amsterdam-schema-validator'","pinned":false,"hidden":false,"mode":"ojs"},{"id":1806,"value":"import {icons} from '@observablehq/suggestions-and-comments'","pinned":false,"hidden":false,"mode":"ojs"}],"files":"$W3c","stdlib":"1","titling":"auto"}