Skip to content

QoS B: Alignment with Commonalities r4.3 #97

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
Masa8106 merged 14 commits into from
Jul 1, 2026
Merged

QoS B: Alignment with Commonalities r4.3 #97

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
d639b69
Alignment with Commonalities #563
Masa8106 Mar 5, 2026
a6d23cf
Alignment with Commonalities #576
Masa8106 Mar 5, 2026
f4afab6
Alignment with Commonalities #580
Masa8106 Mar 5, 2026
8078cbd
Alignment with Commonalities #582
Masa8106 Mar 5, 2026
972f301
Corrections
Masa8106 Mar 5, 2026
1c7f7cf
Corrections2
Masa8106 Mar 5, 2026
cdf5207
Addressing limit restrictions
Masa8106 Jun 12, 2026
3dbe498
Addressing other warnings
Masa8106 Jun 12, 2026
a8691fc
Merge branch 'main' into Masa8106-align-comm-r4.3
Masa8106 Jun 19, 2026
bfd4bec
Update code/API_definitions/qos-booking.yaml
Masa8106 Jun 30, 2026
900bd29
Update code/API_definitions/qos-booking.yaml
Masa8106 Jun 30, 2026
3e2d0de
Update code/API_definitions/qos-booking.yaml
Masa8106 Jun 30, 2026
75fc5c5
Merge main into Masa8106-align-comm-r4.3 to resolve conflicts
jlurien Jul 1, 2026
871ccfc
Refine $.device assertion wording in getBookingById and retrieveBooki…
jlurien Jul 1, 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
99 changes: 47 additions & 52 deletions code/API_definitions/qos-booking.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 warning on line 1 in code/API_definitions/qos-booking.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

Mandatory info.description template missing 

[P-026] info.description is missing the mandatory template 'authorization-and-authentication'. Paste the BEGIN..END block from 'code/common/info-description-templates.yaml'. | info.description is missing the mandatory template 'additional-error-responses'. Paste the BEGIN..END block from 'code/common/info-description-templates.yaml'. | info.description is missing the mandatory template 'request-body-strictness'. Paste the BEGIN..END block from 'code/common/info-description-templates.yaml'. | Suggestion: Paste the missing BEGIN..END block from code/common/info-description-templates.yaml under the template name reported in the message into info.description.
info:
title: QoS Booking
description: |
Expand Down Expand Up @@ -72,7 +72,7 @@
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
version: wip
x-camara-commonalities: tbd
x-camara-commonalities: 0.8

externalDocs:
description: Project documentation at CAMARA
Expand Down Expand Up @@ -381,6 +381,7 @@
description: Booking Identifier in UUID format
type: string
format: uuid
maxLength: 36

BaseBookingInfo:
description: Common attributes of a QoS Booking
Expand All @@ -402,6 +403,7 @@
type: string
format: uri
pattern: ^https:\/\/.+$
maxLength: 2048
description: The address to which events shall be delivered, using the HTTP protocol.
example: "https://endpoint.example.com/sink"
sinkCredential:
Expand All @@ -424,6 +426,7 @@
description: Date and time when QoS profile is scheduled to become available. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
type: string
format: date-time
maxLength: 64
duration:
description: |
Session duration in seconds. Implementations can grant the requested session duration or set a different duration from `startTime`, based on network policies or conditions.
Expand All @@ -433,6 +436,8 @@
type: integer
format: int32
minimum: 1
maximum: 31622400
# Assume 1 year
serviceArea:
$ref: "#/components/schemas/Area"
bookingId:
Expand All @@ -441,6 +446,7 @@
description: Date and time when the Booking became "ACTIVATED". Not to be returned when `bookingStatus` is "REQUESTED" or "SCHEDULED". It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
type: string
format: date-time
maxLength: 64
bookingStatus:
$ref: "#/components/schemas/BookingStatus"
statusInfo:
Expand All @@ -464,12 +470,15 @@
description: Date and time when the API consumer requests the QoS profile to become available. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
type: string
format: date-time
maxLength: 64
duration:
description:
Requested session duration in seconds. Value may be explicitly limited for the QoS profile, as specified in the Qos Profile (see qos-profile API). Implementations can grant the requested session duration or set a different duration from `startTime`, based on network policies or conditions.
type: integer
format: int32
minimum: 1
maximum: 31622400
# Assume 1 year
serviceArea:
$ref: "#/components/schemas/Area"
required:
Expand All @@ -490,6 +499,7 @@
items:
$ref: "#/components/schemas/BookingInfo"
minItems: 0
maxItems: 100

SinkCredential:

@jlurien jlurien Jun 30, 2026

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.

Any reason not to replace this with $ref: "../common/CAMARA_event_common.yaml#/components/schemas/SinkCredential"?

@Masa8106 Masa8106 Jun 30, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

When this PR was opened, target release was alpha release and it was not warning not to use $ref;. This is a reason.
Now I know it is warning not to use $ref: for RC release. So let me update it to use $ref: after merging this PR.

description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target.
Expand All @@ -500,18 +510,18 @@
enum:
- PLAIN
- ACCESSTOKEN
- REFRESHTOKEN
description: "The type of the credential."
- PRIVATE_KEY_JWT
description: The type of the credential - MUST be set to ACCESSTOKEN or PRIVATE_KEY_JWT for now
discriminator:
propertyName: credentialType
mapping:
PLAIN: "#/components/schemas/PlainCredential"
ACCESSTOKEN: "#/components/schemas/AccessTokenCredential"
REFRESHTOKEN: "#/components/schemas/RefreshTokenCredential"
PRIVATE_KEY_JWT: "#/components/schemas/PrivateKeyJWTCredential"
required:
- credentialType

PlainCredential:

Check notice on line 524 in code/API_definitions/qos-booking.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

Component may be unused 

[S-211] Potentially unused component has been detected. | Suggestion: Spectral does not follow discriminator mappings — verify the schema is truly unused.
type: object
description: A plain credential as a combination of an identifier and a secret.
allOf:
Expand All @@ -521,26 +531,30 @@
- identifier
- secret
properties:
identifier:

Check notice on line 534 in code/API_definitions/qos-booking.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

String has no format/pattern/enum 

[S-313] Schema of type string should specify a format, pattern, enum, or const. | Suggestion: Acceptable if free-form field or implementation-dependent — no fix needed.
description: The identifier might be an account or username.
type: string
maxLength: 256
secret:

Check notice on line 538 in code/API_definitions/qos-booking.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

String has no format/pattern/enum 

[S-313] Schema of type string should specify a format, pattern, enum, or const. | Suggestion: Acceptable if free-form field or implementation-dependent — no fix needed.
description: The secret might be a password or passphrase.
type: string
maxLength: 512

AccessTokenCredential:

Check notice on line 543 in code/API_definitions/qos-booking.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

Component may be unused 

[S-211] Potentially unused component has been detected. | Suggestion: Spectral does not follow discriminator mappings — verify the schema is truly unused.
type: object
description: An access token credential.
description: An access token credential. This type of credential is meant to be used by API Consumers that have limited capabilities to handle authorization requests.
allOf:
- $ref: "#/components/schemas/SinkCredential"
- type: object
properties:
accessToken:

Check notice on line 550 in code/API_definitions/qos-booking.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

String has no format/pattern/enum 

[S-313] Schema of type string should specify a format, pattern, enum, or const. | Suggestion: Acceptable if free-form field or implementation-dependent — no fix needed.
description: REQUIRED. An access token is a previously acquired token granting access to the target resource.
description: REQUIRED. An access token is a token granting access to the target resource.
type: string
maxLength: 4096
accessTokenExpiresUtc:
type: string
format: date-time
maxLength: 64
description: |
REQUIRED. An absolute (UTC) timestamp at which the token shall be considered expired.
In the case of an ACCESS_TOKEN_EXPIRED termination reason, implementation should notify the client before the expiration date.
Expand All @@ -557,47 +571,16 @@
- accessTokenExpiresUtc
- accessTokenType

RefreshTokenCredential:
PrivateKeyJWTCredential:

Check notice on line 574 in code/API_definitions/qos-booking.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

Component may be unused 

[S-211] Potentially unused component has been detected. | Suggestion: Spectral does not follow discriminator mappings — verify the schema is truly unused.
type: object
description: An access token credential with a refresh token.
description: Use PRIVATE_KEY_JWT to get an access token. The authorization server information needed for this type of sink credential (token endpoint, client ID, JWKS URL) is shared upfront between the client and the CAMARA entity. This type of credential is to be used by clients that have an authorization server.
allOf:
- $ref: "#/components/schemas/SinkCredential"
- type: object
properties:
accessToken:
description: REQUIRED. An access token is a previously acquired token granting access to the target resource.
type: string
accessTokenExpiresUtc:
type: string
format: date-time
description: |
REQUIRED. An absolute (UTC) timestamp at which the token shall be considered expired.
In the case of an ACCESS_TOKEN_EXPIRED termination reason, implementation should notify the client before the expiration date.
If the access token is a JWT and registered "exp" (Expiration Time) claim is present, the two expiry times should match.
It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone.
example: "2023-07-03T12:27:08.312Z"
accessTokenType:
description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)).
type: string
enum:
- bearer
refreshToken:
description: REQUIRED. An refresh token credential used to acquire access tokens.
type: string
refreshTokenEndpoint:
type: string
format: uri
description: REQUIRED. A URL at which the refresh token can be traded for an access token.
required:
- accessToken
- accessTokenExpiresUtc
- accessTokenType
- refreshToken
- refreshTokenEndpoint

Port:
description: TCP or UDP port number
type: integer
format: int32
minimum: 0
maximum: 65535

Expand All @@ -607,10 +590,12 @@
minProperties: 1
properties:
ranges:
description: Range of TCP or UDP ports
description: Array of TCP or UDP port ranges
type: array
minItems: 1
maxItems: 65536
items:
description: Range of TCP or UDP port
type: object
required:
- from
Expand All @@ -624,6 +609,7 @@
description: Array of TCP or UDP ports
type: array
minItems: 1
maxItems: 65536
items:
$ref: "#/components/schemas/Port"
example:
Expand Down Expand Up @@ -669,7 +655,7 @@
mapping:
org.camaraproject.qos-booking.v0.status-changed: "#/components/schemas/EventStatusChanged"

EventStatusChanged:

Check notice on line 658 in code/API_definitions/qos-booking.yaml

View workflow job for this annotation

GitHub Actions / validation / Validate

Component may be unused 

[S-211] Potentially unused component has been detected. | Suggestion: Spectral does not follow discriminator mappings — verify the schema is truly unused.
description: Event to notify a QoS booking status change
allOf:
- $ref: "#/components/schemas/BookingNotificationEvent"
Expand Down Expand Up @@ -772,6 +758,7 @@
properties:
areaName:
type: string
maxLength: 256

PointList:
description: List of points defining a polygon
Expand Down Expand Up @@ -830,7 +817,7 @@
networkAccessIdentifier:
$ref: "#/components/schemas/NetworkAccessIdentifier"
ipv4Address:
$ref: "#/components/schemas/DeviceIpv4Addr"
$ref: "#/components/schemas/DeviceIpv4Address"
ipv6Address:
$ref: "#/components/schemas/DeviceIpv6Address"
minProperties: 1
Expand All @@ -853,6 +840,7 @@

ApplicationServerIpv4Address:
type: string
maxLength: 15
example: "198.51.100.0/24"
description: |
IPv4 address may be specified in form <address/mask> as:
Expand All @@ -862,6 +850,7 @@

ApplicationServerIpv6Address:
type: string
maxLength: 45
example: "2001:db8:85a3:8d3:1319:8a2e:370:7344"
description: |
IPv6 address may be specified in form <address/mask> as:
Expand All @@ -875,15 +864,17 @@
NetworkAccessIdentifier:
description: A public identifier addressing a subscription in a mobile network. In 3GPP terminology, it corresponds to the GPSI formatted with the External Identifier ({Local Identifier}@{Domain Identifier}). Unlike the telephone number, the network access identifier is not subjected to portability ruling in force, and is individually managed by each operator.
type: string
maxLength: 2028
example: "123456789@domain.com"

PhoneNumber:
description: A public identifier addressing a telephone subscription. In mobile networks it corresponds to the MSISDN (Mobile Station International Subscriber Directory Number). In order to be globally unique it has to be formatted in international format, according to E.164 standard, prefixed with '+'.
type: string
pattern: '^\+[1-9][0-9]{4,14}$'
maxLength: 16
example: "+123456789"

DeviceIpv4Addr:
DeviceIpv4Address:
type: object
description: |
The device should be identified by either the public (observed) IP address and port as seen by the application server, or the private (local) and any public (observed) IP addresses in use by the device (this information can be obtained by various means, for example from some DNS servers).
Expand All @@ -895,9 +886,9 @@
In all cases, publicAddress must be specified, along with at least one of either privateAddress or publicPort, dependent upon which is known. In general, mobile devices cannot be identified by their public IPv4 address alone.
properties:
publicAddress:
$ref: "#/components/schemas/SingleIpv4Addr"
$ref: "#/components/schemas/SingleIpv4Address"
privateAddress:
$ref: "#/components/schemas/SingleIpv4Addr"
$ref: "#/components/schemas/SingleIpv4Address"
publicPort:
$ref: "#/components/schemas/Port"
anyOf:
Expand All @@ -909,16 +900,18 @@
"publicPort": 59765
}

SingleIpv4Addr:
SingleIpv4Address:
description: A single IPv4 address with no subnet mask
type: string
maxLength: 15
format: ipv4
example: "203.0.113.0"

DeviceIpv6Address:
description: |
The device should be identified by the observed IPv6 address, or by any single IPv6 address from within the subnet allocated to the device (e.g. adding ::0 to the /64 prefix).
type: string
maxLength: 45
format: ipv6
example: 2001:db8:85a3:8d3:1319:8a2e:370:7344

Expand Down Expand Up @@ -960,20 +953,27 @@
properties:
status:
type: integer
format: int32
minimum: 100
maximum: 599
description: HTTP response status code
code:
type: string
maxLength: 96
description: A human-readable code to describe the error
message:
type: string
maxLength: 512
description: A human-readable description of what the event represents
required:
- status
- code
- message

XCorrelator:
description: Correlation id for the different services
type: string
maxLength: 256
pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$
example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46"

Expand Down Expand Up @@ -1057,12 +1057,7 @@
value:
status: 400
code: INVALID_CREDENTIAL
message: Only Access token is supported
GENERIC_400_INVALID_TOKEN:
value:
status: 400
code: INVALID_TOKEN
message: Only bearer token is supported
message: Only Access token or Private key JWT are supported
GENERIC_400_INVALID_SINK:
description: Invalid sink value
value:
Expand Down
Loading
Loading