Validate mandatory info.description content via a canonical Commonalities file

[hdamker]

Problem description

CAMARA APIs include several mandatory text blocks in info.description originating from the API Design Guide (§3.2.3 additional error responses; §3.2.4 request body strictness, new in Commonalities#634; Appendix A identifier-from-access-token) and the ICM profile (authorization and authentication). Each API specification today copy-pastes these texts into its own info.description. Every change to a mandatory section produces a parallel copy-paste update across 60+ API specifications.

Commonalities#634 adds the §3.2.4 block and surfaces this cost again. A scalable mechanism is needed before more mandatory text is added.

Possible evolution

A canonical content file in Commonalities, distributed to each API repository through the existing code/common/ cache-common synchronisation, paired with a delimited-block convention in info.description and a small set of Spectral rules in the validation framework. Authoritative prose in the API Design Guide and the ICM profile is unchanged; the canonical file mirrors the same text in a machine-readable form.

Detailed design lands in camaraproject/tooling under validation/docs/CAMARA-Validation-Framework-Info-Description-Design.md (PR linked below). Activation target: Commonalities r4.3 ruleset.

Alternative solution

Bundling-time placeholder expansion (a $ref-like marker in info.description that the bundling step expands into the canonical text) was considered and rejected — it hides the mandatory content from contributors and reviewers at the source-spec level.

Additional context

Planned steps:

• Tooling: design document under validation/docs/
• Commonalities: canonical file at artifacts/common/info-description-templates.yaml + artifacts/api-templates/sample-*.yaml wrapping + disclaimer; depends on Commonalities#634 merging
• Tooling: Spectral rule implementation + activation in .spectral-r4.3.yaml
• Tooling: codeowner-facing how-to under documentation/validation/
• ReleaseTest: pilot PR ahead of the r4.3 cut, on a tooling working branch
• ReleaseTest: regression-fixtures branch with deliberate variants (missing template, content drift, duplicate template name, folded YAML scalar)

This issue serves as the umbrella for the planned PRs.

[hdamker]

I investigated the observed problems with the info.description errors in r4.3 sync PRs. The short version is that the current severity configuration already matches the intended bootstrap behavior: P-026/P-027 are hints for alpha APIs, warnings for rc APIs, and errors for public APIs.

The blocking info.description failures I found were caused by APIs already marked public, not by the rc path being too strict.

Repository	Initial r4.3 sync PR	Target/API status from diagnostics	Validation result	info.description relation
ClickToDial	camaraproject/ClickToDial#104	public-release / public	Failed: 3 blocking errors	Yes. All 3 errors were P-026 missing mandatory info.description blocks.
NetworkSliceBooking	camaraproject/NetworkSliceBooking#128	public-release / public for both APIs	Failed: 6 blocking errors plus 2 hints	Yes. All 6 errors were P-026 missing mandatory info.description blocks. Follow-up sync PR camaraproject/NetworkSliceBooking#132 later passed.
ConnectivityInsights	camaraproject/ConnectivityInsights#190	pre-release-rc, but both APIs already public	Failed: 8 blocking errors	Yes, but not only. 6 errors were P-026 missing mandatory info.description blocks; 2 errors were S-016 schema type findings.
QoSBooking	camaraproject/QoSBooking#93	pre-release-alpha / alpha for both APIs	Failed: 2 blocking errors	No blocking info.description issue. P-026 appeared only as hints; the blockers were 2 S-016 CloudEvent schema type findings.
ConsentManagement	camaraproject/ConsentManagement#28	pre-release-rc	Passed	No errors.
DeviceRoamingStatus	camaraproject/DeviceRoamingStatus#75	pre-release-rc	Passed	No errors.
EdgeApplicationManagement	camaraproject/EdgeApplicationManagement#30	pre-release-alpha	Passed	No errors.
NumberVerification	camaraproject/NumberVerification#233	No target release type in the local r4.3 inventory / r4.3 sync PR	Passed	No errors.
ReleaseTest	camaraproject/ReleaseTest#183	pre-release-alpha	Passed	No errors.

Conclusion: I do not see a need to change the validation-rule severity for this. The important operational guidance is that repositories preparing an rc release should keep the affected APIs at target_api_status: rc until the r4.3 sync is merged and the info.description blocks are updated. If an API is already marked public, P-026/P-027 are intentionally strict, fail the validation and would block the release.

For ConnectivityInsights specifically, the unblock path is split into smaller PRs:

1. fix(api): add missing schema object types ConnectivityInsights#193 clears the two S-016 blockers.
2. fix(release-plan): set Connectivity Insights API status to rc ConnectivityInsights#192 changes both API statuses to rc.
3. Sync common files from Commonalities r4.3 ConnectivityInsights#190 can then be resynced with main and merged as the r4.3 sync PR.

[hdamker]

Following the above findings, the remaining user-facing documentation topic is now covered by camaraproject/tooling#309.

That PR adds a CAMARA Validation FAQ entry for P-026/P-027 mandatory info.description findings, including what codeowners should do for hints, warnings, and errors during the r4.3 adoption flow.

[hdamker]

All done here, camaraproject/tooling#309 now also included in v1-rc