Skip to content

fix: aligns base Device type with commonalities #70

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
caubut-charter merged 1 commit into from
Jul 3, 2025
Merged

fix: aligns base Device type with commonalities #70

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
244 changes: 150 additions & 94 deletions code/API_definitions/network-access-management.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1824,103 +1824,159 @@ components:
example: &device-network-intersection-list
- *device-network-intersection

# FIXME: https://github.com/camaraproject/NetworkAccessManagement/issues/27
# Device:
# description: |
# End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators.
# The developer can choose to provide the below specified device identifiers:
# * `ipv4Address`
# * `ipv6Address`
# * `phoneNumber`
# * `networkAccessIdentifier`
# NOTE1: the network operator might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different network operators. In this case the identifiers MUST belong to the same device.
# NOTE2: as for this Commonalities release, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines.
# type: object
# properties:
# phoneNumber:
# $ref: "#/components/schemas/PhoneNumber"
# networkAccessIdentifier:
# $ref: "#/components/schemas/NetworkAccessIdentifier"
# ipv4Address:
# $ref: "#/components/schemas/DeviceIpv4Addr"
# ipv6Address:
# $ref: "#/components/schemas/DeviceIpv6Address"
# minProperties: 1
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}$'
example: "+123456789"

Device:
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
example: "123456789@domain.com"

DeviceIpv4Addr:
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).

If the allocated and observed IP addresses are the same (i.e. NAT is not in use) then the same address should be specified for both publicAddress and privateAddress.

If NAT64 is in use, the device should be identified by its publicAddress and publicPort, or separately by its allocated IPv6 address (field ipv6Address of the Device object)

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:
id:
$ref: "#/components/schemas/DeviceId"
name:
type: string
minLength: 1
maxLength: 100
description: The name of the device
example: &device-name "Gateway-1"
description:
type: string
minLength: 0
maxLength: 255
description: A description of the device
example: &device-description "A Wi-Fi gateway device"
hardwareAddress:
description: The hardware address of the device
oneOf:
- type: object
properties:
hardwareAddressType:
type: string
enum: ["EUI-48"]
example: &device-hardware-address-type "EUI-48"
value:
type: string
pattern: "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$"
example: &device-hardware-address-value "12:34:56:78:9A:BC"
required:
- hardwareAddressType
- value
discriminator:
propertyName: hardwareAddressType
example: &device-hardware-address
hardwareAddressType: *device-hardware-address-type
value: *device-hardware-address-value
serviceSite:
$ref: "#/components/schemas/ServiceSiteId"
networks:
allOf:
- $ref: "#/components/schemas/DeviceNetworkIntersectionList"
- description: The IDs of networks attached to the device
example: *device-network-intersection-list
maxAuxiliaryNetworks:
type: integer
description: >-
Maximum amount of auxiliary networks the device supports for a given client. For the `only-own` client
roles, this is a count of what is in-use by the client + remaining count of what the client can create. For
`primary`-only client roles, the field is not used. For `auxiliary`-only client roles, it is the maximum
number the device supports.
minimum: 1
example: &device-max-networks 2
deviceStatus:
type: string
enum:
- connected
- disconnected
- unavailable
default: unavailable
description: The current status of the device
example: &device-status "connected"
required:
- id
example: &device
id: *device-id
deviceStatus: *device-status
name: *device-name
description: *device-description
hardwareAddress: *device-hardware-address
serviceSite: *service-site-id
networks: *device-network-intersection-list
maxAuxiliaryNetworks: *device-max-networks
publicAddress:
$ref: "#/components/schemas/SingleIpv4Addr"
privateAddress:
$ref: "#/components/schemas/SingleIpv4Addr"
publicPort:
$ref: "#/components/schemas/Port"
anyOf:
- required: [publicAddress, privateAddress]
- required: [publicAddress, publicPort]
example:
publicAddress: "84.125.93.10"
publicPort: 59765

SingleIpv4Addr:
description: A single IPv4 address with no subnet mask
type: string
format: ipv4
example: "84.125.93.10"

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

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
format: ipv6
example: 2001:db8:85a3:8d3:1319:8a2e:370:7344

# https://github.com/camaraproject/Commonalities/blob/main/artifacts/CAMARA_common.yaml
BaseDevice:
description: |
End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators.
The developer can choose to provide the below specified device identifiers:
* `ipv4Address`
* `ipv6Address`
* `phoneNumber`
* `networkAccessIdentifier`
NOTE1: the network operator might support only a subset of these options. The API invoker can provide multiple identifiers to be compatible across different network operators. In this case the identifiers MUST belong to the same device.
NOTE2: as for this Commonalities release, we are enforcing that the networkAccessIdentifier is only part of the schema for future-proofing, and CAMARA does not currently allow its use. After the CAMARA meta-release work is concluded and the relevant issues are resolved, its use will need to be explicitly documented in the guidelines.
type: object
properties:
phoneNumber:
$ref: "#/components/schemas/PhoneNumber"
networkAccessIdentifier:
$ref: "#/components/schemas/NetworkAccessIdentifier"
ipv4Address:
$ref: "#/components/schemas/DeviceIpv4Addr"
ipv6Address:
$ref: "#/components/schemas/DeviceIpv6Address"
# minProperties: 1 # NOTE: not used currently
Comment on lines +1882 to +1902
Copy link
Contributor

@clundie-CL clundie-CL Jul 3, 2025

Choose a reason for hiding this comment

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

Does it make sense to have something like this attached to BaseDevice:

    example: &base-device-model
    phoneNumber: "+123456789"
    networkAccessIdentifier: "123456789@example.com"
    ipv4Address:
      publicAddress: "84.125.93.10"
      publicPort: 59765
    ipv6Address: "2001:db8:85a3:8d3:1319:8a2e:370:7344"

in order to update examples like this:

    BaseDevice:
      summary: Base Device
      description: |
        Output with the following scope(s):
        - **one of**
          - `network-access-management:devices:read`
          - `network-access-management:devices:write`
      value: &base-device
        - *base-device-model
        - id: *device-id
          name: *device-name
          description: *device-description


Device:
allOf:
- $ref: "#/components/schemas/BaseDevice"
- type: object
properties:
id:
$ref: "#/components/schemas/DeviceId"
name:
type: string
minLength: 1
maxLength: 100
description: The name of the device
example: &device-name "Gateway-1"
description:
type: string
minLength: 0
maxLength: 255
description: A description of the device
example: &device-description "A Wi-Fi gateway device"
hardwareAddress:
description: The hardware address of the device
oneOf:
- type: object
properties:
hardwareAddressType:
type: string
enum: ["EUI-48"]
example: &device-hardware-address-type "EUI-48"
value:
type: string
pattern: "^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$"
example: &device-hardware-address-value "12:34:56:78:9A:BC"
required:
- hardwareAddressType
- value
discriminator:
propertyName: hardwareAddressType
example: &device-hardware-address
hardwareAddressType: *device-hardware-address-type
value: *device-hardware-address-value
serviceSite:
$ref: "#/components/schemas/ServiceSiteId"
networks:
allOf:
- $ref: "#/components/schemas/DeviceNetworkIntersectionList"
- description: The IDs of networks attached to the device
example: *device-network-intersection-list
maxAuxiliaryNetworks:
type: integer
description: >-
Maximum amount of auxiliary networks the device supports for a given client. For the `only-own` client
roles, this is a count of what is in-use by the client + remaining count of what the client can create. For
`primary`-only client roles, the field is not used. For `auxiliary`-only client roles, it is the maximum
number the device supports.
minimum: 1
example: &device-max-networks 2
deviceStatus:
type: string
enum:
- connected
- disconnected
- unavailable
default: unavailable
description: The current status of the device
example: &device-status "connected"
required:
- id
example: &device
id: *device-id
deviceStatus: *device-status
name: *device-name
description: *device-description
hardwareAddress: *device-hardware-address
serviceSite: *service-site-id
networks: *device-network-intersection-list
maxAuxiliaryNetworks: *device-max-networks

DeviceList:
type: array
Expand Down