Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documented profiles (and Fix generating spec using latest bikeshed version) #1202

Merged
merged 4 commits into from
Jan 16, 2025
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/Makefile
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
ams-schema-spec.html: ams-schema-spec.bs
bikeshed spec $< $@
sed -i 's/ *$$//' $@
sed -i.bak -e 's/ *$$//' $@
rm [email protected]
83 changes: 42 additions & 41 deletions docs/ams-schema-spec.bs
Original file line number Diff line number Diff line change
Expand Up @@ -15,14 +15,15 @@ Logo: https://api.data.amsterdam.nl/api/gemeente_Amsterdam_logo.svg
Favicon: https://data.amsterdam.nl/favicon.png
Boilerplate: copyright no, footer no
Max ToC Depth: 2
Text Macro: DCAT <a data-link-type=biblio data-lt="vocab-dcat-2" data-biblio-type=informative>DCAT</a>
Text Macro: DCATURL https://www.w3.org/TR/vocab-dcat-2/
Text Macro: DCAT <a data-link-type=biblio data-lt="vocab-dcat-3" data-biblio-type=informative>DCAT</a>
Text Macro: DCATURL https://www.w3.org/TR/vocab-dcat-3/
Text Macro: BP <blockquote class="best-practice"> **Best Practice**
Text Macro: BPE </blockquote>
Text Macro: CONST *constant*
Text Macro: HIDELINESEXAMPLE class="example hide-lines" onClick="this.classList.toggle('hide-lines');this.classList.toggle('unhide-lines');"
Text Macro: SYNCSCROLLA class="a" onscroll="let sibling =this.nextElementSibling; sibling.scrollTop=this.scrollTop;sibling.scrollLeft=this.scrollLeft;"
Text Macro: SYNCSCROLLB class="b" onscroll="let sibling =this.previousElementSibling; sibling.scrollTop=this.scrollTop;sibling.scrollLeft=this.scrollLeft;"
Text Macro: HIDELINESEXAMPLE <div class="example hide-lines" onClick="this.classList.toggle('hide-lines');this.classList.toggle('unhide-lines');">
Text Macro: COMPAREA <div class="a" onscroll="let sibling =this.nextElementSibling; sibling.scrollTop=this.scrollTop;sibling.scrollLeft=this.scrollLeft;">
Text Macro: COMPAREB <div class="b" onscroll="let sibling =this.previousElementSibling; sibling.scrollTop=this.scrollTop;sibling.scrollLeft=this.scrollLeft;">
Text Macro: END </div>
</pre>

Advisement: De meest recente aanpassing aan deze specificatie is:<br/> [[#lastchange]]
Expand Down Expand Up @@ -69,7 +70,7 @@ Een dataset wordt beschreven in één of meer JSON bestanden.
Binnen deze bestanden bestaan de volgende niveaus:
: [[#datasets| dataset]]
:: Een samenhangende collectie van data met één beheerder of beherende instantie.
Zoals bedoeld in [[VOCAB-DCAT-2#dcat-scope|DCAT]].
Zoals bedoeld in [[vocab-dcat-3#dcat-scope|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.
: [[#tables|tabel]]
Expand All @@ -96,13 +97,13 @@ Met een dataset wordt een dataset zoals gedefinieerd in [DCAT] bedoeld. [DCAT] d
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 [[VOCAB-DCAT-2#dcat-scope]])
any of which might be collected into a dataset. (From [[vocab-dcat-3#dcat-scope]])

Verplichte attributen {#dataset-mandatory-fields}
-------------------------------------------------------
Een <dfn dfn export>dataset</dfn> binnen Amsterdam Schema bestaat uit een JSON bestand met in ieder geval de volgende velden:
<table dfn-type="attribute" dfn-for=dataset export class="dfn-table">
<tr><td><dfn>id</dfn> <td> {{id-type|identifier}} <td> Unieke identifier voor deze dataset. Moet voldoen aan [[#naamgeving]]. Conform \[DCAT § resource_identifier](https://www.w3.org/TR/vocab-dcat-2/#Property:resource_identifier).
<tr><td><dfn>id</dfn> <td> {{id-type|identifier}} <td> Unieke identifier voor deze dataset. Moet voldoen aan [[#naamgeving]]. Conform \[DCAT § resource_identifier](https://www.w3.org/TR/vocab-dcat-3/#Property:resource_identifier).
<tr><td><dfn>type</dfn> <td> {{schema-type}} <td> Type van dit bestand, in dit geval `"dataset"`.
<tr><td><dfn>status</dfn> <td> string
<td> Publicatiestatus van de dataset
Expand Down Expand Up @@ -179,7 +180,7 @@ Het is mogelijk op dataset niveau extra eigenschappen met meta-gegevens mee te g
Dit kan indien gewenst worden gebruikt om automatisch een [DCAT] catalogus te genereren.
De volgende velden zijn toegestaan:
<table dfn-type="attribute" dfn-for=dataset export class="dfn-table">
<tr><td><dfn>language</dfn> <td> string <td> Taal van de dataset volgens [ISO 639-1](http://id.loc.gov/vocabulary/iso639-1.html) of [ISO 639-2](http://id.loc.gov/vocabulary/iso639-2.html) Conform \[DCAT § resource_language](https://www.w3.org/TR/vocab-dcat-2/#Property:resource_language)
<tr><td><dfn>language</dfn> <td> string <td> Taal van de dataset volgens [ISO 639-1](http://id.loc.gov/vocabulary/iso639-1.html) of [ISO 639-2](http://id.loc.gov/vocabulary/iso639-2.html) Conform \[DCAT § resource_language](https://www.w3.org/TR/vocab-dcat-3/#Property:resource_language)
<tr><td><dfn>dateCreated</dfn> <td> {{date-time}} <td> Datum van publicatie. Conform \[DCAT § resource_release_date]([DCATURL]#Property:resource_release_date)
<tr><td><dfn>dateModified</dfn> <td> {{date-time}} <td> Meest recente datum waarop de dataset is aangepast. Conform \[DCAT § resource_update_date]([DCATURL]#Property:resource_update_date)
<tr><td><dfn>accrualPeriodicity</dfn> <td> string <td> Frequentie waarmee de dataset gepubliceerd wordt. Conform \[DCAT § dataset_frequency]([DCATURL]#Property:dataset_frequency)
Expand Down Expand Up @@ -244,7 +245,7 @@ Het pad gezien vanuit de locatie van het dataset bestand **zou** dus de volgende

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

<div [HIDELINESEXAMPLE]>
[HIDELINESEXAMPLE]
Voorbeeld van een dataset met twee tabel referenties.

Een `locaties` tabel in `./locaties/v1.0.0.json`.<br/>
Expand All @@ -254,7 +255,7 @@ Advisement: Van deze bestandsnaam en padstructuur moet niet worden afgeweken beh
highlight: json
line-highlight: 12-25
</pre>
</div>
[END]

Publisherreferenties {#publisher-refs}
----------------------------------------------------------
Expand Down Expand Up @@ -305,15 +306,15 @@ Een <dfn dfn export>tabel</dfn> binnen Amsterdam Schema is een JSON object met i

Advisement: Let op: Zie [[#naamgeving]] voor de eisen waaraan {{tabel/id}} moet voldoen.

<div [HIDELINESEXAMPLE]>
[HIDELINESEXAMPLE]
Voorbeeld van een minimale tabel definitie. De {{tabel/title}} en {{tabel/description}} velden zijn niet verplicht,
maar het is best practice ze toe te voegen.
<pre class="include-code">
path: examples/datasets/minimaal/personen/v1.0.0.json
highlight: json
line-highlight: 0-7,25-27
</pre>
</div>
[END]


Optionele attributen {#tabel-optional-fields}
Expand All @@ -323,7 +324,7 @@ Een [=tabel=] mag daarnaast de volgende attributen bezitten:
<tr><td><dfn>title</dfn> <td> string <td> zie [[#omschrijving]] Default: Gelijk aan {{tabel/id}}.
<tr><td><dfn>description</dfn> <td> string <td> zie [[#omschrijving]]
<tr><td><dfn>shortname</dfn> <td> string <td> Verkorte unieke naam van de tabel. zie [[#naamgeving]]
<tr><td><dfn>derivedFrom</dfn> <td> array<td> De datasets waar deze view op gebaseerd is. e.g. `<dataset>:<tabel>`. Dit attribuut is enkel noodzakelijk wanneer de dataset een view is.
<tr><td><dfn>derivedFrom</dfn> <td> array<td> De datasets waar deze view op gebaseerd is. e.g. `<dataset>:<tabel>`. Dit attribuut is enkel noodzakelijk wanneer de dataset een view is.
<tr><td><dfn>auth</dfn> <td> string | array <td> geautoriseerde [=scope|scope(s)=]. Default: gelijk aan waarde in dataset/{{dataset/auth}}, zie [[#autorisatie]].
<tr><td><dfn>reasonsNonPublic</dfn> <td> array({{nonPubReason}})
<td> een of meer gronden voor het niet openbaar maken van data obv uitzonderingen in Hoofdstuk 5 van de [[Woo]].
Expand Down Expand Up @@ -393,7 +394,7 @@ Daarnaast mag een [=schema=] object de volgende attributen bezitten:

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

<div [HIDELINESEXAMPLE]>
[HIDELINESEXAMPLE]
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.
Expand All @@ -402,7 +403,7 @@ Issue: Het identifier veld moet string zijn. De array optie wordt binnenkort ver
highlight: json
line-highlight: 7-25
</pre>
</div>
[END]


Temporaliteit {#temporaliteit}
Expand Down Expand Up @@ -484,86 +485,86 @@ Het versie nummer bestaat uit 3 getallen gescheiden door punten `MAJOR.MINOR.PAT

Zie [[#table-refs]] voor het toevoegen van verschillende versies van een tabel.

<div [HIDELINESEXAMPLE]>
[HIDELINESEXAMPLE]
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.
<div class="compare-code">
<div [SYNCSCROLLA]>
[COMPAREA]
`personen/v1.2.1.json`
<pre class="include-code">
path: examples/datasets/bekendeAmsterdammers/personen/v1.2.1.json
highlight: json
line-highlight: 5,28,31-34
</pre>
</div>
<div [SYNCSCROLLB]>
[END]
[COMPAREB]
`personen/v1.3.0.json`
<pre class="include-code">
path: examples/datasets/bekendeAmsterdammers/personen/v1.3.0.json
highlight: json
line-highlight: 5,28, 31-35,37-44
</pre>
</div>
[END]
</div>
</div>
[END]

<div [HIDELINESEXAMPLE]>
[HIDELINESEXAMPLE]
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.
<div class="compare-code">
<div [SYNCSCROLLA]>
[COMPAREA]
`personen/v1.3.0.json`
<pre class="include-code">
path: examples/datasets/bekendeAmsterdammers/personen/v1.3.0.json
highlight: json
line-highlight: 5,10-13,19-23,31-35
</pre>
</div>
<div [SYNCSCROLLB]>
[END]
[COMPAREB]
`personen/v2.0.0.json`
<pre class="include-code">
path: examples/datasets/bekendeAmsterdammers/personen/v2.0.0.json
highlight: json
line-highlight: 5,10-14,20-25,33-40
</pre>
</div>
[END]
</div>
</div>
[END]

<div [HIDELINESEXAMPLE]>
[HIDELINESEXAMPLE]
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.
<div class="compare-code">
<div [SYNCSCROLLA]>
[COMPAREA]
`personen/v2.0.0.json`
<pre class="include-code">
path: examples/datasets/bekendeAmsterdammers/personen/v2.0.0.json
highlight: json
line-highlight: 5-6,15,31,44
</pre>
</div>
<div [SYNCSCROLLB]>
[END]
[COMPAREB]
`personen/v2.0.1.json`
<pre class="include-code">
path: examples/datasets/bekendeAmsterdammers/personen/v2.0.1.json
highlight: json
line-highlight: 5-6,15,31,44
</pre>
</div>
[END]
</div>
</div>
[END]

<div [HIDELINESEXAMPLE]>
[HIDELINESEXAMPLE]
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".

Expand All @@ -578,7 +579,7 @@ Zie [[#table-refs]] voor het toevoegen van verschillende versies van een tabel.
line-highlight: 1,13-20,26
</pre>
</div>
</div>
[END]

Note: Deze semantic versioning standaard is geinspireerd door [[SCHEMVER inline]] wat weer is gebaseerd op [[SEMVER inline]].

Expand Down Expand Up @@ -1024,7 +1025,7 @@ Note: Elk veld is nullable tenzij het als `required` property is opgegeven, zie

<div class=example>
Voorbeeld van een geometrie veld.
<pre class=example class="include-code">
<pre class="include-code">
path: examples/datasets/bekendeAmsterdammers/pleinen/v1.0.0.json
highlight: json
show: 28-32
Expand All @@ -1044,15 +1045,15 @@ Note: Elk veld is nullable tenzij het als `required` property is opgegeven, zie
Note: Als een tabel een geometrie veld bevat, moet op dataset niveau het coordinaat
referentie systeem worden aangegeven in het {{dataset/crs}} attribuut.

<div [HIDELINESEXAMPLE]>
[HIDELINESEXAMPLE]
Voorbeeld van een tabel met meerdere geometrie velden. Het veld `"locatie"` is hier als primaire geometrie
aangegeven in "{{mainGeometry}}".
<pre class="include-code">
path: examples/datasets/bekendeAmsterdammers/pleinen/v1.0.0.json
highlight: json
line-highlight: 0-7,28-37
</pre>
</div>
[END]


### object ### {#data-types-object}
Expand Down Expand Up @@ -1857,10 +1858,10 @@ waarschuwingen of uitleg verschijnen dus niet in dit overzicht.
float: right;
background-repeat: no-repeat;
background-size: contain;
background-image: url("[LOGO]");
background-image: url("https://api.data.amsterdam.nl/api/gemeente_Amsterdam_logo.svg"); /* Using [LOGO] here fails on Bikeshed 4 */
}
#toc::before {
content: "[TITLE]";
content: "Amsterdam Schema Specificatie"; /* Using [TITLE] here fails on Bikeshed 4 */
background: rgb(0, 90, 156);
color: var(--tocsidebar-bg);
font-size: 18px;
Expand Down
Loading
Loading