HTTPSettings.headers in CAMARA_event_common.yaml: remove or constrain?

[hdamker]

Problem description

HTTPSettings.headers in artifacts/common/CAMARA_event_common.yaml (lines 170–178, post-#606) is a map of arbitrary custom HTTP headers attached to outbound notification requests. Four observations:

1. Self-flagged as undiscussed. The field's own description states: "Use/Applicability of this concept has not been discussed in Commonalities. When required by an API project as an option to meet a UC/Requirement, please generate an issue for Commonalities discussion about it."

2. Not endorsed by the Design Guide. §5.8.5 standardizes only x-correlator (explicitly for notification scenarios) and Content-Type. There is no concept of arbitrary custom headers.

3. No CAMARA API actually uses it. Across the API spec files in camaraproject/* that define an HTTPSettings schema, most carry the field verbatim as a placeholder (including the self-flagging note). The one exception surfaced in the checks so far is SessionInsights, which defines HTTPSettings as type: object, description: "No additional settings" — explicitly omitting headers. No API populates the field with examples, constraints, or documented use cases.

4. Triggers two OWASP rules on every API that $refs this schema:

   • owasp:api3:2023-constrained-additionalProperties (no maxProperties cap)
   • owasp:api3:2023-no-additionalProperties (the field's purpose is additionalProperties, so the strict form would break functionality)

Expected behavior

Two options for discussion:

Option A — Remove the headers property entirely. Cleanest fix; honors the field's own "please raise an issue before using" path by acting on the fact that no one has raised one. Leaves HTTPSettings with just method:

    HTTPSettings:
      type: object
      description: HTTP protocol settings for event delivery.
      properties:
        method:
          type: string
          description: The HTTP method to use for sending the message.
          enum:
            - POST

Tradeoff: CAMARA drifts further from the CloudEvents subscriptions 0.1-wip spec, which defines headers as part of HTTP protocol settings.

Option B — Add maxProperties: 50. Keeps the field and preserves CloudEvents alignment, but only mitigates owasp:api3:2023-constrained-additionalProperties. The sibling rule owasp:api3:2023-no-additionalProperties remains unmitigable at the source (custom headers fundamentally need additionalProperties) and would require a rule-side conditional severity downgrade in CAMARA linting tooling.

Alternative solution

None beyond the two options above.

Additional context

Surfaced during CAMARA Validation Framework v1-rc smoke testing on camaraproject/ReleaseTest. Recommendation from the surfacing side: Option A, on the grounds that a field with no endorsed use case and no concrete usage is better removed than retained with a cap.