Skip to content

[Changed] Refactor subscription schemas for Commonalities r4.4 and add initialEvent #90

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
eric-murray merged 4 commits into from
Sep 14, 2026
Merged

[Changed] Refactor subscription schemas for Commonalities r4.4 and add initialEvent #90

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
a40ec9e
Update schema names for Commonalities r4.4
eric-murray Sep 14, 2026
70915c4
Sync info.description templates with Commonalities r4.4
eric-murray Sep 14, 2026
db86872
Rename ConfigLocal to Config in YAML schema
eric-murray Sep 14, 2026
177c8fa
Update device reachability status YAML with error notes
eric-murray Sep 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 12 additions & 7 deletions code/API_definitions/device-reachability-status-subscriptions.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
openapi: 3.0.3

Check failure on line 1 in code/API_definitions/device-reachability-status-subscriptions.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

$ref target does not exist 

[S-229] '#/components/schemas/ConfigBase' does not exist @ 'code/common/CAMARA_event_common.yaml' | Suggestion: The $ref points to a JSON pointer that does not exist in the target file. Check the pointer name against the target's components section — a schema renamed or removed in a newer Commonalities release is the usual cause. Fix the reference in this API definition; do not edit code/common/.
info:
title: Device Reachability Status Subscriptions
description: |
Expand Down Expand Up @@ -112,7 +112,7 @@
- provide reachability status update notifications only for a single device in the multi-SIM group, which may not be the intended device.

Possible solutions in such a scenario include:
- Using the authorisation code flow to obtain an access token, which will automatically identify the intended device

Check warning on line 115 in code/API_definitions/device-reachability-status-subscriptions.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

info.description mandatory template content drift 

[P-027] info.description template 'additional-error-responses' has drifted from canonical at paragraph 3.   canonical: Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable C...   found:     Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable C... Re-copy the BEGIN..END block from 'code/common/info-description-templates.yaml'. | Suggestion: Re-copy the BEGIN..END block from code/common/info-description-templates.yaml to replace the drifted content; the message identifies the first differing paragraph.
- Identifying the intended device from a unique identifier for that device, such as its source IP address and port
- Check with the SIM provider whether a unique "secondary" phone number is already associated with each device, and use the secondary phone number to identify the intended device if available.

Expand All @@ -122,7 +122,7 @@

The list of error codes in this API specification is not exhaustive. Therefore the API specification MAY not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`.

Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version.
Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified from the `x-camara-commonalities` field, the changelog and the metadata of the released API version.

As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API.
<!-- CAMARA:MANDATORY:additional-error-responses:END -->
Expand Down Expand Up @@ -400,21 +400,26 @@
$ref: "../common/CAMARA_event_common.yaml#/components/schemas/SubscriptionId"

schemas:
CreateSubscriptionDetailLocal:
CreateSubscriptionDetail:
description: The detail of the requested event subscription.
type: object
properties:
device:
$ref: "../common/CAMARA_common.yaml#/components/schemas/Device"

ConfigLocal:
Config:
description: Config schema allowing for device to be specified as part of subscription detail
allOf:
- $ref: "../common/CAMARA_event_common.yaml#/components/schemas/Config"
- $ref: "../common/CAMARA_event_common.yaml#/components/schemas/ConfigBase"
- type: object
properties:
subscriptionDetail:
$ref: "#/components/schemas/CreateSubscriptionDetailLocal"
$ref: "#/components/schemas/CreateSubscriptionDetail"
initialEvent:
description: |
Set to `true` by API consumer if consumer wants to get an event as soon as the subscription is created and current situation reflects event request.
Example: Consumer requests `reachability-disconnected` events. If API consumer sets initialEvent to true and device is not connected to the mobile network, an event is triggered
type: boolean

ApiEventType:
type: string
Expand Down Expand Up @@ -484,7 +489,7 @@
items:
$ref: "#/components/schemas/ApiEventType"
config:
$ref: "#/components/schemas/ConfigLocal"
$ref: "#/components/schemas/Config"
id:
$ref: "../common/CAMARA_event_common.yaml#/components/schemas/SubscriptionId"
startsAt:
Expand Down Expand Up @@ -561,7 +566,7 @@
items:
$ref: "#/components/schemas/ApiEventType"
config:
$ref: "#/components/schemas/ConfigLocal"
$ref: "#/components/schemas/Config"
discriminator:
propertyName: protocol
mapping:
Expand Down
2 changes: 1 addition & 1 deletion code/API_definitions/device-reachability-status.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@
- return the reachability status for a single device in the multi-SIM group, which may not be the intended device.

Possible solutions in such a scenario include:
- Using the authorisation code flow to obtain an access token, which will automatically identify the intended device

Check warning on line 71 in code/API_definitions/device-reachability-status.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

info.description mandatory template content drift 

[P-027] info.description template 'additional-error-responses' has drifted from canonical at paragraph 3.   canonical: Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable C...   found:     Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable C... Re-copy the BEGIN..END block from 'code/common/info-description-templates.yaml'. | Suggestion: Re-copy the BEGIN..END block from code/common/info-description-templates.yaml to replace the drifted content; the message identifies the first differing paragraph.
- Identifying the intended device from a unique identifier for that device, such as its source IP address and port
- Check with the SIM provider whether a unique "secondary" phone number is already associated with each device, and use the secondary phone number to identify the intended device if available.

Expand All @@ -78,7 +78,7 @@

The list of error codes in this API specification is not exhaustive. Therefore the API specification MAY not document some non-mandatory error statuses as indicated in `CAMARA API Design Guide`.

Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified in the `API Readiness Checklist` document associated to this API version.
Please refer to the `CAMARA_common.yaml` of the Commonalities Release associated to this API version for a complete list of error responses. The applicable Commonalities Release can be identified from the `x-camara-commonalities` field, the changelog and the metadata of the released API version.

As a specific rule, error `501 - NOT_IMPLEMENTED` can be only a possible error response if it is explicitly documented in the API.
<!-- CAMARA:MANDATORY:additional-error-responses:END -->
Expand Down
Loading