From 1310ee79c418f4bdb9225a99c44200a658b03869 Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Thu, 16 Jul 2026 12:14:52 +0200 Subject: [PATCH 1/3] fix: resolve error-level lint findings in artifacts Kebab-case webhook path and a syntactically valid externalDocs.url placeholder resolve the two error-level Spectral findings; the issue-template trailing space resolves the yamllint finding. Rule-compliant placeholders instead of suppression rules, per the first-step scope on #668. The externalDocs.url placeholder is harmonized to APIRepositoryName (PascalCase, like real repository names) across all three API templates. --- .../Github_templates/.github/ISSUE_TEMPLATE/config.yml | 2 +- artifacts/api-templates/sample-implicit-events.yaml | 4 ++-- artifacts/api-templates/sample-service-subscriptions.yaml | 4 ++-- artifacts/api-templates/sample-service.yaml | 4 ++-- artifacts/notification-templates/sample-notification.yaml | 6 +++--- 5 files changed, 10 insertions(+), 10 deletions(-) diff --git a/artifacts/Github_templates/.github/ISSUE_TEMPLATE/config.yml b/artifacts/Github_templates/.github/ISSUE_TEMPLATE/config.yml index 0067a970..d94493b5 100644 --- a/artifacts/Github_templates/.github/ISSUE_TEMPLATE/config.yml +++ b/artifacts/Github_templates/.github/ISSUE_TEMPLATE/config.yml @@ -1,6 +1,6 @@ blank_issues_enabled: true contact_links: - - name: 🗣 Subproject discussions + - name: 🗣 Subproject discussions url: https://github.com/camaraproject/Commonalities/discussions about: Please ask and answer questions here. - name: 📖 CAMARA API Design Guidelines diff --git a/artifacts/api-templates/sample-implicit-events.yaml b/artifacts/api-templates/sample-implicit-events.yaml index 10079f74..3e14b1d9 100644 --- a/artifacts/api-templates/sample-implicit-events.yaml +++ b/artifacts/api-templates/sample-implicit-events.yaml @@ -86,8 +86,8 @@ info: externalDocs: description: Product documentation at CAMARA - url: https://github.com/camaraproject/apiRepository - # {apiRepository} MUST be replaced by the CAMARA Subproject Repository name where the API design based on this template is hosted. + url: https://github.com/camaraproject/APIRepositoryName + # APIRepositoryName MUST be replaced by the CAMARA Subproject Repository name where the API design based on this template is hosted. servers: - url: "{apiRoot}/sample-implicit-events/vwip" variables: diff --git a/artifacts/api-templates/sample-service-subscriptions.yaml b/artifacts/api-templates/sample-service-subscriptions.yaml index e56aff1d..8ac7e973 100644 --- a/artifacts/api-templates/sample-service-subscriptions.yaml +++ b/artifacts/api-templates/sample-service-subscriptions.yaml @@ -52,8 +52,8 @@ info: externalDocs: description: Product documentation at CAMARA - url: https://github.com/camaraproject/apiRepository - # {apiRepository} MUST be replaced by the CAMARA Subproject Repository name where the API design based on this template is hosted. + url: https://github.com/camaraproject/APIRepositoryName + # APIRepositoryName MUST be replaced by the CAMARA Subproject Repository name where the API design based on this template is hosted. servers: - url: "{apiRoot}/sample-service-subscriptions/vwip" variables: diff --git a/artifacts/api-templates/sample-service.yaml b/artifacts/api-templates/sample-service.yaml index 52b06953..53e62198 100644 --- a/artifacts/api-templates/sample-service.yaml +++ b/artifacts/api-templates/sample-service.yaml @@ -70,8 +70,8 @@ info: x-camara-commonalities: wip externalDocs: description: Product documentation at CAMARA - url: https://github.com/camaraproject/{apiRepository} - # {apiRepository} MUST be replaced by the CAMARA API Repository name where the API specification is hosted. + url: https://github.com/camaraproject/APIRepositoryName + # APIRepositoryName MUST be replaced by the CAMARA API Repository name where the API specification is hosted. servers: - url: "{apiRoot}/sample-service/vwip" variables: diff --git a/artifacts/notification-templates/sample-notification.yaml b/artifacts/notification-templates/sample-notification.yaml index b1eda169..d90c362e 100644 --- a/artifacts/notification-templates/sample-notification.yaml +++ b/artifacts/notification-templates/sample-notification.yaml @@ -33,17 +33,17 @@ security: - {} paths: - /your_webhook_notification_url: + /your-webhook-notification-url: post: tags: - CAMARA Cloud Event summary: Cloud Event notification endpoint to notify consumer that statement of fact had occurred description: | INFORMATIVE ENDPOINT: The value of this endpoint is freely declared by each client app by means of resource-based - subscription or instance-based subscription. `/your_webhook_notification_url` is + subscription or instance-based subscription. `/your-webhook-notification-url` is just a convention naming referring to an absolute URL, indeed the one indicated by API client in the triggering of the procedure (resource-based or instance-based). In this way, it represents an absolute - URL, i.e.: notifications won't be sent to `/event-notification/vX/your_webhook_notification_url`. + URL, i.e.: notifications won't be sent to `/event-notification/vX/your-webhook-notification-url`. operationId: sendEvent parameters: - $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator" From ef7ce5f6730c894f1adaf2adb61b9b6ab97e861d Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Thu, 16 Jul 2026 12:14:52 +0200 Subject: [PATCH 2/3] ci: add Artifacts Lint workflow (yamllint, Spectral, gplint) Lint configurations and tool versions come from camaraproject/tooling at the v1-rc pin API repositories use for CAMARA Validation. All three checks gate at error level; first step on #668. --- .github/workflows/artifacts-lint.yml | 124 +++++++++++++++++++++++++++ artifacts/linting_rules/README.md | 17 ++++ 2 files changed, 141 insertions(+) create mode 100644 .github/workflows/artifacts-lint.yml diff --git a/.github/workflows/artifacts-lint.yml b/.github/workflows/artifacts-lint.yml new file mode 100644 index 00000000..9b39586e --- /dev/null +++ b/.github/workflows/artifacts-lint.yml @@ -0,0 +1,124 @@ +# ========================================================================================= +# CAMARA Commonalities - Artifacts Lint +# +# Lints the distributed artifacts (artifacts/**) so broken content is caught at +# PR time instead of after a downstream sync into an API repository: +# 1. yamllint over all YAML files in artifacts/ - including Github_templates/, +# whose installed copies in API repositories are not checked there. +# 2. Spectral over the full-OpenAPI templates (api-templates/, +# notification-templates/) with the CAMARA ruleset of the release line +# under development; $ref resolution transitively lints the referenced +# common definitions (artifacts/common/). +# 3. gplint over the Gherkin feature templates (artifacts/testing/). +# +# All three checks gate at error level; warnings and hints are reported but do +# not block. Lint configurations and tool versions are taken from +# camaraproject/tooling at the same pinned ref API repositories use for CAMARA +# Validation, so findings here match the validation toolchain - no local +# copies that could drift. +# +# The Spectral ruleset is pinned to the release line main currently targets +# (r4.x); update SPECTRAL_RULESET when main starts targeting the next line. +# +# Changelog: +# - 2026-07-16: Initial version (yamllint + Spectral + gplint) +# +# SEE ALSO: artifacts/linting_rules/README.md +# ========================================================================================= + +name: Artifacts Lint + +on: + pull_request: + push: + branches: [main] + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: artifacts-lint-${{ github.ref }} + cancel-in-progress: true + +env: + TOOLING_REF: v1-rc + SPECTRAL_RULESET: .spectral-r4.yaml + PYTHON_VERSION: "3.14" + NODE_VERSION: "24" + +jobs: + lint: + name: Lint artifacts + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v7 + + # Lint configurations and dependency pins from tooling at the pinned ref. + - name: Checkout tooling lint configs + uses: actions/checkout@v7 + with: + repository: camaraproject/tooling + ref: ${{ env.TOOLING_REF }} + path: .tooling + sparse-checkout: | + linting/config/ + requirements.txt + validation/package.json + validation/package-lock.json + validation/.npmrc + sparse-checkout-cone-mode: false + + - name: Setup Python + uses: actions/setup-python@v6 + with: + python-version: ${{ env.PYTHON_VERSION }} + + - name: Setup Node + uses: actions/setup-node@v6 + with: + node-version: ${{ env.NODE_VERSION }} + + - name: Install yamllint (tooling-pinned version) + run: pip install --quiet -r .tooling/requirements.txt + + - name: Install Spectral and gplint (tooling-pinned versions) + run: npm ci --ignore-scripts + working-directory: .tooling/validation + + # The three checks run independently of each other's outcome, so a PR + # touching several artifact types reports all findings in one run. + - name: yamllint over artifacts/ + if: ${{ !cancelled() }} + run: yamllint -c .tooling/linting/config/.yamllint.yaml -f github artifacts/ + + # Findings in transitively referenced common files carry their real + # artifacts/common/** paths. The github-actions output goes to a file + # first so annotations survive the non-zero exit of the lint command. + - name: Spectral over API and notification templates + if: ${{ !cancelled() }} + env: + NODE_PATH: ${{ github.workspace }}/.tooling/validation/node_modules + run: | + export PATH="${{ github.workspace }}/.tooling/validation/node_modules/.bin:${PATH}" + status=0 + spectral lint \ + --ruleset ".tooling/linting/config/${SPECTRAL_RULESET}" \ + --fail-severity error \ + -f pretty -f github-actions \ + -o.pretty /dev/stdout \ + -o.github-actions "${RUNNER_TEMP}/spectral-annotations.log" \ + artifacts/api-templates/*.yaml artifacts/notification-templates/*.yaml \ + || status=$? + cat "${RUNNER_TEMP}/spectral-annotations.log" + exit $status + + # gplint exits non-zero only on error-level findings; warnings are + # reported in the log. + - name: gplint over feature templates + if: ${{ !cancelled() }} + run: | + export PATH="${{ github.workspace }}/.tooling/validation/node_modules/.bin:${PATH}" + gplint --config .tooling/linting/config/.gplintrc artifacts/testing/*.feature diff --git a/artifacts/linting_rules/README.md b/artifacts/linting_rules/README.md index 36a74013..c70cb7b1 100644 --- a/artifacts/linting_rules/README.md +++ b/artifacts/linting_rules/README.md @@ -1 +1,18 @@ Linting rules and their usage documentation are maintained within CAMARA [tooling repository](https://github.com/camaraproject/tooling/tree/main/linting). + +## Linting of the artifacts in this repository + +The [Artifacts Lint workflow](../../.github/workflows/artifacts-lint.yml) runs on every pull request and on pushes to `main`: + +- **yamllint** over all YAML files in `artifacts/` (including `Github_templates/`, whose installed copies in API repositories are not checked there) +- **Spectral** over the full-OpenAPI templates (`api-templates/`, `notification-templates/`) with the CAMARA ruleset of the release line under development; `$ref` resolution transitively checks the referenced definitions in `common/` +- **gplint** over the Gherkin feature templates (`testing/`) + +Lint configurations and tool versions are taken from the [tooling repository](https://github.com/camaraproject/tooling/tree/main/linting/config) at the same pinned ref API repositories use for CAMARA Validation, so findings here match the validation toolchain. + +All three checks block only on error-level findings; warnings and hints are reported in the workflow log but do not fail the check. + +### When a check fails + +- The finding points at a real problem in the changed artifact (parse error, violated convention): fix the content. +- The artifact is intentional and the rule itself no longer matches a Commonalities convention: the rules live in the tooling repository, so open a paired change there — the tooling change merges first, then the change in this repository lints green. From bd6b7481b27913967a08ca746ec6b7a857c73b9a Mon Sep 17 00:00:00 2001 From: Herbert Damker <52109189+hdamker@users.noreply.github.com> Date: Thu, 16 Jul 2026 12:47:12 +0200 Subject: [PATCH 3/3] test: deliberate lint errors for red-path check (do not merge) --- artifacts/common/CAMARA_event_common.yaml | 2 +- artifacts/notification-templates/sample-notification.yaml | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/artifacts/common/CAMARA_event_common.yaml b/artifacts/common/CAMARA_event_common.yaml index 6e2aaf14..070c8308 100644 --- a/artifacts/common/CAMARA_event_common.yaml +++ b/artifacts/common/CAMARA_event_common.yaml @@ -1,6 +1,6 @@ info: title: CAMARA common event and subscription data types - description: | + description: | Common data types for CAMARA event notification and subscription management. This file contains Commonalities-owned schemas that are identical across all CAMARA APIs supporting event notifications and/or explicit subscriptions. diff --git a/artifacts/notification-templates/sample-notification.yaml b/artifacts/notification-templates/sample-notification.yaml index d90c362e..bda829ad 100644 --- a/artifacts/notification-templates/sample-notification.yaml +++ b/artifacts/notification-templates/sample-notification.yaml @@ -33,7 +33,7 @@ security: - {} paths: - /your-webhook-notification-url: + /your_webhook_notification_url: post: tags: - CAMARA Cloud Event