Validation errors/warnings from #273 (/retrieve-age-band) landed on main unsurfaced

[hdamker]

Problem description

No CAMARA Validation check run exists for #273's head commit (292805c) — zero check-runs, check-suites, or workflow-runs are recorded for it, even though the CAMARA Validation workflow has no path filter and ran normally on other PRs targeting main in the same window (e.g. fix271, fix267). So none of the findings below were ever surfaced for review before /retrieve-age-band landed on main. Running validation locally against the current main (commit e4699aa) confirms the following issues in code/API_definitions/sim-swap.yaml, all traceable to the /retrieve-age-band addition:

Errors

• Y-012 (yamllint) — trailing whitespace: lines 15, 72, 255.
• Y-009 (yamllint) — wrong indentation (expected 6, found 10) on the AGEBAND_2LEGS example: line 728. The block's summary/value/phoneNumber lines are indented 10 spaces instead of the 6 spaces every sibling example uses.
• Y-011 (yamllint) — no newline at end of file: line 749.
• invalid-ref — #/components/parameters/x-correlator does not exist: line 288, the new /retrieve-age-band operation's parameter list.
• invalid-ref — #/components/headers/x-correlator does not exist: line 307, the same operation's 200 response header.
• invalid-ref — #/components/schemas/ErrorInfo does not exist: line 494 (and the same pattern repeats in the Generic401/403/404/422/429/501 response definitions added alongside it).

The x-correlator and ErrorInfo refs point at local #/components/... paths that don't exist anywhere in this file's own components: section. Every other operation in this spec (/retrieve-date, /check) correctly imports these from the shared file instead: ../common/CAMARA_common.yaml#/components/parameters/x-correlator, .../headers/x-correlator, and (for error schemas) the equivalent ErrorInfo ref. The new operation and its Generic4xx/5xx response block use the old local-ref pattern instead, so the refs dangle.

Warnings

• S-039 — line 287: "Operation must document the x-correlator request header parameter" (downstream symptom of the broken ref above).
• S-009 — line 335: "Parameter description is missing or empty" (Spectral resolves this to the components: node itself, also a downstream symptom of the same broken ref chain).
• S-310 — line 369: the new SimSwapAgeBand integer schema doesn't specify format (int32/int64).
• S-311 — line 369: the same schema doesn't specify minimum/maximum. Note the enum (1–17, 111) doesn't substitute for either: per Design Guide §2.2, enum is an accepted alternative to maxLength for string types, but the integer rule ("format and range... MUST be specified") carries no equivalent enum exception.
• S-011 — missing description (only summary given) on 7 new components: CreateSimSwapAgeBand (line 479) and examples AGEBAND_2LEGS (727), AGEBAND_3LEGS (731), AGEBAND_RECENT (734), AGEBAND_WITHIN_72H (738), AGEBAND_NO_SWAP (742), AGEBAND_LONG_TERM (746). Every pre-existing example in this file carries both fields.

Hints

• S-021 — line 144: tag name Retrieve SIM swap age band is not Title Case, inconsistent with the sibling tags Retrieve SIM Swap Date and Check SIM Swap.
• P-027 — the mandatory additional-error-responses info.description template block (delimited by <!-- CAMARA:MANDATORY:additional-error-responses:BEGIN/END -->) now has 7 paragraphs where the canonical template has 4. The three /retrieve-age-band-specific paragraphs (the 501/422/transient-failure rules) were inserted inside the mandatory markers instead of before them, so the block no longer matches the canonical text in code/common/info-description-templates.yaml. See faq.md#p-026-p-027-info-description-mandatory.

Expected behavior

• Fix the broken x-correlator/ErrorInfo refs by switching the new operation and its Generic* responses to the same external ../common/CAMARA_common.yaml#/components/... pattern the rest of the file uses.
• Clean up the yamllint errors (trailing whitespace, AGEBAND_2LEGS indentation, missing trailing newline).
• Move the /retrieve-age-band-specific error-handling prose outside the additional-error-responses mandatory markers so the block matches the canonical template.
• Add format/minimum/maximum to the SimSwapAgeBand schema, description fields to the new schema/examples, and align the new tag's casing with its siblings.

Alternative solution

N/A — these are conformance fixes, not a design change.

Additional context

Findings above come from a local run of the CAMARA Validation orchestrator (Spectral + yamllint + Python checks) against main at e4699aa, restricted to the surface actually changed by #273 (confirmed via git blame/diff against the PR's own commits).

[hdamker]

@camaraproject/sim-swap_codeowners Most probably reason that the validation never run on this PR is that it was a fork PR from a "First time contributor". There was probably a button shown for codeowners to "Approve the workflow run" or similar. Please ensure that PRs have a passed validation run, in this case only EasyCLA was checked.