From 1d4bd9cd9be0217039f861d8fa61d88b66eedc3a Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Mon, 29 Jun 2026 11:59:00 +0200 Subject: [PATCH 01/13] Beheer: zet spellcheck aan voor en-GB op het document --- .github/workflows/build.yml | 20 +++++++++++ index.html | 2 +- js/config.mjs | 19 +++++++++- sections/designRules.md | 8 ++--- sections/introduction.md | 4 +++ standaard.aff | 10 ++++++ standaard.dic | 70 +++++++++++++++++++++++++++++++++++++ 7 files changed, 127 insertions(+), 6 deletions(-) create mode 100644 standaard.aff create mode 100644 standaard.dic diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 439a9a9b..fbd37fe8 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -61,3 +61,23 @@ jobs: run: npm install -g @stoplight/spectral-cli - name: Run linter on ${{ matrix.example }} example run: ./examples/${{ matrix.example }}/build-and-check-project.sh + spellchecker: + name: Run spellcheck + runs-on: ubuntu-22.04 + steps: + - uses: actions/checkout@v4 + - name: Install hunspell + run: | + sudo apt-get install hunspell + wget -O en_GB.aff https://cgit.freedesktop.org/libreoffice/dictionaries/plain/en/en_GB.aff + wget -O en_GB.dic https://cgit.freedesktop.org/libreoffice/dictionaries/plain/en/en_GB.dic + - name: Build spellcheck version of standard + run: | + REPLACEMENT_REGEX="s/spellcheck: false/spellcheck: true/" + sed -i "$REPLACEMENT_REGEX" js/config.mjs + mkdir ~/static + npx respec --localhost --src index.html --out ~/static/index.html --haltonwarn + - name: Run spellcheck + run: | + hunspell -l -d en_GB,standaard -H ~/static/index.html | sort -u > spelling.txt + [ -s spelling.txt ] && cat spelling.txt && exit 1 diff --git a/index.html b/index.html index b2425bcb..684d9472 100644 --- a/index.html +++ b/index.html @@ -27,7 +27,7 @@

Linter configuration

-
+
diff --git a/js/config.mjs b/js/config.mjs index 95536d3a..bb93460c 100644 --- a/js/config.mjs +++ b/js/config.mjs @@ -54,6 +54,17 @@ async function highlightLinterCode(config, document) { }); } +function runSpellcheck(config, document) { + if (!config.spellcheck) { + return; + } + document.querySelector('.head').remove(); + document.getElementById('references')?.remove(); + for (const element of document.getElementsByClassName('remove-for-spellcheck')) { + element.remove(); + } +} + loadRespecWithConfiguration({ authors: [ { @@ -104,9 +115,15 @@ loadRespecWithConfiguration({ specStatus: "WV", specType: "ST", pluralize: true, + spellcheck: false, preProcess: [initializeHighlightJSYaml, fetchLinterConfiguration], - postProcess: [generateMermaidFigures, highlightLinterCode, (config, document, utils) => processRuleBlocks(config, document, utils, linterConfiguration)], + postProcess: [ + generateMermaidFigures, + highlightLinterCode, + (config, document, utils) => processRuleBlocks(config, document, utils, linterConfiguration), + runSpellcheck, + ], localBiblio: { "ADR-encryption": { diff --git a/sections/designRules.md b/sections/designRules.md index 06601b59..449210a3 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -18,13 +18,13 @@ The REST architectural style is centered around the concept of a [=resource=]. A diff --git a/sections/introduction.md b/sections/introduction.md index 0d4ba158..768bb0e7 100644 --- a/sections/introduction.md +++ b/sections/introduction.md @@ -20,6 +20,8 @@ This document is part of the *Nederlandse API Strategie*. The Nederlandse API Strategie consists of [a set of distinct documents](https://developer.overheid.nl/communities/kennisplatform-apis/#api-strategie). +
+ | Status | Description & Link | |------------------|------------------------------------------------------------------------------------------------------------------| | Informative | [Inleiding NL API Strategie](https://geonovum.github.io/KP-APIs/API-strategie-algemeen/Inleiding/) | @@ -34,6 +36,8 @@ The Nederlandse API Strategie consists of [a set of distinct documents](https:// Before reading this document it is advised to gain knowledge of the informative documents, in particular the [Architecture](https://geonovum.github.io/KP-APIs/API-strategie-algemeen/Architectuur/). +
+ An overview of all current documents is available in this Dutch infographic:
diff --git a/standaard.aff b/standaard.aff new file mode 100644 index 00000000..a755c8f6 --- /dev/null +++ b/standaard.aff @@ -0,0 +1,10 @@ +SET UTF-8 + +# Required to make sure that combinations of two are also allowed. +# The default is 3, which wouldn't match for RFC123 +COMPOUNDMIN 1 + +COMPOUNDRULE 3 +COMPOUNDRULE RN* # Allow RFC notation +COMPOUNDRULE IN* # Allow ISO notation +COMPOUNDRULE VN # Allow v1 notation diff --git a/standaard.dic b/standaard.dic new file mode 100644 index 00000000..6ecc7070 --- /dev/null +++ b/standaard.dic @@ -0,0 +1,70 @@ +69 +0/N +1/N +2/N +3/N +4/N +5/N +6/N +7/N +8/N +9/N +RFC/R +ISO/I +v/V +ADR +backend +BCP +beheermodel +birthDate +camelCase +CORS +CRS +CSRF +datetime +Digikoppeling +DX +Geonovum +json +JWE +JWS +Kennisplatform +Logius +meetingStartTime +NCSC +Nederlandse +NL +NLgov +OAuth +OAuth2 +OData +OGC +openapi +OpenAPI +OPENAPIS +Ottowa +Overheid +OWASP +ReDoc +regex +REpresentational +ReSpec +RESTful +RPC +SameSite +SemVer +Specref +Standaarden +Standaardisatie +subresource +timeOfBirth +timeOfBirthTimezone +timezone +timezones +URIs +WebDAV +Werkversie +WFS +XSS +yaml +YAML From 860edbfe891f7f972e2a52c57a047be1323795d3 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Wed, 1 Jul 2026 13:41:40 +0200 Subject: [PATCH 02/13] Beheer: fix alle spellingsfouten --- publishers.yml | 2 +- sections/designRules.md | 62 ++++++++++++++++++++-------------------- sections/introduction.md | 4 +-- standaard.dic | 6 +++- 4 files changed, 39 insertions(+), 35 deletions(-) diff --git a/publishers.yml b/publishers.yml index 78ea0618..a55dcaed 100644 --- a/publishers.yml +++ b/publishers.yml @@ -1,4 +1,4 @@ -# publishers.yml This is a list of organizations and repositories to crawl. +# publishers.yml This is a list of organisations and repositories to crawl. --- diff --git a/sections/designRules.md b/sections/designRules.md index 449210a3..5331902f 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -6,7 +6,7 @@ ## Resources -The REST architectural style is centered around the concept of a [=resource=]. A resource is an abstraction of a conceptual entity, identified by a globally unique [=URI=]. It may correspond to anything from a physical object (e.g. a building or a person) to an abstract concept (e.g. a permit, an event or today's weather). Although a resource is not tied to any specific exchange format, its current state can be transferred to clients through one or more representations, such as JSON or XML. +The REST architectural style is centred around the concept of a [=resource=]. A resource is an abstraction of a conceptual entity, identified by a globally unique [=URI=]. It may correspond to anything from a physical object (e.g. a building or a person) to an abstract concept (e.g. a permit, an event or today's weather). Although a resource is not tied to any specific exchange format, its current state can be transferred to clients through one or more representations, such as JSON or XML.
@@ -117,8 +117,8 @@ https://api.example.org/v1/vergunningen/d285e05c-6b01-45c3-92d8-5e19a946b66fStatement
-

Path segments of a [=URI=] MUST only contain lowercase letters, digits or hyphens. This is also known as kebab-case. Hyphens MUST only be used to deliniate distinct words. This also implies that diacritics MUST be normalized and special characters MUST be omitted. -

Another implication of this rule is that file extensions MUST NOT be used. Resources SHOULD use the Accept header for content negotation. +

Path segments of a [=URI=] MUST only contain lowercase letters, digits or hyphens. This is also known as kebab-case. Hyphens MUST only be used to delineate distinct words. This also implies that diacritics MUST be normalised and special characters MUST be omitted. +

Another implication of this rule is that file extensions MUST NOT be used. Resources SHOULD use the Accept header for content negotiation.

The last path segment MAY start with `_`, which is used as a convention to implement operations

@@ -136,7 +136,7 @@ https://api.example.org/v1/vergunningen/d285e05c-6b01-45c3-92d8-5e19a946b66fhttps://api.example.org/v1/organisatie-

URI path segment starting with a hyphen (incorrect):

https://api.example.org/v1/-organisatie
-

URI path segment using normalized diacritics (correct):

+

URI path segment using normalised diacritics (correct):

https://api.example.org/v1/scenes

URI path segment using diacritics (incorrect):

https://api.example.org/v1/scènes
@@ -167,12 +167,12 @@ https://api.example.org/v1/vergunningen/d285e05c-6b01-45c3-92d8-5e19a946b66fStatement
-

Query keys in a [=URI=] MUST only contain letters and digits, where the first letter of each word is capitalized, except for the first letter (MUST NOT be a digit) of the entire compound word. This is also known as lower camelCase. This also implies that diacritics MUST be normalized and special characters MUST be omitted. +

Query keys in a [=URI=] MUST only contain letters and digits, where the first letter of each word is capitalised, except for the first letter (MUST NOT be a digit) of the entire compound word. This is also known as lower camelCase. This also implies that diacritics MUST be normalised and special characters MUST be omitted.

Rationale
-

Query keys are often converted to JSON object keys, where camelCase is the naming convention to avoid compatibility issues with JavaScript when deserializing objects. +

Query keys are often converted to JSON object keys, where camelCase is the naming convention to avoid compatibility issues with JavaScript when deserialising objects.

@@ -292,7 +292,7 @@ Handling date and time is tricky and can lead to confusion among clients. The da
Rationale

Allowing clients to use any timezone offset in requests results in flexibility and less complexity for users. Using UTC in responses results in clarity and removes ambiguity. -

While storage formats are outside the scope of this specification, it is recommended to use appropriate temporal datatypes (such as DATE and TIMESTAMPTZ). Many database systems store these values internally in UTC and handle timezone conversion automatically on read/write. +

While storage formats are outside the scope of this specification, it is recommended to use appropriate temporal data types (such as DATE and TIMESTAMPTZ). Many database systems store these values internally in UTC and handle timezone conversion automatically on read/write.

@@ -333,7 +333,7 @@ Although the REST architectural style does not impose a specific protocol, REST
Rationale
- The HTTP specifications offer a set of standard methods, where every method is designed with explicit semantics. Adhering to the HTTP specification is crucial, since HTTP clients and middleware applications rely on standardized characteristics. + The HTTP specifications offer a set of standard methods, where every method is designed with explicit semantics. Adhering to the HTTP specification is crucial, since HTTP clients and middleware applications rely on standardised characteristics. @@ -410,7 +410,7 @@ Although the REST architectural style does not impose a specific protocol, REST

The HTTP specification [[RFC9110]] and the later introduced PATCH method specification [[RFC5789]] offer a set of standard methods, where every method is designed with explicit semantics. HTTP also defines other methods, e.g. HEAD, OPTIONS, TRACE, and CONNECT.
The OpenAPI Specification 3.0 Path Item Object also supports these methods, except for CONNECT.
According to RFC 9110 9.1 the GET and HEAD HTTP methods MUST be supported by the server, all other methods are optional.
- In addition to the standard HTTP methods, a server may support other optional methods as well, e.g. PROPFIND, COPY, PURGE, VIEW, LINK, UNLINK, LOCK, UNLOCK, etc.
+ In addition to the standard HTTP methods, a server may support other optional methods as well, e.g. PROPFIND, COPY, PURGE, VIEW, LINK, UNLINK, LOCK, UNLOCK, etcetera.
If an optional HTTP request method is sent to a server and the server does not support that HTTP method for the target resource, an HTTP status code 405 Method Not Allowed shall be returned and a list of allowed methods for the target resource shall be provided in the Allow header in the response as stated in RFC 9110 15.5.6.

How to test
@@ -503,7 +503,7 @@ Although the REST architectural style does not impose a specific protocol, REST ## Statelessness -One of the key constraints of the REST architectural style is stateless communication between client and server. It means that every request from client to server must contain all of the information necessary to understand the request. The server cannot take advantage of any stored session context on the server as it didn’t memorize previous requests. Session state must therefore reside entirely on the client. +One of the key constraints of the REST architectural style is stateless communication between client and server. It means that every request from client to server must contain all of the information necessary to understand the request. The server cannot take advantage of any stored session context on the server as it didn’t memorise previous requests. Session state must therefore reside entirely on the client. To properly understand this constraint, it is important to make a distinction between two different kinds of state: @@ -514,9 +514,9 @@ To properly understand this constraint, it is important to make a distinction be Stateless communication offers many advantages, including: -* *Simplicity* is increased because the server does not have to memorize or retrieve session state while processing requests +* *Simplicity* is increased because the server does not have to memorise or retrieve session state while processing requests * *Scalability* is improved because not having to incorporate session state across multiple requests enables higher concurrency and performance -* *Observability* is improved since every request can be monitored or analyzed in isolation without having to incorporate session context from other requests +* *Observability* is improved since every request can be monitored or analysed in isolation without having to incorporate session context from other requests * *Reliability* is improved because it eases the task of recovering from partial failures since the server does not have to maintain, update or communicate session state. One failing request does not influence other requests (depending on the nature of the failure of course). @@ -562,7 +562,7 @@ Resources are often interconnected by relationships. Relationships can be modell

The [=singular resources=] for comments, referenced from all 3 collections, could still be modelled on a higher level to avoid deep nesting of URIs (which might increase complexity or problems due to the URI length): 

https://api.example.org/v1/comments/123
 https://api.example.org/v1/comments/456
-

Although this approach might seem counterintuitive from a technical perspective (we simply could have modelled a single /comments resource with optional filters for article and photo) and might introduce partially redundant functionality, it makes perfect sense from the perspective of the consumer, which increases developer experience. +

Although this approach might seem counter-intuitive from a technical perspective (we simply could have modelled a single /comments resource with optional filters for article and photo) and might introduce partially redundant functionality, it makes perfect sense from the perspective of the consumer, which increases developer experience. @@ -581,7 +581,7 @@ https://api.example.org/v1/comments/456

There are resource operations which might not seem to fit well in the CRUD interaction model. For example, approving a submission or notifying a customer. Depending on the type of the operation, there are three possible approaches:
    -
  1. Re-model the resource to incorporate extra fields supporting the particular operation. For example, an approval operation can be modelled in a boolean attribute goedgekeurd that can be modified by issuing a PATCH request against the resource. A drawback of this approach is that the resource does not contain any metadata about the operation (when and by whom was the approval given? Was the submission rejected in an earlier stage?). Furthermore, this requires a fine-grained authorization model, since approval might require a specific role.
    2. +
  2. Re-model the resource to incorporate extra fields supporting the particular operation. For example, an approval operation can be modelled in a boolean attribute goedgekeurd that can be modified by issuing a PATCH request against the resource. A drawback of this approach is that the resource does not contain any metadata about the operation (when and by whom was the approval given? Was the submission rejected in an earlier stage?). Furthermore, this requires a fine-grained authorisation model, since approval might require a specific role.
  3. Treat the operation as a sub-resource. For example, model a sub-collection resource /inzendingen/12/beoordelingen and add an approval or rejection by issuing a POST request. To be able to retrieve the review history (and to consistently adhere to the REST principles), also support the GET method for this resource. The /inzendingen/12 resource might still provide a goedgekeurd boolean attribute (same as approach 1) which gets automatically updated in the background after adding a review. This attribute SHOULD however be read-only.
  4. In exceptional cases, the approaches above still do not offer an appropriate solution. An example of such an operation is a global search across multiple resources. In this case, the creation of a dedicated resource, possibly nested under an existing resource, is the most obvious solution. Use the imperative mood of a verb, maybe even prefix it with a underscore to distinguish these resources from regular resources. For example: /search or /_search. Depending on the operation characteristics, GET and/or POST method MAY be supported for such a resource.
@@ -649,7 +649,7 @@ Content-Type: application/problem+json{
Rationale
-

To reduce the amount of roundtrips between client and server, all applicable schema validation errors SHOULD be returned together. +

To reduce the amount of round trips between client and server, all applicable schema validation errors SHOULD be returned together. This allows a client to present validation errors to a user in one go, reducing user friction with multiple retries.

It depends on a validation technique whether this is possible or not. For example, when a client provides a date in the weekend, where only dates on weekdays are allowed, it depends on which service performs these validation checks. @@ -677,7 +677,7 @@ An API is as good as the accompanying documentation. The documentation has to be

How to test
- Parse the resource at the provided location as an OpenAPI Description and confirm all $refs are resolvable and paths are defined. + Parse the resource at the provided location as an OpenAPI Description and confirm all $refs are resolvable and paths are defined.
@@ -751,8 +751,8 @@ An API is as good as the accompanying documentation. The documentation has to be
How to test
    -
  • Step 1: The API MUST meet the prerequisites to be tested. These include that an OAS file (openapi.json) is publicly available, parsable, all $refs are resolvable and paths are defined.
    • -
  • Step 2: The openapi.yaml document MAY be available. If available it MUST contain YAML, be readable and parsable.
    • +
  • Step 1: The API MUST meet the prerequisites to be tested. These include that an OAS file (openapi.json) is publicly available, parseable, all $refs are resolvable and paths are defined.
    • +
  • Step 2: The openapi.yaml document MAY be available. If available it MUST contain YAML, be readable and parseable.
  • Step 3: The openapi.yaml document MUST contain the same OpenAPI Description as the openapi.json document.
  • Step 4: The CORS header Access-Control-Allow-Origin MUST allow all origins.
@@ -830,7 +830,7 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
Statement
- A changelog MUST be publised for every API version. + A changelog MUST be published for every API version.
Rationale
@@ -849,7 +849,7 @@ Changes in APIs are inevitable. APIs should therefore always be versioned, facil
Rationale
- Version numbering MUST follow the Semantic Versioning [[SemVer]] model to prevent breaking changes when releasing new API versions. Release versions are formatted using the major.minor.patch template (examples: 1.0.2, 1.11.0). Pre-release versions MAY be denoted by appending a hyphen and a series of dot separated identifiers (examples: 1.0.2-rc.1, 2.0.0-beta.3). When releasing a new version which contains backwards-incompatible changes, a new major version MUST be released. Minor and patch releases MUST only contain backwards compatible changes (e.g. the addition of an endpoint or an optional attribute). + Version numbering MUST follow the Semantic Versioning [[SemVer]] model to prevent breaking changes when releasing new API versions. Release versions are formatted using the major.minor.patch template (examples: 1.0.2, 1.11.0). Pre-release versions MAY be denoted by appending a hyphen and a series of dot separated identifiers (examples: 1.0.2-rc.1, 2.0.0-beta.3). When releasing a new version which contains backwards-incompatible changes, a new major version MUST be released. Minor and patch releases MUST only contain backwards compatible changes (e.g. the addition of an endpoint or an optional attribute).
How to test
@@ -910,7 +910,7 @@ Note: security controls for signing and encrypting of application level messages
How to test
-

The usage of TLS is machine testable. Follow the latest NCSC guidelines on what is required to test. The serverside is what will be tested, only control over the server is assumed for testing. A testing client will be employed to test adherence of the server. Supporting any protocols, algorithms, key sizes, options or ciphers that are deemed insufficient or phased out by NCSC will lead to failure on the automated test. Both positive and negative scenarios are part of the test: testing that a subset of *Good* and *Sufficient* configurations are supported and configurations deemed *Insufficient* or marked for *Phase out*. A manual exception to the automated test results can be made when configurations designated for *Phase out* are supported; The API provider will have to provide clear documentation regarding the phase out schedule. +

The usage of TLS is machine testable. Follow the latest NCSC guidelines on what is required to test. The server-side is what will be tested, only control over the server is assumed for testing. A testing client will be employed to test adherence of the server. Supporting any protocols, algorithms, key sizes, options or ciphers that are deemed insufficient or phased out by NCSC will lead to failure on the automated test. Both positive and negative scenarios are part of the test: testing that a subset of *Good* and *Sufficient* configurations are supported and configurations deemed *Insufficient* or marked for *Phase out*. A manual exception to the automated test results can be made when configurations designated for *Phase out* are supported; The API provider will have to provide clear documentation regarding the phase out schedule.

@@ -923,7 +923,7 @@ Note: security controls for signing and encrypting of application level messages

Sensitive information MUST NOT be part of URIs

The term sensitive is deliberately left undefined in this document.

-

In case of REST-API's for system to system communication on a closed network, this rule applies only when there is logging involved in systems that are not under control of the organizations involved in the exchange +

In case of REST-API's for system to system communication on a closed network, this rule applies only when there is logging involved in systems that are not under control of the organisations involved in the exchange

Rationale
@@ -935,7 +935,7 @@ Note: security controls for signing and encrypting of application level messages

Be aware that queries (anything after the '?' in a URI) are also part of a URI.

For REST API's that are accessed directly from user devices, like web browsers, do not put client secrets used for authentication and other sensitive information in the URI. These are directly visible to users, are stored in the web browser's history and cache and can be bookmarked and sent to others. -

For REST API's that are only used for system-to-system integration on closed networks where all systems are under control of the organizations involved in the exchange, do not put client secrets used for authentication in the URI and be careful to put sensitive information in the URI. Intermediate network components that terminate and newly initiate TLS could log or otherwise store URIs. Consider the consequences, advantages and disadvantages of using sensitive information in the URI and be deliberate about which information is logged, for which purposes and who has access. +

For REST API's that are only used for system-to-system integration on closed networks where all systems are under control of the organisations involved in the exchange, do not put client secrets used for authentication in the URI and be careful to put sensitive information in the URI. Intermediate network components that terminate and newly initiate TLS could log or otherwise store URIs. Consider the consequences, advantages and disadvantages of using sensitive information in the URI and be deliberate about which information is logged, for which purposes and who has access.

@@ -965,7 +965,7 @@ For browser-based applications a subsection is included with additional details System-to-system (sometimes called machine-to-machine) may have a need for the listed specifications as well. Note that different usage patterns may be applicable in contexts with system-to-system clients, see above under Client Authentication. -Realizations may rely on internal usage of HTTP-Headers. +Realisations may rely on internal usage of HTTP-Headers. Information for processing requests and responses can be passed between components, that can have security implications. For instance, this is common practice between a reverse proxy or TLS-offloader and an application server. Additional HTTP headers are used in such example to pass an original IP-address or client certificate. @@ -1022,7 +1022,7 @@ For outbound filtering, the main concern is leaking of information.
-

The headers below are only intended to provide additional security when responses are rendered as HTML. As such, if the API will never return HTML in responses, then these headers may not be necessary. You SHOULD include the headers as part of a defense-in-depth approach if there is any uncertainty about the function of the headers, the types of information that the API returns or information it may return in the future. +

The headers below are only intended to provide additional security when responses are rendered as HTML. As such, if the API will never return HTML in responses, then these headers may not be necessary. You SHOULD include the headers as part of a defence-in-depth approach if there is any uncertainty about the function of the headers, the types of information that the API returns or information it may return in the future. @@ -1065,7 +1065,7 @@ For outbound filtering, the main concern is leaking of information.
Rationale

Different resources can have different uses, as some resources are publicly available whereas others are restricted to several domains. - Modern web browsers use Cross-Origin Resource Sharing (CORS) to minimize the risk associated with cross-site HTTP-requests. + Modern web browsers use Cross-Origin Resource Sharing (CORS) to minimise the risk associated with cross-site HTTP-requests.

By default browsers only allow 'same origin' access to resources. This means that responses on requests to another `[scheme]://[hostname]:[port]` than the `Origin` request header of the initial request will not be processed by the browser. To enable cross-site requests APIs can return a `Access-Control-Allow-Origin` response header. @@ -1103,7 +1103,7 @@ A REST request or response body SHOULD match the intended content type in the he * Requests containing unexpected or missing content type headers MUST be rejected with HTTP response status `406 Not Acceptable` or `415 Unsupported Media Type`. * Accidentally exposing unintended content types MUST be avoided by explicitly defining content types e.g. Jersey (Java) `@consumes("application/json"); @produces("application/json")`. - This avoids XXE-attack vectors for example. + This avoids XML external entity injection attack vectors for example. It is common for REST services to allow multiple response types (e.g. `application/xml` or `application/json`) in which case then the client specifies the preferred order of response types by the Accept header in the request. @@ -1128,7 +1128,7 @@ The following modules are normative for all REST API's.

Rationale
- The [[[ADR-GEO]]] formalizes as set of rules regarding: + The [[[ADR-GEO]]] formalises as set of rules regarding:
  1. How to encode geospatial data in request and response payloads.
  2. How resource collections can be filtered by a given bounding box.
    3. @@ -1150,7 +1150,7 @@ The following modules are normative for all REST API's.
Rationale
- The [[[ADR-signing]]] formalizes as set of rules regarding: + The [[[ADR-signing]]] formalises as set of rules regarding:
  1. How to sign data in request and response payloads.
  2. Which header to specify the signature.
    3. @@ -1171,7 +1171,7 @@ The following modules are normative for all REST API's.
Rationale
- The [[[ADR-encryption]]] formalizes as set of rules regarding: + The [[[ADR-encryption]]] formalises as set of rules regarding:
  1. How to encrypt data in request and response payloads.
  2. The flow of operations between client and server.
    3. diff --git a/sections/introduction.md b/sections/introduction.md index 768bb0e7..a608a4d5 100644 --- a/sections/introduction.md +++ b/sections/introduction.md @@ -2,9 +2,9 @@ ## Goal -More and more governmental organizations offer REST APIs (henceforth abbreviated as APIs), in addition to existing interfaces like SOAP and WFS. These APIs aim to be developer-friendly and easy to implement. While this is a commendable aim, it does not shield a developer from a steep learning curve getting to know every new API, in particular when every individual API is designed using different patterns and conventions. +More and more governmental organisations offer REST APIs (henceforth abbreviated as APIs), in addition to existing interfaces like SOAP and WFS. These APIs aim to be developer-friendly and easy to implement. While this is a commendable aim, it does not shield a developer from a steep learning curve getting to know every new API, in particular when every individual API is designed using different patterns and conventions. -This document aims to describe a widely applicable set of design rules for the unambiguous provisioning of REST APIs. The primary goal is to offer guidance for organizations designing new APIs, with the purpose of increasing developer experience (DX) and interoperability between APIs. Hopefully, many organizations will adopt these design rules in their corporate API strategies and provide feedback about exceptions and additions to subsequently improve these design rules. +This document aims to describe a widely applicable set of design rules for the unambiguous provisioning of REST APIs. The primary goal is to offer guidance for organisations designing new APIs, with the purpose of increasing developer experience (DX) and interoperability between APIs. Hopefully, many organisations will adopt these design rules in their corporate API strategies and provide feedback about exceptions and additions to subsequently improve these design rules. ## Status diff --git a/standaard.dic b/standaard.dic index 6ecc7070..3fa9293f 100644 --- a/standaard.dic +++ b/standaard.dic @@ -1,4 +1,4 @@ -69 +73 0/N 1/N 2/N @@ -12,6 +12,7 @@ RFC/R ISO/I v/V +Aanbeveling ADR backend BCP @@ -38,6 +39,7 @@ NLgov OAuth OAuth2 OData +offloader OGC openapi OpenAPI @@ -56,12 +58,14 @@ SemVer Specref Standaarden Standaardisatie +Strategie subresource timeOfBirth timeOfBirthTimezone timezone timezones URIs +voor WebDAV Werkversie WFS From 4bb4bb2a86a6a7219873f1d3f66c699489dd4e00 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Wed, 1 Jul 2026 13:44:48 +0200 Subject: [PATCH 03/13] Beheer: sta twee extra woorden toe --- standaard.dic | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/standaard.dic b/standaard.dic index 3fa9293f..9434d5b8 100644 --- a/standaard.dic +++ b/standaard.dic @@ -1,4 +1,4 @@ -73 +75 0/N 1/N 2/N @@ -14,6 +14,7 @@ ISO/I v/V Aanbeveling ADR +Authorization backend BCP beheermodel @@ -47,6 +48,7 @@ OPENAPIS Ottowa Overheid OWASP +parseable ReDoc regex REpresentational From c27c74df5b2f5fc0fb80bd031a782fba418fd6af Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Mon, 6 Jul 2026 11:46:43 +0200 Subject: [PATCH 04/13] Beheer: gebruik if-statement om build te fixen --- .github/workflows/build.yml | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index fbd37fe8..c11d0888 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -80,4 +80,8 @@ jobs: - name: Run spellcheck run: | hunspell -l -d en_GB,standaard -H ~/static/index.html | sort -u > spelling.txt - [ -s spelling.txt ] && cat spelling.txt && exit 1 + if [ -s spelling.txt ]; then + echo "De volgende woorden zijn niet toegestaan:" + cat spelling.txt + exit 1 + fi From e5c4a04dd907352ca2024a68e0db76bbf32b59da Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Mon, 6 Jul 2026 14:27:23 +0200 Subject: [PATCH 05/13] Beheer: fetch van GitHub ipv libreoffice --- .github/workflows/build.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index c11d0888..c70aaef4 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -69,8 +69,8 @@ jobs: - name: Install hunspell run: | sudo apt-get install hunspell - wget -O en_GB.aff https://cgit.freedesktop.org/libreoffice/dictionaries/plain/en/en_GB.aff - wget -O en_GB.dic https://cgit.freedesktop.org/libreoffice/dictionaries/plain/en/en_GB.dic + wget -O en_GB.aff https://raw.githubusercontent.com/Logius-standaarden/Automatisering/main/scripts/spellcheck/en_GB.aff + wget -O en_GB.dic https://raw.githubusercontent.com/Logius-standaarden/Automatisering/main/scripts/spellcheck/en_GB.dic - name: Build spellcheck version of standard run: | REPLACEMENT_REGEX="s/spellcheck: false/spellcheck: true/" From b642420dddab20cdab3d2db761ac5a3b2f3bbaf8 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Tue, 7 Jul 2026 13:11:53 +0200 Subject: [PATCH 06/13] Fix logica voor het verwijderen van elementen --- index.html | 2 +- js/config.mjs | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index 684d9472..b2425bcb 100644 --- a/index.html +++ b/index.html @@ -27,7 +27,7 @@

    Linter configuration

    -
    +
    diff --git a/js/config.mjs b/js/config.mjs index bb93460c..7dbcd9d9 100644 --- a/js/config.mjs +++ b/js/config.mjs @@ -60,7 +60,8 @@ function runSpellcheck(config, document) { } document.querySelector('.head').remove(); document.getElementById('references')?.remove(); - for (const element of document.getElementsByClassName('remove-for-spellcheck')) { + const removableElements = [...document.getElementsByClassName('remove-for-spellcheck')]; + for (const element of removableElements) { element.remove(); } } From afa1076b8bb3554edf00eff5aca5457252e1e4f0 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Tue, 7 Jul 2026 14:06:10 +0200 Subject: [PATCH 07/13] Verwijder nog meer elementen --- js/config.mjs | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) diff --git a/js/config.mjs b/js/config.mjs index 7dbcd9d9..dedee5d6 100644 --- a/js/config.mjs +++ b/js/config.mjs @@ -58,11 +58,20 @@ function runSpellcheck(config, document) { if (!config.spellcheck) { return; } - document.querySelector('.head').remove(); - document.getElementById('references')?.remove(); - const removableElements = [...document.getElementsByClassName('remove-for-spellcheck')]; + const removableElements = [ + // Contains author and editor names that don't match any dictionary + document.querySelector('.head'), + // Contain name of standards and their authors, which don't match + // any dictionary + document.getElementById('references'), + ...document.getElementsByClassName('bibref'), + ...document.querySelectorAll('[data-cite]'), + // Any particular part of a standard that is custom and doesn't need + // checking, such as Dutch context in an English standard + ...document.getElementsByClassName('remove-for-spellcheck'), + ]; for (const element of removableElements) { - element.remove(); + element?.remove(); } } From f39f907be70467c8a15a994b50e418c7e25e27d3 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Tue, 7 Jul 2026 14:14:37 +0200 Subject: [PATCH 08/13] Gebruik check configuratie van Automatisering --- .github/workflows/build.yml | 26 +------------------------- standaard.dic | 7 +------ 2 files changed, 2 insertions(+), 31 deletions(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index c70aaef4..aee99fb0 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -13,7 +13,7 @@ jobs: check: needs: build name: Check - uses: Logius-standaarden/Automatisering/.github/workflows/check.yml@main + uses: Logius-standaarden/Automatisering/.github/workflows/check.yml@spellcheck publish: needs: build name: Publish (Logius) @@ -61,27 +61,3 @@ jobs: run: npm install -g @stoplight/spectral-cli - name: Run linter on ${{ matrix.example }} example run: ./examples/${{ matrix.example }}/build-and-check-project.sh - spellchecker: - name: Run spellcheck - runs-on: ubuntu-22.04 - steps: - - uses: actions/checkout@v4 - - name: Install hunspell - run: | - sudo apt-get install hunspell - wget -O en_GB.aff https://raw.githubusercontent.com/Logius-standaarden/Automatisering/main/scripts/spellcheck/en_GB.aff - wget -O en_GB.dic https://raw.githubusercontent.com/Logius-standaarden/Automatisering/main/scripts/spellcheck/en_GB.dic - - name: Build spellcheck version of standard - run: | - REPLACEMENT_REGEX="s/spellcheck: false/spellcheck: true/" - sed -i "$REPLACEMENT_REGEX" js/config.mjs - mkdir ~/static - npx respec --localhost --src index.html --out ~/static/index.html --haltonwarn - - name: Run spellcheck - run: | - hunspell -l -d en_GB,standaard -H ~/static/index.html | sort -u > spelling.txt - if [ -s spelling.txt ]; then - echo "De volgende woorden zijn niet toegestaan:" - cat spelling.txt - exit 1 - fi diff --git a/standaard.dic b/standaard.dic index 9434d5b8..def0b3e1 100644 --- a/standaard.dic +++ b/standaard.dic @@ -1,4 +1,4 @@ -75 +70 0/N 1/N 2/N @@ -13,8 +13,6 @@ RFC/R ISO/I v/V Aanbeveling -ADR -Authorization backend BCP beheermodel @@ -24,9 +22,7 @@ CORS CRS CSRF datetime -Digikoppeling DX -Geonovum json JWE JWS @@ -44,7 +40,6 @@ offloader OGC openapi OpenAPI -OPENAPIS Ottowa Overheid OWASP From 4fb16b8c71a2ce56c7bbc1d7a1c816cc15fc8ded Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Tue, 7 Jul 2026 14:29:19 +0200 Subject: [PATCH 09/13] Ruim dictionary op Hiermee gebruiken we de organisation dictionary --- sections/designRules.md | 6 +++--- standaard.aff | 10 ---------- standaard.dic | 31 +------------------------------ 3 files changed, 4 insertions(+), 43 deletions(-) delete mode 100644 standaard.aff diff --git a/sections/designRules.md b/sections/designRules.md index 5331902f..076cab16 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -281,12 +281,12 @@ Handling date and time is tricky and can lead to confusion among clients. The da

    APIs MUST accept any timezone offset in fields in requests containing a datetime. Fields in responses containing a datetime SHOULD be in UTC (e.g. Z as timezone offset).

    If the original timezone is relevant for users (such as the timezone in which a value is registered), the timezone offset MUST be stored and published as a separate field in [[ISO8601-1]] format time-offset.

    Rationale
    @@ -309,7 +309,7 @@ Handling date and time is tricky and can lead to confusion among clients. The da

    Appending a default or irrelevant time portion to a date field can lead to interpretation errors. A publish date of 2025-07-24T00:00:00Z could for instance be rendered as July 23 in Ireland. A default time of 23:59 would in turn cause date confusion east of Greenwich.

    To prevent conversion errors between storage and API, it is recommended to also store date values without a time portion (i.e. not as a timestamp).

How to test
diff --git a/standaard.aff b/standaard.aff deleted file mode 100644 index a755c8f6..00000000 --- a/standaard.aff +++ /dev/null @@ -1,10 +0,0 @@ -SET UTF-8 - -# Required to make sure that combinations of two are also allowed. -# The default is 3, which wouldn't match for RFC123 -COMPOUNDMIN 1 - -COMPOUNDRULE 3 -COMPOUNDRULE RN* # Allow RFC notation -COMPOUNDRULE IN* # Allow ISO notation -COMPOUNDRULE VN # Allow v1 notation diff --git a/standaard.dic b/standaard.dic index def0b3e1..3aee2596 100644 --- a/standaard.dic +++ b/standaard.dic @@ -1,22 +1,7 @@ -70 -0/N -1/N -2/N -3/N -4/N -5/N -6/N -7/N -8/N -9/N -RFC/R -ISO/I -v/V +41 Aanbeveling backend BCP -beheermodel -birthDate camelCase CORS CRS @@ -26,13 +11,6 @@ DX json JWE JWS -Kennisplatform -Logius -meetingStartTime -NCSC -Nederlandse -NL -NLgov OAuth OAuth2 OData @@ -41,30 +19,23 @@ OGC openapi OpenAPI Ottowa -Overheid OWASP parseable ReDoc regex REpresentational -ReSpec RESTful RPC SameSite SemVer Specref -Standaarden -Standaardisatie Strategie subresource -timeOfBirth -timeOfBirthTimezone timezone timezones URIs voor WebDAV -Werkversie WFS XSS yaml From 776bf812391ba10a94c8c1cfd1ed1599e82959e5 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Tue, 7 Jul 2026 14:37:40 +0200 Subject: [PATCH 10/13] Fix nog wat meer spelling --- .../testcases/date-time/expected-output.txt | 4 +-- media/linter.yaml | 4 +-- sections/designRules.md | 34 +++++++++---------- sections/introduction.md | 2 +- standaard.dic | 12 +------ 5 files changed, 23 insertions(+), 33 deletions(-) diff --git a/linter/testcases/date-time/expected-output.txt b/linter/testcases/date-time/expected-output.txt index 6a3cdc88..7cb4bbd5 100644 --- a/linter/testcases/date-time/expected-output.txt +++ b/linter/testcases/date-time/expected-output.txt @@ -1,13 +1,13 @@ /testcases/date-time/openapi.json - 94:55 error nlgov:date-time-ensure-timezone Use date-time format which includes a timezone paths./resources-with-time-incorrect.get.responses[200].content.application/json.schema.properties.date-time-local.format + 94:55 error nlgov:date-time-ensure-timezone Use date-time format which includes a time zone paths./resources-with-time-incorrect.get.responses[200].content.application/json.schema.properties.date-time-local.format 98:55 error nlgov:use-date-instead-of-datetime Field represents a date and therefore must set 'format' to 'date' paths./resources-with-time-incorrect.get.responses[200].content.application/json.schema.properties.date.format 102:55 error nlgov:use-date-instead-of-datetime Field represents a date and therefore must set 'format' to 'date' paths./resources-with-time-incorrect.get.responses[200].content.application/json.schema.properties.datum.format 106:55 error nlgov:use-date-instead-of-datetime Field represents a date and therefore must set 'format' to 'date' paths./resources-with-time-incorrect.get.responses[200].content.application/json.schema.properties.geboorteDatum.format 110:55 error nlgov:use-date-instead-of-datetime Field represents a date and therefore must set 'format' to 'date' paths./resources-with-time-incorrect.get.responses[200].content.application/json.schema.properties.birthDate.format 114:55 error nlgov:use-date-instead-of-datetime Field represents a date and therefore must set 'format' to 'date' paths./resources-with-time-incorrect.get.responses[200].content.application/json.schema.properties.expiration_date.format 118:55 error nlgov:use-date-instead-of-datetime Field represents a date and therefore must set 'format' to 'date' paths./resources-with-time-incorrect.get.responses[200].content.application/json.schema.properties.expiration_Date.format - 122:55 error nlgov:time-without-timezone Use time-local format without a timezone paths./resources-with-time-incorrect.get.responses[200].content.application/json.schema.properties.timestamp.format + 122:55 error nlgov:time-without-timezone Use time-local format without a time zone paths./resources-with-time-incorrect.get.responses[200].content.application/json.schema.properties.timestamp.format 124:61 error nlgov:specify-format-for-date-and-time Any date field must set 'format' to 'date' paths./resources-with-time-incorrect.get.responses[200].content.application/json.schema.properties.missingFormatDate 218:27 error nlgov:use-date-instead-of-datetime Field represents a date and therefore must set 'format' to 'date' components.schemas.LocalDateTimeIncorrect.format diff --git a/media/linter.yaml b/media/linter.yaml index 15b99e93..7e46f64a 100644 --- a/media/linter.yaml +++ b/media/linter.yaml @@ -232,7 +232,7 @@ rules: nlgov:date-time-ensure-timezone: severity: error given: $..properties[*].format - message: "Use date-time format which includes a timezone" + message: "Use date-time format which includes a time zone" then: function: pattern functionOptions: @@ -241,7 +241,7 @@ rules: nlgov:time-without-timezone: severity: error given: $..properties[*].format - message: "Use time-local format without a timezone" + message: "Use time-local format without a time zone" then: function: pattern functionOptions: diff --git a/sections/designRules.md b/sections/designRules.md index 076cab16..abddf71a 100644 --- a/sections/designRules.md +++ b/sections/designRules.md @@ -154,7 +154,7 @@ https://api.example.org/v1/vergunningen/d285e05c-6b01-45c3-92d8-5e19a946b66f Loop all resource paths in the OpenAPI Description and check that all resource path segments use lowercase letters, digits or hyphens (-). The last path segment is allowed to start with a _. @@ -184,7 +184,7 @@ https://api.example.org/v1/vergunningen/d285e05c-6b01-45c3-92d8-5e19a946b66f
How to test
- Loop all resource paths in the OpenAPI Description and check that all query keys use letters, digits in camelCase. You can use the following regex for each query key: + Loop all resource paths in the OpenAPI Description and check that all query keys use letters, digits in camelCase. You can use the following regular expression for each query key: @@ -219,7 +219,7 @@ https://api.example.org/v1/vergunningen/d285e05c-6b01-45c3-92d8-5e19a946b66f -

A child is born on March 20th 2025 in The Netherlands. If a client sends a request with value 2025-03-20T00:00:00+01:00, timezone conversion would result in 2025-03-19T23:00:00Z. When the client receives this value in a response and incorrectly converts it to a date (by removing the time portion), this would result in 2025-03-19. +

A child is born on March 20th 2025 in The Netherlands. If a client sends a request with value 2025-03-20T00:00:00+01:00, time zone conversion would result in 2025-03-19T23:00:00Z. When the client receives this value in a response and incorrectly converts it to a date (by removing the time portion), this would result in 2025-03-19.

Ambiguous date and time handling can therefore lead to misinterpretation and changes of days/months/years depending on which component performs which incorrect conversion. Clients could incorrectly remove a time portion from a datetime value if the value should have been a date in the first place. By specifying which formats are allowed in which fields, the odds of invalid conversion are reduced. @@ -258,12 +258,12 @@ Handling date and time is tricky and can lead to confusion among clients. The da

Rationale
-

Implementing RFC9557 and ISO 8601 removes ambiguity in date handling between systems and timezones. +

Implementing RFC9557 and ISO 8601 removes ambiguity in date handling between systems and time zones.

RFC9557 is a profile on ISO8601, but is not a strict subset of allowed notations. Practically, to adhere to both, the following limitations MUST be applied to RFC9557:
  • In a field with a date-time value, the date and time component MUST be separated by a "T" in uppercase. -
  • The timezone offset "Z" MUST be uppercase. -
  • "-00:00" MUST NOT be used as timezone offset. +
  • The time zone offset "Z" MUST be uppercase. +
  • "-00:00" MUST NOT be used as time zone offset.
@@ -275,24 +275,24 @@ Handling date and time is tricky and can lead to confusion among clients. The da
-

Allow all timezone offsets in requests and use UTC in responses

+

Allow all time zone offsets in requests and use UTC in responses

Statement
-

APIs MUST accept any timezone offset in fields in requests containing a datetime. Fields in responses containing a datetime SHOULD be in UTC (e.g. Z as timezone offset). +

APIs MUST accept any time zone offset in fields in requests containing a datetime. Fields in responses containing a datetime SHOULD be in UTC (e.g. Z as time zone offset).

-

If the original timezone is relevant for users (such as the timezone in which a value is registered), the timezone offset MUST be stored and published as a separate field in [[ISO8601-1]] format time-offset. +

If the original time zone is relevant for users (such as the time zone in which a value is registered), the time zone offset MUST be stored and published as a separate field in [[ISO8601-1]] format time-offset.

Rationale
-

Allowing clients to use any timezone offset in requests results in flexibility and less complexity for users. Using UTC in responses results in clarity and removes ambiguity. -

While storage formats are outside the scope of this specification, it is recommended to use appropriate temporal data types (such as DATE and TIMESTAMPTZ). Many database systems store these values internally in UTC and handle timezone conversion automatically on read/write. +

Allowing clients to use any time zone offset in requests results in flexibility and less complexity for users. Using UTC in responses results in clarity and removes ambiguity. +

While storage formats are outside the scope of this specification, it is recommended to use appropriate temporal data types (such as DATE and TIMESTAMPTZ). Many database systems store these values internally in UTC and handle time zone conversion automatically on read/write.

@@ -1094,8 +1094,8 @@ These applications can be split into three architectural patterns: * JavaScript applications with a backend; with this class of applications, the backend is the confidential client and should intermediate any interaction, with tokens never ending up in the browser. Effectively, these are not different from regular web-application for this security facet, even though they leverage JavaScript for implementation. * JavaScript applications that share a domain with the API (resource server); these can leverage cookies marked as HTTP-Only, Secure and SameSite. -* JavaScript applications without a backend; these clients are considered public clients, and are potentially more vulnerable to several types of attacks, including Cross-Site Scripting (XSS), Cross Site Request Forgery (CSRF) and OAuth token theft. - In order to support these clients, the Cross-Origin Resource Sharing (CORS) policy mentioned above is critical and MUST be supported. +* JavaScript applications without a backend; these clients are considered public clients, and are potentially more vulnerable to several types of attacks, including Cross-Site Scripting (XSS), Cross Site Request Forgery (CSRF) and OAuth token theft. + In order to support these clients, the Cross-Origin Resource Sharing (CORS) policy mentioned above is critical and MUST be supported. ### Validate content types @@ -1132,7 +1132,7 @@ The following modules are normative for all REST API's.
  1. How to encode geospatial data in request and response payloads.
  2. How resource collections can be filtered by a given bounding box.
    3. -
  3. How to deal with different coordinate systems (CRS).
    4. +
  4. How to deal with different coordinate systems (CRS).
diff --git a/sections/introduction.md b/sections/introduction.md index a608a4d5..9aaabe55 100644 --- a/sections/introduction.md +++ b/sections/introduction.md @@ -4,7 +4,7 @@ More and more governmental organisations offer REST APIs (henceforth abbreviated as APIs), in addition to existing interfaces like SOAP and WFS. These APIs aim to be developer-friendly and easy to implement. While this is a commendable aim, it does not shield a developer from a steep learning curve getting to know every new API, in particular when every individual API is designed using different patterns and conventions. -This document aims to describe a widely applicable set of design rules for the unambiguous provisioning of REST APIs. The primary goal is to offer guidance for organisations designing new APIs, with the purpose of increasing developer experience (DX) and interoperability between APIs. Hopefully, many organisations will adopt these design rules in their corporate API strategies and provide feedback about exceptions and additions to subsequently improve these design rules. +This document aims to describe a widely applicable set of design rules for the unambiguous provisioning of REST APIs. The primary goal is to offer guidance for organisations designing new APIs, with the purpose of increasing developer experience (DX) and interoperability between APIs. Hopefully, many organisations will adopt these design rules in their corporate API strategies and provide feedback about exceptions and additions to subsequently improve these design rules. ## Status diff --git a/standaard.dic b/standaard.dic index 3aee2596..ad52af82 100644 --- a/standaard.dic +++ b/standaard.dic @@ -1,13 +1,8 @@ -41 +31 Aanbeveling backend -BCP camelCase -CORS -CRS -CSRF datetime -DX json JWE JWS @@ -22,21 +17,16 @@ Ottowa OWASP parseable ReDoc -regex REpresentational RESTful RPC SameSite -SemVer Specref Strategie subresource -timezone -timezones URIs voor WebDAV WFS -XSS yaml YAML From 0771667ea51ce5bd572ee52b6f3d10da35506fb0 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Tue, 7 Jul 2026 14:41:31 +0200 Subject: [PATCH 11/13] Voeg CORS weer toe Wordt ook als woord gebruikt verderop --- standaard.dic | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/standaard.dic b/standaard.dic index ad52af82..eecc42a0 100644 --- a/standaard.dic +++ b/standaard.dic @@ -1,7 +1,8 @@ -31 +32 Aanbeveling backend camelCase +CORS datetime json JWE From 9ae4109ff6e27d958bb5720f48b8b66bf726d7f7 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Wed, 8 Jul 2026 14:07:54 +0200 Subject: [PATCH 12/13] Update build.yml --- .github/workflows/build.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index aee99fb0..439a9a9b 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -13,7 +13,7 @@ jobs: check: needs: build name: Check - uses: Logius-standaarden/Automatisering/.github/workflows/check.yml@spellcheck + uses: Logius-standaarden/Automatisering/.github/workflows/check.yml@main publish: needs: build name: Publish (Logius) From a13d6b4c41304457f9b15cfaedea5763719a2b85 Mon Sep 17 00:00:00 2001 From: Tim van der Lippe Date: Thu, 9 Jul 2026 12:53:27 +0200 Subject: [PATCH 13/13] Update config.mjs --- js/config.mjs | 27 ++++----------------------- 1 file changed, 4 insertions(+), 23 deletions(-) diff --git a/js/config.mjs b/js/config.mjs index dedee5d6..bff21374 100644 --- a/js/config.mjs +++ b/js/config.mjs @@ -54,27 +54,6 @@ async function highlightLinterCode(config, document) { }); } -function runSpellcheck(config, document) { - if (!config.spellcheck) { - return; - } - const removableElements = [ - // Contains author and editor names that don't match any dictionary - document.querySelector('.head'), - // Contain name of standards and their authors, which don't match - // any dictionary - document.getElementById('references'), - ...document.getElementsByClassName('bibref'), - ...document.querySelectorAll('[data-cite]'), - // Any particular part of a standard that is custom and doesn't need - // checking, such as Dutch context in an English standard - ...document.getElementsByClassName('remove-for-spellcheck'), - ]; - for (const element of removableElements) { - element?.remove(); - } -} - loadRespecWithConfiguration({ authors: [ { @@ -127,12 +106,14 @@ loadRespecWithConfiguration({ pluralize: true, spellcheck: false, - preProcess: [initializeHighlightJSYaml, fetchLinterConfiguration], + preProcess: [ + initializeHighlightJSYaml, + fetchLinterConfiguration, + ], postProcess: [ generateMermaidFigures, highlightLinterCode, (config, document, utils) => processRuleBlocks(config, document, utils, linterConfiguration), - runSpellcheck, ], localBiblio: {