Add basic CI to lint the common artifacts (yamllint + Spectral)

[hdamker]

Problem description

Commonalities has no CI. There is no .github/workflows/ directory and no GitHub Actions run on pull requests or on pushes to main, so nothing checks the common artifacts before they land.

Because every CAMARA API repository consumes these artifacts (artifacts/common/CAMARA_common.yaml, artifacts/common/CAMARA_event_common.yaml, the API templates, the notification template), an invalid change here has a wide blast radius. A concrete case: the Date schema in CAMARA_common.yaml was merged with indentation that makes the whole file fail to parse as YAML, and it stayed on main undetected. A basic yamllint run on the PR would have caught it. (The immediate breakage is corrected in a separate PR.)

Possible evolution

Add a lightweight CI workflow, triggered on pull_request and push to main, that lints the artifacts. A feasible minimum:

• YAML lint over all artifacts/**/*.yaml. This alone catches the class of error above and applies to every artifact, including the component-only common/*.yaml files — it is the essential baseline.
• Spectral (OpenAPI) lint over the artifacts that are full OpenAPI documents — the API templates under artifacts/api-templates/ (sample-service.yaml, sample-service-subscriptions.yaml, sample-implicit-events.yaml) declare openapi:/paths: and lint cleanly. These templates $ref a large part of the common files, so linting them with references resolved transitively checks the referenced common definitions for OpenAPI consistency. Worth investigating whether that transitive coverage is sufficient: today the templates reference only a subset of the common files (for CAMARA_common.yaml, ~4/26 schemas and ~9/17 responses; Date itself is unreferenced), so template-based resolution does not cover the whole file. The common/*.yaml files are themselves component-only (info + components, no openapi/paths), so the OpenAPI document rules do not apply to them directly and, if checked standalone, would need a scoped ruleset or exclusion.
• optionally gherkin lint over artifacts/testing/*.feature.

To stay consistent with what API repositories are validated against, reuse the CAMARA linting configuration from camaraproject/tooling (the yamllint config and the Spectral ruleset) rather than maintaining a separate copy.

Alternative solution

Rather than a bespoke workflow, consume a lint-only reusable workflow from camaraproject/tooling, which already hosts Spectral and validation workflows. The full CAMARA validation workflow is not directly usable on this repository: it targets consuming API repositories and derives its ruleset and context from a per-API release-plan.yaml, whereas Commonalities is the source of the shared artifacts, not a consuming API. Only the linting subset is proposed here.

Additional context

Open points for the working group / tooling maintainers:

• How to source the config and ruleset — reference a reusable tooling workflow, install the tools and fetch the ruleset, or vendor a minimal config in this repo.
• Which Spectral ruleset version to pin, and whether to scope it so the component-only common/*.yaml files can be checked without the OpenAPI document rules misfiring.
• Whether to add one or two extra template artifacts that reference every definition in the common/*.yaml files, so that Spectral linting the templates (with references resolved) transitively covers the common files completely — closing the partial-coverage gap noted above and avoiding a standalone ruleset for the component-only files.
• Whether to trigger on push to main as well as on pull requests, so a direct edit to main is also gated.

Outlook (beyond the lint subset): for deeper coverage, a regression repository similar to the current ReleaseTest could run the full CAMARA validation workflow on main pushes (PR merges) — the API templates and common files are copied into it and validated as an assembled API. This would need a couple of tweaks: a release-plan.yaml for the copied set, and treating the common files as unreleased "synced" content — i.e. depending on Commonalities main rather than a released tag. That is a larger follow-up; the lint subset above is the immediate, low-cost step.

[hdamker]

Based on a closer investigation, here is a concrete proposal for the first step — essentially what this issue describes, deliberately without the full validation machinery (that remains the outlook).

One self-contained workflow (~70 lines, no changes in tooling needed), triggered on pull_request, push to main, and manually:

• yamllint over artifacts/** — blocking. Would have caught the Date indentation issue (fix: correct Date schema indentation in CAMARA_common.yaml #669) at PR time. Includes Github_templates/: the installed copies in API repositories are checked by nothing, so linting them at the source is the only gate they get.
• Spectral over the full-OAS template files (artifacts/api-templates/, artifacts/notification-templates/) with the current r4 ruleset — blocking on errors; warnings stay visible but don't block. The referenced CAMARA_common.yaml / CAMARA_event_common.yaml definitions are checked transitively.
• gherkin linting (gplint) over artifacts/testing/*.feature — blocking on errors (currently none).

Configuration and pinned tool versions are taken from camaraproject/tooling at the same tag the API repositories use — no duplicated configs. Findings appear as inline annotations on the PR plus the workflow log.

Content corrections ship with the workflow, bringing all three checks to zero errors on current main: the two placeholder-induced Spectral errors are fixed by making the placeholders rule-compliant (/your_webhook_notification_url → kebab-case; a valid-URL externalDocs.url placeholder in sample-service.yaml) instead of adding suppression mechanisms, plus one trailing-space fix in Github_templates.

Follow-up, not blocking: triage the current warnings (Spectral, and gherkin linting — the latter mostly mechanical indentation in the feature templates) as fix-or-document, the same standard API repositories are held to.

Limitations of this first step: it covers the current r4.x line short-term — the ruleset reference is fixed to r4, and coverage of the common files is only transitive through what the templates reference. The next major release cycle, and deeper validation (including the test-repository approach from the outlook of this issue), need further coordination between Commonalities and tooling — to be discussed separately once this first step is in place.