Skip to content

fix: Clarify x-entur-metadata.id docs, and relation to versioning #110

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.

Sign up for GitHub

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

Open
egrimstad wants to merge 1 commit into
base: main
Choose a base branch
from
Open

fix: Clarify x-entur-metadata.id docs, and relation to versioning #110

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
14 changes: 9 additions & 5 deletions guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -188,14 +188,17 @@ Example:


#### 2.4.1 Identifying a specification
- :white_check_mark: OpenAPI specifications **SHOULD** use the `id` property in the `x-entur-metadata` extension in the `info` section.
- :white_check_mark: OpenAPI specifications **MUST** use the `id` property in the `x-entur-metadata` extension in the `info` section.
- :white_check_mark: It **MUST** be in lower kebab-case and contain only dashes, digits and letters (a-z).
- :eyes: It **SHOULD NOT** have a `-id` suffix (or prefix).

**Choosing an id**
The id is used to uniquely identify a specification - each id results in an entry in the Developer Portal API catalogue, and an entry in the linting results.
Because of this, the id should not change over time. The current api title (in kebab-case) could be a good id - but, of course, you should not update the id if the title changes in the future.
The id should not have a `-id` suffix (or prefix).
The id is used to uniquely identify a specification. Each id results in an entry in the Developer Portal API catalogue and an entry in the linting results. It is also used to create the URL where the specification is available for download from the Developer Portal.
Because of this, the id should not change over time, and it should be suitable for external use. The current api title (in kebab-case) could be a good id, but you should not update the id if the title changes in the future.

[See also 3.2.2 API spec versioning](#322-api-spec-versioning).


- :white_check_mark: If the id is present, it **MUST** be in lower kebab-case and contain only dashes, digits and letters (a-z).

#### 2.4.2 Specification owner
- :white_check_mark: OpenAPI specifications **SHOULD** use the `owner` property in the `x-entur-metadata` extension in the `info` section.
Expand Down Expand Up @@ -283,6 +286,7 @@ Here, only 1 specification will be shown on the Developer Portal, which is a com

#### 3.2.2 API Spec Versioning
API spec versioning is done automatically when [publishing the spec](https://github.com/entur/gha-api/blob/main/README-publish.md).
If the published specification has an [Entur id](#241-identifying-a-specification) that has been published before, it will be considered a new version of the same spec.
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,
Expand Down
Loading