Configurable Belgif REST guidelines version

[jpraet]

The Belgif REST guidelines keep evolving, and sometimes new rules are added that will break compliance of existing APIs, and it is often not worth it to update those, especially when they can be potentially breaking for the consumers of the API.

I think it would be useful if we could explicitly specify the Belgif REST guidelines version that an API aims to be compliant with:

openapi: 3.0.3
info:
  title: foreignLegalEntity
  x-belgif-guidelines-version: 2025-06-16

The rest-guide-validator would then only apply the rules for that version. This seems less cumbersome than adding x-ignore-rules all over the place.

Thoughts?

[pvdbosch]

I guess this is about the same as sticking with an older version of the validator, except for any possible changes in output format and config format in the validator.
This would have quite an impact on the implementation complexity. Rules might not be updated in the validator in the same order as the guide, and rule implementations may be changed for updated guidelines.

The disadvantage of sticking to an old ruleset, is that it doesn't encourage any new changes to the API to be compliant with the latest guidelines; nor encourages changes that can be done in a backwards-compatible way (e.g. schema renaming, detection of bugs like missing 'required' on a requestBody).

Ideally there'd be some automated way to add the x-ignore-rules after updating the validator (e.g. Renovate's postUpgradeTasks), but I'm not sure if that is feasible.

[jpraet]

There are these drawbacks to pinning the validator plugin on an older version:

• the plugin version and configuration might be managed globally in a company pom.xml (it is the case for CBSS)
• you would miss out on any bugfixes
• what if our customer wants to validate the contract we give them: they would also need to use an old version of the validator, and we would need to tell them which version

If supporting configurable Belgif guideline version is not feasible, maybe a way to define global x-ignore-rules could also help:
#118

[pvdbosch]

I wouldn't like to allow a global ignore, because new changes (e.g. new operations, new schemas) in APIs would escape validation.
Maybe instead, we could add a command to add x-ignore-rules in bulk for all detected violations in an OpenAPI?

[jpraet]

At CBSS the latest version of rest-guide-validator is integrated into the build pipeline. We validate our own APIs as well as (optionally) the supplier APIs we integrate with. Even though we only have a limited amount of REST APIs at this point, the breakage due to the many violations against the new id-name rule caused us quite some headaches.

So I wonder how Smals and eHealth manage evolutions in the REST guidelines:

• do you also have the rest-guide-validator integrated into your build pipeline? or is it a manual process?
• do you systematically either update existing APIs to conform to the new / updated rules or add x-ignore-rules?

/cc @VirginieHayot @pvdbosch @wsalembi

[pvdbosch]

For us:

• validation needs to be successful when validating the REST API (each time there are significant changes)
• there are two builds of the same OpenAPIs: one centrally managed, one within the application build managed by the dev team
  • the centrally managed one has validator on non-blocking
  • config of the application build varies per team. Renovate rules don't automerge minor version updates by default (but do create a PR), patch updates are set to automerge.