diff --git a/.spectral.yml b/.spectral.yml index f58a7c8..87651c6 100644 --- a/.spectral.yml +++ b/.spectral.yml @@ -362,16 +362,6 @@ rules: # 3.2 Versioning # ------------------------------------------------------------------------- - entur-info-version: - message: "The OpenAPI info.version MUST be a valid semantic version (MAJOR.MINOR.PATCH format, e.g. 1.0.0)." - documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#32-versioning" - severity: error - given: $ - then: - field: info.version - function: pattern - functionOptions: - match: "^(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*)$" # ------------------------------------------------------------------------- # 3.3 Backward Compatibility - Not directly lintable @@ -519,7 +509,7 @@ rules: entur-language-headers: message: "Accept-Language and Content-Language should follow IETF BCP 47. And macrolanguages like 'no' should not be used - use 'nb' or 'nn'." - documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#41-language--spelling" + documentationUrl: "https://github.com/entur/api-guidelines/blob/main/guidelines.md#51-language--spelling" severity: error given: - $..parameters[?(@.in=='header' && @.name=='Accept-Language')].example diff --git a/guidelines.md b/guidelines.md index 8c4c8c8..f4fa3f4 100644 --- a/guidelines.md +++ b/guidelines.md @@ -282,7 +282,11 @@ Here, only 1 specification will be shown on the Developer Portal, which is a com - Example: `https://api.entur.io/sales/v1/orders?distributionChannelId=1` #### 3.2.2 API Spec Versioning -- :white_check_mark: The info.version field **MUST** be set and follow the semver format (e.g. `1.0.0`). This field can be used to communicate changes in the api, together with a changelog. +API spec versioning is done automatically when [publishing the spec](https://github.com/entur/gha-api/blob/main/README-publish.md). +The version is set based on the [CalVer](https://calver.org/) versioning convention, and uses the format YYYY.MM.MICRO. When the spec is +published, the current year and month is used, and MICRO is set to "00". If a version already exists for the given year and month, "01" is used (and so on). +If the published spec is equal to the current spec, no new version is created. Because versioning is done automatically, the value in `info.version` is ignored, +but must be set in order for linting to pass, therefore a placeholder value like `1.0.0` may be used. ### 3.3 Backward Compatibility - :eyes: You **MUST** not remove or modify existing fields or endpoints