Skip to content

Naming convention for mapping IRI's

Jurrian Tromp edited this page Nov 26, 2019 · 2 revisions

As discussed in #162:

Some had_primary_source are not correct, for example:

(58865) == https://argu.co/voc/mapping/source/source_id_key/organization/amersfoort => https://openbesluitvorming.nl/voc/mapping/amersfoort/?/?/?

(58875) == https://argu.co/voc/mapping/zwolle/ibabs/identifier/zwolle => https://openbesluitvorming.nl/voc/mapping/zwolle/ibabs/sitename/zwolle

(58908) == https://argu.co/voc/mapping/almere/notubiz/identifier/almere => https://openbesluitvorming.nl/voc/mapping/almere/notubiz/organization/952

(64006) == https://argu.co/voc/mapping/bloemendaal/gemeenteoplossingen/identifier/https:-gemeenteraad-bloemendaal-nl-api-v1-meetings-1607-documents-16511 => https://openbesluitvorming.nl/voc/mapping/bloemendaal/gemeenteoplossingen/document/16511

(250094) == https://argu.co/voc/mapping/zuid-holland/greenvalley/identifier/https:-staten-zuid-holland-nl-dsresource-objectid-7fdbf54e-d8fa-4d96-9dfc-51e2d336e7c2 => https://openbesluitvorming.nl/voc/mapping/zuid-holland/greenvalley/document/7fdbf54e-d8fa-4d96-9dfc-51e2d336e7c2

Mapping IRI's should have the following format: https://openbesluitvorming.nl/voc/mapping/<source>/<supplier>/<collection>/<identifier>

The following rules apply to the parts of this IRI. This is currently work in progress so new ones are added or they might be changed.

1. All parts
1.1 argu.co domain will be replaced by openbesluitvorming.nl
1.2 Characters are lower case
1.3 Special characters and spaces should be escaped, making the whole IRI url-escaped.
1.4 Dashes and underscores are not escaped

2. Source
2.1 Index name of the municipality or province
2.2 Spaces should be dashes underscores, for example: capelle_ad_ijssel
2.3 Dashes are only used when they appear in the name: hendrik-ido-ambacht, amsterdam_nieuw-west

3. Supplier
3.1 Long name for the supplier: greenvalley instead of gv.

4. Collection
4.1 Arbitrary name scoped on the supplier to avoid collisions with equal identifiers.
4.2 Should be the shortest concise name for describing the identifier. If possible and appropriate it should be one word.
4.3 It should not describe the relationship with the identifier but instead describe what the identifier is.
4.4 Ambiguity between names to be used in the future should be avoided.
4.5 Name should be consistent with previous use. If something was named municipality before, then it should be named the same the next time, unless there is a very compelling reason.
4.6 The name should specific and not be confusing if the collection can be interpreted in another way, for example: committee is more specific than organization.
4.7 Should preferably be a conventional complete name, document instead of doc.
4.8 Should be singular: document instead of documents.
4.9 Not including prefixes and postfixes like _id.
4.10 If the identifier is a UUID (universal unique) then the collection should be uuid. (removed, this gives us less information about what the resource actually is)
4.11 If there are no reasonable indications for collisions collection should be one word, membership instead of party_membership.

5. Identifier
5.1 The smallest identifier to identify a foreign resource
5.2 The most specific foreign identifier is preferred over the full url as identifier
5.3 If an identifier is an composite between two identifiers, i.e municipality and a person: alkmaar-vandijk. Then a slash should be used instead of a dash to avoid problems with uuid's which also contain dashes.
5.4. If multiple different instances could exist (in the future) the identifier should specify the difference, i.e these composite identifiers could exist simultaneously: alkmaar/chair/van-dijk and alkmaar/member/van-dijk.