Skip to content

Fix editorial issues in security-relevant parts of Event Subscription and Notification Guide - #725

Open
rartych wants to merge 1 commit into
camaraproject:mainfrom
rartych:fix-719-editorial-security-guide
Open

rartych wants to merge 1 commit into
camaraproject:mainfrom
rartych:fix-719-editorial-security-guide

Conversation

@rartych

@rartych rartych commented Oct 12, 2026

Copy link
Copy Markdown
Contributor

What type of PR is this?

  • correction

What this PR does / why we need it:

This PR fixes four editorial issues in the security-relevant parts of CAMARA-API-Event-Subscription-and-Notification-Guide.md:

  • §4.3 Notifications Security Considerations: The normative statement that the Notification Sender MUST follow TLS requirements pointed to a non-existent "10.2 Security Implementation" section. It now links to CAMARA API Design Guide §6.1 Good Practices for Securing REST APIs, which contains the actual HTTPS/TLS requirement.
  • §2.2.3 Subscriptions Data Model: The sink attribute's "security considerations" link was broken (43#notifications-security-considerations, a stray relative path) and now correctly resolves to #43-notifications-security-considerations within the same document.
  • §3.7 Notification Examples: The subscription-ended example used type: "org.camaraproject.api.device-roaming-subscriptions.v1.subscription-ended", which includes an extra .api segment that violates the mandated org.camaraproject.<api-name>.<event-version>.<event-name> pattern. The extra segment has been removed.
  • §3.7 Notification Examples: Both notification examples used numeric id values (123654, 123658), while the CloudEvent.id schema in CAMARA_event_common.yaml defines id as a string. Both values are now quoted strings.

Which issue(s) this PR fixes:

Fixes #719

Does this PR introduce a breaking change?

  • Yes
  • No

Special notes for reviewers:

Changelog input

 release-note
Fixed editorial issues in security-relevant parts of CAMARA API Event Subscription and Notification Guide: broken §4.3 TLS reference, broken `sink` security-considerations link, extra `.api` segment in `subscription-ended` example `type`, and numeric `id` values corrected to strings in notification examples.

… and Notification Guide (camaraproject#719)

- Fix dangling TLS reference in 4.3: point to CAMARA API Design Guide
  6.1 Good Practices for Securing REST APIs instead of non-existent
  10.2 Security Implementation section.
- Fix broken sink security-considerations link in 2.2.3 Subscriptions
  Data Model (43#... -> camaraproject#43-...).
- Remove extra .api segment from subscription-ended example type value
  in 3.7 Notification Examples to match the mandated
  org.camaraproject.<api-name>.<event-version>.<event-name> pattern.
- Quote numeric id values as strings in 3.7 Notification Examples to
  match the CloudEvent.id schema (type: string).

@bigludo7 bigludo7 left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@PedroDiez PedroDiez left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Editorial fixes in the security-relevant parts of the guide

4 participants