From ce02454071f74412d59b47144c952ebd72fa3ad0 Mon Sep 17 00:00:00 2001 From: Thorsten Lohmar Date: Mon, 2 Mar 2026 11:02:13 +0100 Subject: [PATCH 01/14] New Commonalities version header format (i.e. "0.7") --- code/API_definitions/dedicated-network-accesses.yaml | 2 +- code/API_definitions/dedicated-network-areas.yaml | 2 +- code/API_definitions/dedicated-network-profiles.yaml | 2 +- code/API_definitions/dedicated-network.yaml | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/dedicated-network-accesses.yaml b/code/API_definitions/dedicated-network-accesses.yaml index 74aaa07..94392a2 100644 --- a/code/API_definitions/dedicated-network-accesses.yaml +++ b/code/API_definitions/dedicated-network-accesses.yaml @@ -78,7 +78,7 @@ info: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: wip - x-camara-commonalities: 0.6 + x-camara-commonalities: "0.7" externalDocs: description: Product documentation at CAMARA url: https://github.com/camaraproject/DedicatedNetworks diff --git a/code/API_definitions/dedicated-network-areas.yaml b/code/API_definitions/dedicated-network-areas.yaml index c6ab073..f6c65e3 100644 --- a/code/API_definitions/dedicated-network-areas.yaml +++ b/code/API_definitions/dedicated-network-areas.yaml @@ -63,7 +63,7 @@ info: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: wip - x-camara-commonalities: 0.6 + x-camara-commonalities: "0.7" servers: - url: "{apiRoot}/dedicated-network-areas/vwip" variables: diff --git a/code/API_definitions/dedicated-network-profiles.yaml b/code/API_definitions/dedicated-network-profiles.yaml index aaff87c..fb97310 100644 --- a/code/API_definitions/dedicated-network-profiles.yaml +++ b/code/API_definitions/dedicated-network-profiles.yaml @@ -51,7 +51,7 @@ info: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: wip - x-camara-commonalities: 0.6 + x-camara-commonalities: "0.7" externalDocs: description: Product documentation at CAMARA url: https://github.com/camaraproject/DedicatedNetworks diff --git a/code/API_definitions/dedicated-network.yaml b/code/API_definitions/dedicated-network.yaml index 7f2e3ca..6b765be 100644 --- a/code/API_definitions/dedicated-network.yaml +++ b/code/API_definitions/dedicated-network.yaml @@ -53,7 +53,7 @@ info: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: wip - x-camara-commonalities: 0.6 + x-camara-commonalities: "0.7" externalDocs: description: Product documentation at CAMARA url: https://github.com/camaraproject/DedicatedNetworks From 045a4736d455ceb3350cd77d84f31288707d9b64 Mon Sep 17 00:00:00 2001 From: Thorsten Lohmar Date: Mon, 2 Mar 2026 11:05:09 +0100 Subject: [PATCH 02/14] fix : 'Addr' schema objects updated to 'Address' #563 --- code/API_definitions/dedicated-network-accesses.yaml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/code/API_definitions/dedicated-network-accesses.yaml b/code/API_definitions/dedicated-network-accesses.yaml index 94392a2..1c7d1c7 100644 --- a/code/API_definitions/dedicated-network-accesses.yaml +++ b/code/API_definitions/dedicated-network-accesses.yaml @@ -333,7 +333,7 @@ components: networkAccessIdentifier: $ref: "#/components/schemas/NetworkAccessIdentifier" ipv4Address: - $ref: "#/components/schemas/DeviceIpv4Addr" + $ref: "#/components/schemas/DeviceIpv4Address" ipv6Address: $ref: "#/components/schemas/DeviceIpv6Address" minProperties: 1 @@ -349,7 +349,7 @@ components: type: string example: "123456789@domain.com" - 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). @@ -361,9 +361,9 @@ components: 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: @@ -373,7 +373,7 @@ components: publicAddress: "84.125.93.10" publicPort: 59765 - SingleIpv4Addr: + SingleIpv4Address: description: A single IPv4 address with no subnet mask type: string format: ipv4 From b24058d004968dd76b71d3057941bac1f10de50f Mon Sep 17 00:00:00 2001 From: Thorsten Lohmar Date: Mon, 2 Mar 2026 20:08:01 +0100 Subject: [PATCH 03/14] Guidelines and linting rules for OWASP API Security Top 10 #582 --- .../dedicated-network-accesses.yaml | 16 ++++++ .../dedicated-network-areas.yaml | 14 +++++ .../dedicated-network-profiles.yaml | 10 ++++ code/API_definitions/dedicated-network.yaml | 57 +++++++++++++++++-- 4 files changed, 91 insertions(+), 6 deletions(-) diff --git a/code/API_definitions/dedicated-network-accesses.yaml b/code/API_definitions/dedicated-network-accesses.yaml index 1c7d1c7..83544d5 100644 --- a/code/API_definitions/dedicated-network-accesses.yaml +++ b/code/API_definitions/dedicated-network-accesses.yaml @@ -119,6 +119,7 @@ paths: type: array items: $ref: '#/components/schemas/NetworkAccessInfo' + maxItems: 200 "400": $ref: "#/components/responses/Generic400" "401": @@ -156,6 +157,7 @@ paths: required: true schema: type: string + maxLength: 2048 '400': $ref: "#/components/responses/Generic400" "401": @@ -255,6 +257,7 @@ components: as per section 3.3.5 of the RFC schema: type: string + maxLength: 200 example: 'phonenumber="+123456789"' headers: @@ -267,17 +270,20 @@ components: XCorrelator: type: string pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$ + maxLength: 256 example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" AccessId: description: Network access id in UUID format type: string format: uuid + maxLength: 36 NetworkId: description: Network id in UUID format type: string format: uuid + maxLength: 36 BaseNetworkAccessInfo: description: Common attributes of a device access to a dedicated network @@ -292,10 +298,13 @@ components: type: array items: type: string + maxLength: 256 minItems: 1 + maxItems: 10 defaultQosProfile: description: (Optional) The default QOS profile of a device access. When absent, the defaultQosProfile of the Network is used type: string + maxLength: 256 required: - networkId @@ -377,6 +386,7 @@ components: description: A single IPv4 address with no subnet mask type: string format: ipv4 + maxLength: 15 example: "84.125.93.10" Port: @@ -390,6 +400,7 @@ components: 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 format: ipv6 + maxLength: 45 example: 2001:db8:85a3:8d3:1319:8a2e:370:7344 ErrorInfo: @@ -401,12 +412,17 @@ components: 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 responses: diff --git a/code/API_definitions/dedicated-network-areas.yaml b/code/API_definitions/dedicated-network-areas.yaml index f6c65e3..26d892e 100644 --- a/code/API_definitions/dedicated-network-areas.yaml +++ b/code/API_definitions/dedicated-network-areas.yaml @@ -93,6 +93,7 @@ paths: type: array items: $ref: '#/components/schemas/ServiceArea' + maxItems: 200 '400': $ref: "#/components/responses/Generic400" "401": @@ -150,10 +151,12 @@ components: XCorrelator: type: string pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$ + maxLength: 256 example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" NetworkProfileId: type: string + maxLength: 36 QosProfileName: description: | @@ -174,6 +177,7 @@ components: ServiceAreaId: type: string format: uuid + maxLength: 36 RetrieveServiceAreasRequest: description: Request object to retrieve service areas that match all the given properties @@ -187,6 +191,7 @@ components: $ref: "#/components/schemas/Area" byName: type: string + maxLength: 200 byNetworkProfileId: $ref: "#/components/schemas/NetworkProfileId" byQosProfileName: @@ -199,8 +204,10 @@ components: $ref: '#/components/schemas/ServiceAreaId' name: type: string + maxLength: 200 description: type: string + maxLength: 200 area: $ref: '#/components/schemas/Area' networkProfiles: @@ -209,12 +216,14 @@ components: items: $ref: "#/components/schemas/NetworkProfileId" minItems: 1 + maxItems: 20 qosProfiles: description: Qos Profiles which are supported in this area. type: array items: $ref: '#/components/schemas/QosProfileName' minItems: 1 + maxItems: 20 required: - id - area @@ -323,12 +332,17 @@ components: 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 responses: diff --git a/code/API_definitions/dedicated-network-profiles.yaml b/code/API_definitions/dedicated-network-profiles.yaml index fb97310..ca4c4ed 100644 --- a/code/API_definitions/dedicated-network-profiles.yaml +++ b/code/API_definitions/dedicated-network-profiles.yaml @@ -77,6 +77,7 @@ paths: description: name of a network profile schema: type: string + maxLength: 200 - $ref: "#/components/parameters/x-correlator" responses: '200': @@ -87,6 +88,7 @@ paths: type: array items: $ref: '#/components/schemas/NetworkProfile' + maxItems: 200 '400': $ref: "#/components/responses/Generic400" "401": @@ -149,12 +151,14 @@ components: XCorrelator: type: string pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$ + maxLength: 256 example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" NetworkProfileId: description: Network profile id in UUID format type: string format: uuid + maxLength: 36 NetworkProfile: type: object @@ -164,6 +168,7 @@ components: name: description: A human-readable name to describe the network profile type: string + maxLength: 200 maxNumberOfDevices: type: integer aggregatedUlThroughput: @@ -235,12 +240,17 @@ components: 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 responses: diff --git a/code/API_definitions/dedicated-network.yaml b/code/API_definitions/dedicated-network.yaml index 6b765be..85ae20b 100644 --- a/code/API_definitions/dedicated-network.yaml +++ b/code/API_definitions/dedicated-network.yaml @@ -87,6 +87,7 @@ paths: type: array items: $ref: '#/components/schemas/NetworkInfo' + maxItems: 200 "400": $ref: "#/components/responses/Generic400" "401": @@ -164,6 +165,7 @@ paths: schema: type: string format: uri + maxLength: 2048 '400': $ref: "#/components/responses/Generic400" "401": @@ -253,17 +255,20 @@ components: XCorrelator: type: string pattern: ^[a-zA-Z0-9-_:;.\/<>{}]{0,256}$ + maxLength: 256 example: "b4333c46-49c0-4f62-80d7-f0ef930f1c46" NetworkId: description: Network id in UUID format type: string format: uuid + maxLength: 36 NetworkProfileId: description: Network profile id in UUID format type: string format: uuid + maxLength: 36 QosProfileName: description: | @@ -284,6 +289,7 @@ components: ServiceAreaId: type: string format: uuid + maxLength: 36 BaseNetworkInfo: description: Common attributes of a dedicated network @@ -301,6 +307,7 @@ components: description: The address to which events shall be delivered using the selected protocol. type: string format: uri + maxLength: 2048 pattern: ^https:\/\/.+$ sinkCredential: $ref: '#/components/schemas/SinkCredential' @@ -360,10 +367,9 @@ components: id: description: Identifier of this event, that must be unique in the source context. type: string + maxLength: 256 source: - description: Identifies the context in which an event happened in the specific Provider Implementation. - type: string - format: uri-reference + $ref: "#/components/schemas/Source" type: description: The type of the event. type: string @@ -383,15 +389,41 @@ components: description: Event notification details payload, which depends on the event type type: object time: + $ref: "#/components/schemas/DateTime" description: | - Timestamp of when the occurrence happened. It must follow RFC 3339 + Timestamp of when the occurrence happened. 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 discriminator: propertyName: 'type' mapping: org.camaraproject.dedicated-network.v0.network-status-changed: "#/components/schemas/EventNetworkStatusChanged" + Source: + type: string + format: uri-reference + minLength: 1 + maxLength: 2048 + description: | + Identifies the context in which an event happened - be a non-empty `URI-reference` like: + - URI with a DNS authority: + * https://github.com/cloudevents + * mailto:cncf-wg-serverless@lists.cncf.io + - Universally-unique URN with a UUID: + * urn:uuid:6e8bc430-9c3a-11d9-9669-0800200c9a66 + - Application-specific identifier: + * /cloudevents/spec/pull/123 + * 1-555-123-4567 + example: "https://notificationSendServer12.example.com" + + DateTime: + type: string + format: date-time + maxLength: 64 + description: Timestamp of when the occurrence happened. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. + example: "2018-04-05T17:31:00Z" + EventNetworkStatusChanged: description: Event to notify a network status change type: object @@ -456,9 +488,11 @@ components: identifier: description: The identifier might be an account or username. type: string + maxLength: 256 secret: description: The secret might be a password or passphrase. type: string + maxLength: 512 AccessTokenCredential: type: object @@ -470,10 +504,12 @@ components: accessToken: description: REQUIRED. An access token is a previously acquired token granting access to the target resource. type: string + maxLength: 4096 accessTokenExpiresUtc: type: string format: date-time - description: REQUIRED. An absolute UTC instant at which the token shall be considered expired. + maxLength: 64 + description: REQUIRED. An absolute UTC instant at which the token shall be considered expired. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. accessTokenType: description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). For the current version of the API the type MUST be set to `Bearer`. type: string @@ -494,10 +530,12 @@ components: accessToken: description: REQUIRED. An access token is a previously acquired token granting access to the target resource. type: string + maxLength: 4096 accessTokenExpiresUtc: type: string format: date-time - description: REQUIRED. An absolute UTC instant at which the token shall be considered expired. + description: REQUIRED. An absolute UTC instant at which the token shall be considered expired. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. + maxLength: 64 accessTokenType: description: REQUIRED. Type of the access token (See [OAuth 2.0](https://tools.ietf.org/html/rfc6749#section-7.1)). type: string @@ -506,9 +544,11 @@ components: refreshToken: description: REQUIRED. An refresh token credential used to acquire access tokens. type: string + maxLength: 4096 refreshTokenEndpoint: type: string format: uri + maxLength: 2048 description: REQUIRED. A URL at which the refresh token can be traded for an access token. required: - accessToken @@ -526,12 +566,17 @@ components: 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 responses: From 177e3eb7632fd147dca6ae5dddbbae83278efb35 Mon Sep 17 00:00:00 2001 From: Thorsten Lohmar Date: Wed, 4 Mar 2026 10:40:51 +0100 Subject: [PATCH 04/14] Removing leftover. --- code/API_definitions/dedicated-network.yaml | 5 ----- 1 file changed, 5 deletions(-) diff --git a/code/API_definitions/dedicated-network.yaml b/code/API_definitions/dedicated-network.yaml index 85ae20b..4894499 100644 --- a/code/API_definitions/dedicated-network.yaml +++ b/code/API_definitions/dedicated-network.yaml @@ -390,11 +390,6 @@ components: type: object time: $ref: "#/components/schemas/DateTime" - description: | - Timestamp of when the occurrence happened. 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 discriminator: propertyName: 'type' mapping: From ff930b6a36fba7fc631837ce07250acb9c8a53ea Mon Sep 17 00:00:00 2001 From: Thorsten Lohmar Date: Thu, 5 Mar 2026 17:07:52 +0100 Subject: [PATCH 05/14] Adding comments around unclear value selection. --- code/API_definitions/dedicated-network-accesses.yaml | 7 +++++-- code/API_definitions/dedicated-network-areas.yaml | 10 ++++++++-- code/API_definitions/dedicated-network-profiles.yaml | 3 +++ code/API_definitions/dedicated-network.yaml | 2 ++ 4 files changed, 18 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/dedicated-network-accesses.yaml b/code/API_definitions/dedicated-network-accesses.yaml index 83544d5..3566031 100644 --- a/code/API_definitions/dedicated-network-accesses.yaml +++ b/code/API_definitions/dedicated-network-accesses.yaml @@ -120,6 +120,7 @@ paths: items: $ref: '#/components/schemas/NetworkAccessInfo' maxItems: 200 + # We may need to add pagination support, https://github.com/camaraproject/Commonalities/blob/main/documentation/CAMARA-API-Design-Guide.md#41-pagination "400": $ref: "#/components/responses/Generic400" "401": @@ -158,6 +159,7 @@ paths: schema: type: string maxLength: 2048 + # Is this long enough? '400': $ref: "#/components/responses/Generic400" "401": @@ -257,7 +259,8 @@ components: as per section 3.3.5 of the RFC schema: type: string - maxLength: 200 + maxLength: 8192 + # Practical limit of HTTP headers example: 'phonenumber="+123456789"' headers: @@ -300,7 +303,7 @@ components: type: string maxLength: 256 minItems: 1 - maxItems: 10 + maxItems: 128 defaultQosProfile: description: (Optional) The default QOS profile of a device access. When absent, the defaultQosProfile of the Network is used type: string diff --git a/code/API_definitions/dedicated-network-areas.yaml b/code/API_definitions/dedicated-network-areas.yaml index 26d892e..59fd455 100644 --- a/code/API_definitions/dedicated-network-areas.yaml +++ b/code/API_definitions/dedicated-network-areas.yaml @@ -94,6 +94,7 @@ paths: items: $ref: '#/components/schemas/ServiceArea' maxItems: 200 + # We may need to add pagination support, https://github.com/camaraproject/Commonalities/blob/main/documentation/CAMARA-API-Design-Guide.md#41-pagination '400': $ref: "#/components/responses/Generic400" "401": @@ -192,6 +193,7 @@ components: byName: type: string maxLength: 200 + # Is this too short? byNetworkProfileId: $ref: "#/components/schemas/NetworkProfileId" byQosProfileName: @@ -205,9 +207,11 @@ components: name: type: string maxLength: 200 + # Is this too short? description: type: string maxLength: 200 + # Is this too short area: $ref: '#/components/schemas/Area' networkProfiles: @@ -216,14 +220,16 @@ components: items: $ref: "#/components/schemas/NetworkProfileId" minItems: 1 - maxItems: 20 + maxItems: 256 + # The standard should not limit deployments here. Deployments may enforce a shorter array length qosProfiles: description: Qos Profiles which are supported in this area. type: array items: $ref: '#/components/schemas/QosProfileName' minItems: 1 - maxItems: 20 + maxItems: 256 + # The standard should not limit deployments here. Deployments may enforce a shorter array length required: - id - area diff --git a/code/API_definitions/dedicated-network-profiles.yaml b/code/API_definitions/dedicated-network-profiles.yaml index ca4c4ed..974301d 100644 --- a/code/API_definitions/dedicated-network-profiles.yaml +++ b/code/API_definitions/dedicated-network-profiles.yaml @@ -78,6 +78,7 @@ paths: schema: type: string maxLength: 200 + # Is this too short? (The standard should not limit deployments) - $ref: "#/components/parameters/x-correlator" responses: '200': @@ -89,6 +90,7 @@ paths: items: $ref: '#/components/schemas/NetworkProfile' maxItems: 200 + # We may need to add pagination support, https://github.com/camaraproject/Commonalities/blob/main/documentation/CAMARA-API-Design-Guide.md#41-pagination '400': $ref: "#/components/responses/Generic400" "401": @@ -169,6 +171,7 @@ components: description: A human-readable name to describe the network profile type: string maxLength: 200 + # Is this too short? The standard should not limit deployments. maxNumberOfDevices: type: integer aggregatedUlThroughput: diff --git a/code/API_definitions/dedicated-network.yaml b/code/API_definitions/dedicated-network.yaml index 4894499..e685894 100644 --- a/code/API_definitions/dedicated-network.yaml +++ b/code/API_definitions/dedicated-network.yaml @@ -166,6 +166,7 @@ paths: type: string format: uri maxLength: 2048 + # Is this too short? The standard should not limit deployments. '400': $ref: "#/components/responses/Generic400" "401": @@ -308,6 +309,7 @@ components: type: string format: uri maxLength: 2048 + # Is this too short? the standrd should not limit deployments pattern: ^https:\/\/.+$ sinkCredential: $ref: '#/components/schemas/SinkCredential' From d40980ca3b7c31a26f9087b241f16980e8292b32 Mon Sep 17 00:00:00 2001 From: Thorsten Lohmar Date: Thu, 5 Mar 2026 17:34:03 +0100 Subject: [PATCH 06/14] Removing trailing space --- code/API_definitions/dedicated-network-accesses.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/dedicated-network-accesses.yaml b/code/API_definitions/dedicated-network-accesses.yaml index 3566031..6c0fd68 100644 --- a/code/API_definitions/dedicated-network-accesses.yaml +++ b/code/API_definitions/dedicated-network-accesses.yaml @@ -260,7 +260,7 @@ components: schema: type: string maxLength: 8192 - # Practical limit of HTTP headers + # Practical limit of HTTP headers example: 'phonenumber="+123456789"' headers: From cb6187fe16820e2deedf11036cacd41a6f9de4ce Mon Sep 17 00:00:00 2001 From: Thorsten Lohmar Date: Wed, 11 Mar 2026 14:58:40 +0100 Subject: [PATCH 07/14] Marking additional restrictions in the NW Profile --- code/API_definitions/dedicated-network-profiles.yaml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/code/API_definitions/dedicated-network-profiles.yaml b/code/API_definitions/dedicated-network-profiles.yaml index 974301d..42df780 100644 --- a/code/API_definitions/dedicated-network-profiles.yaml +++ b/code/API_definitions/dedicated-network-profiles.yaml @@ -174,6 +174,7 @@ components: # Is this too short? The standard should not limit deployments. maxNumberOfDevices: type: integer + # We may need to restrict this because of new Commonalities 0.7-rc1 aggregatedUlThroughput: $ref: "#/components/schemas/BitRate" aggregatedDlThroughput: @@ -184,6 +185,7 @@ components: items: $ref: '#/components/schemas/QosProfileName' minItems: 1 + # We may need to restrict this because of new Commonalities 0.7-rc1 defaultQosProfile: $ref: '#/components/schemas/QosProfileName' required: From e24cab408a4a826966ba7896a82cce43fd5a3097 Mon Sep 17 00:00:00 2001 From: Thorsten Lohmar Date: Sun, 22 Mar 2026 11:26:05 +0100 Subject: [PATCH 08/14] limiting maxNumberOfDevices and qosProfiles --- code/API_definitions/dedicated-network-profiles.yaml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/code/API_definitions/dedicated-network-profiles.yaml b/code/API_definitions/dedicated-network-profiles.yaml index 42df780..3f52517 100644 --- a/code/API_definitions/dedicated-network-profiles.yaml +++ b/code/API_definitions/dedicated-network-profiles.yaml @@ -174,6 +174,10 @@ components: # Is this too short? The standard should not limit deployments. maxNumberOfDevices: type: integer + example: 5 + format: int32 + minimum: 1 + maximum: 128 # We may need to restrict this because of new Commonalities 0.7-rc1 aggregatedUlThroughput: $ref: "#/components/schemas/BitRate" @@ -185,6 +189,7 @@ components: items: $ref: '#/components/schemas/QosProfileName' minItems: 1 + maxItems: 32 # We may need to restrict this because of new Commonalities 0.7-rc1 defaultQosProfile: $ref: '#/components/schemas/QosProfileName' From 4d7afcd542314950cb3b46064be874b974bc53e1 Mon Sep 17 00:00:00 2001 From: Thorsten Lohmar Date: Mon, 23 Mar 2026 14:17:53 +0100 Subject: [PATCH 09/14] Making maxNumberOfDevices an int64, considering support for IOT use-cases. Increasing the maximum. --- code/API_definitions/dedicated-network-profiles.yaml | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/code/API_definitions/dedicated-network-profiles.yaml b/code/API_definitions/dedicated-network-profiles.yaml index 3f52517..0b1e2b7 100644 --- a/code/API_definitions/dedicated-network-profiles.yaml +++ b/code/API_definitions/dedicated-network-profiles.yaml @@ -175,9 +175,10 @@ components: maxNumberOfDevices: type: integer example: 5 - format: int32 + format: int64 minimum: 1 - maximum: 128 + maximum: 1000000000000 + # this is assuming support for an IoT use-case with nationwide support. # We may need to restrict this because of new Commonalities 0.7-rc1 aggregatedUlThroughput: $ref: "#/components/schemas/BitRate" From 7f7cbfbf0754e849b00d1d79977b95da85896267 Mon Sep 17 00:00:00 2001 From: Thorsten Lohmar Date: Tue, 28 Apr 2026 09:57:01 +0200 Subject: [PATCH 10/14] Replace RefreshTokenCredential with PrivateKeyJWTCredential --- code/API_definitions/dedicated-network.yaml | 43 ++++----------------- 1 file changed, 7 insertions(+), 36 deletions(-) diff --git a/code/API_definitions/dedicated-network.yaml b/code/API_definitions/dedicated-network.yaml index e685894..122398a 100644 --- a/code/API_definitions/dedicated-network.yaml +++ b/code/API_definitions/dedicated-network.yaml @@ -456,19 +456,21 @@ components: SinkCredential: type: object + description: A sink credential provides authentication or authorization information necessary to enable delivery of events to a target. properties: credentialType: type: string enum: - PLAIN - ACCESSTOKEN - - REFRESHTOKEN + - 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 @@ -517,42 +519,11 @@ components: - accessTokenExpiresUtc - accessTokenType - RefreshTokenCredential: + PrivateKeyJWTCredential: 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 - maxLength: 4096 - accessTokenExpiresUtc: - type: string - format: date-time - description: REQUIRED. An absolute UTC instant at which the token shall be considered expired. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. - maxLength: 64 - 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 - maxLength: 4096 - refreshTokenEndpoint: - type: string - format: uri - maxLength: 2048 - description: REQUIRED. A URL at which the refresh token can be traded for an access token. - required: - - accessToken - - accessTokenExpiresUtc - - accessTokenType - - refreshToken - - refreshTokenEndpoint + - $ref: "#/components/schemas/SinkCredential" ErrorInfo: type: object From 952daf1d2796c1cd062de76dabe77dc1a586238a Mon Sep 17 00:00:00 2001 From: Thorsten Lohmar Date: Tue, 28 Apr 2026 12:30:09 +0200 Subject: [PATCH 11/14] adjusting maximum of max devices to the maximum of an int64 integer. --- code/API_definitions/dedicated-network-profiles.yaml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/code/API_definitions/dedicated-network-profiles.yaml b/code/API_definitions/dedicated-network-profiles.yaml index ed1f972..f4fd681 100644 --- a/code/API_definitions/dedicated-network-profiles.yaml +++ b/code/API_definitions/dedicated-network-profiles.yaml @@ -183,9 +183,8 @@ components: example: 5 format: int64 minimum: 1 - maximum: 1000000000000 - # this is assuming support for an IoT use-case with nationwide support. - # We may need to restrict this because of new Commonalities 0.7-rc1 + maximum: 9223372036854775807 + # int64 is motivated by IoT use-cases. There is no good reasoning for limiting the maximum. aggregatedUlThroughput: $ref: "#/components/schemas/BitRate" aggregatedDlThroughput: From c921ef70c05788f809251e09d68d5a513cb50020 Mon Sep 17 00:00:00 2001 From: Thorsten Lohmar Date: Tue, 28 Apr 2026 13:55:24 +0200 Subject: [PATCH 12/14] Removing PlainCredential --- code/API_definitions/dedicated-network.yaml | 57 ++++++++++++--------- 1 file changed, 33 insertions(+), 24 deletions(-) diff --git a/code/API_definitions/dedicated-network.yaml b/code/API_definitions/dedicated-network.yaml index 03fb9e0..f145079 100644 --- a/code/API_definitions/dedicated-network.yaml +++ b/code/API_definitions/dedicated-network.yaml @@ -306,6 +306,9 @@ components: name: description: A human-readable name to describe the network type: string + minLength: 1 + maxLength: 256 + # No empty string name allowed. networkProfileId: $ref: '#/components/schemas/NetworkProfileId' qosProfileName: @@ -471,41 +474,42 @@ components: credentialType: type: string enum: - - PLAIN + # - PLAIN - ACCESSTOKEN - PRIVATE_KEY_JWT - description: The type of the credential - MUST be set to ACCESSTOKEN or PRIVATE_KEY_JWT for now + 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' + # PLAIN: '#/components/schemas/PlainCredential' ACCESSTOKEN: '#/components/schemas/AccessTokenCredential' PRIVATE_KEY_JWT: '#/components/schemas/PrivateKeyJWTCredential' required: - credentialType - PlainCredential: - type: object - description: A plain credential as a combination of an identifier and a secret. - allOf: - - $ref: '#/components/schemas/SinkCredential' - - type: object - required: - - identifier - - secret - properties: - identifier: - description: The identifier might be an account or username. - type: string - maxLength: 256 - secret: - description: The secret might be a password or passphrase. - type: string - maxLength: 512 + # PlainCredential: # not used in CAMARA + # type: object + # description: A plain credential as a combination of an identifier and a secret. + # allOf: + # - $ref: "#/components/schemas/SinkCredential" + # - type: object + # required: + # - identifier + # - secret + # properties: + # identifier: + # description: The identifier might be an account or username. + # type: string + # maxLength: 256 + # secret: + # description: The secret might be a password or passphrase. + # type: string + # maxLength: 512 AccessTokenCredential: 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 @@ -518,7 +522,12 @@ components: type: string format: date-time maxLength: 64 - description: REQUIRED. An absolute UTC instant at which the token shall be considered expired. It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. + 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)). For the current version of the API the type MUST be set to `Bearer`. type: string @@ -531,7 +540,7 @@ components: PrivateKeyJWTCredential: type: object - 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. + 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" From 0c155fa44a4fa3c23d681b61f10f7f3959b46cf2 Mon Sep 17 00:00:00 2001 From: Thorsten Lohmar Date: Tue, 28 Apr 2026 14:26:59 +0200 Subject: [PATCH 13/14] insertion of maxLength for strings. --- .../API_definitions/dedicated-network-accesses.yaml | 6 +++++- code/API_definitions/dedicated-network.yaml | 13 ++++++++++--- 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/code/API_definitions/dedicated-network-accesses.yaml b/code/API_definitions/dedicated-network-accesses.yaml index c65b4c9..de4dd9f 100644 --- a/code/API_definitions/dedicated-network-accesses.yaml +++ b/code/API_definitions/dedicated-network-accesses.yaml @@ -203,7 +203,7 @@ paths: schema: type: string maxLength: 2048 - # Is this long enough? + # This is typically a relative URL. Thus, 2048 characters can be enough. '400': $ref: "#/components/responses/Generic400" "401": @@ -354,9 +354,13 @@ components: properties: code: type: string + maxLength: 96 + # Aligned with ErrorInfo description: A human-readable code to describe the reason message: type: string + maxLength: 512 + # Aligned with ErrorInfo description: A human-readable description of what the reason represents DeviceAccessStatusInfo: diff --git a/code/API_definitions/dedicated-network.yaml b/code/API_definitions/dedicated-network.yaml index f145079..8329988 100644 --- a/code/API_definitions/dedicated-network.yaml +++ b/code/API_definitions/dedicated-network.yaml @@ -84,6 +84,8 @@ paths: description: name of a network schema: type: string + maxLength: 256 + # according to name definition - $ref: "#/components/parameters/x-correlator" responses: '200': @@ -173,7 +175,7 @@ paths: type: string format: uri maxLength: 2048 - # Is this too short? The standard should not limit deployments. + # This is typically a relative URL. Thus, 2048 characters can be enough. '400': $ref: "#/components/responses/Generic400" "401": @@ -307,8 +309,9 @@ components: description: A human-readable name to describe the network type: string minLength: 1 + # No empty string name allowed. maxLength: 256 - # No empty string name allowed. + # 256 characters should be enough for normal cases. networkProfileId: $ref: '#/components/schemas/NetworkProfileId' qosProfileName: @@ -322,7 +325,7 @@ components: type: string format: uri maxLength: 2048 - # Is this too short? the standrd should not limit deployments + # Follows the recommendation from CAMARA_event_common.yaml pattern: ^https:\/\/.+$ sinkCredential: $ref: '#/components/schemas/SinkCredential' @@ -388,6 +391,8 @@ components: type: description: The type of the event. type: string + maxLength: 512 + # Follows CAMARA_event_common.yaml, although this is an enum enum: - "org.camaraproject.dedicated-network.v0.network-status-changed" specversion: @@ -458,10 +463,12 @@ components: start: type: string format: date-time + maxLength: 64 description: It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z) end: type: string format: date-time + maxLength: 64 description: It must follow [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6) and must have time zone. Recommended format is yyyy-MM-dd'T'HH:mm:ss.SSSZ (i.e. which allows 2023-07-03T14:27:08.312+02:00 or 2023-07-03T12:27:08.312Z) required: - start From 632737a661de21088f1222b55e0db872c8f037cf Mon Sep 17 00:00:00 2001 From: Thorsten Lohmar Date: Tue, 28 Apr 2026 14:35:23 +0200 Subject: [PATCH 14/14] Trailing spaces...;-( --- code/API_definitions/dedicated-network.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code/API_definitions/dedicated-network.yaml b/code/API_definitions/dedicated-network.yaml index 8329988..e966882 100644 --- a/code/API_definitions/dedicated-network.yaml +++ b/code/API_definitions/dedicated-network.yaml @@ -309,7 +309,7 @@ components: description: A human-readable name to describe the network type: string minLength: 1 - # No empty string name allowed. + # No empty string name allowed. maxLength: 256 # 256 characters should be enough for normal cases. networkProfileId: