Closed shilpa-padgaonkar closed 1 year ago
Would be great if someone can take this issue who is able to recognize where we are using telco terms while we should use something more developer-friendly. Any volunteer?
Would be great if someone can take this issue who is able to recognize where we are using telco terms while we should use something more developer-friendly. Any volunteer?
I can start with this task
The following is the list of properties used in the current version of the API. Almost all of them should be renamed to more descriptive and dev friendly terms, and to comply with the guidelines. Before adding terms to the global Glossary, it would be good to have some internal consensus about the alternative names.
In bold are my personal preferences.
Current term | Proposed alternatives | Comment |
---|---|---|
ueId |
device_info , device , user_device , device_id |
It should be added in description that it refers to client or user device, if not included in the name property. If it is an object with several details instead of a single unique ID, as it is now, maybe _id is not very accurate. |
msisdn |
phone_number , mobile_number |
MSISDN is really restricted to mobile phone numbers, but phone number is more generic. While MSISDN is very common in Telco industry it may not be friendly to general devs |
ipv4Addr |
ip_v4_address |
At some moment we may think in consolidating both V4 and V6 formats in one single property ip_address as version can be deducted from value |
ipv6Addr |
ip_v6_address |
|
externalId |
external_id |
Description should be enhanced to inform about this option. Pending on discussions in commonalities around adoption of 3GPP GPSI |
asId |
app_server_info , app_server |
It should be aligned with the verbosity chosen for ueId |
uePorts |
device_ports , client_ports |
uePort used for device identification in NAT scenarios should be consolidated within device info object |
asPorts |
app_server_ports , server_ports |
|
id |
session_id |
In the context of the response it is implicit, but as we refer to it as sessionId in the notification event, it may be clearer to use same name everywhere |
qos |
qos_profile |
QoS is very generic while in fact we are referring here to a QoS profile specifically |
@hdamker @eric-murray @patrice-conil
It would be great if you could give some feedback and opinions on the terminology and proposals for alternative names. Remember the guidelines are being "dev friendly/not just for telcos", and formatted in snake_case. Thanks!
Notes from the discussion we had in our call on Friday, Feb 10th:
In particular:
Current term | Proposed alternatives | Comment | Discussion 2023-02-10 |
---|---|---|---|
ueId |
device_info , device , user_device , device_id |
It should be added in description that it refers to client or user device, if not included in the name property. If it is an object with several details instead of a single unique ID, as it is now, maybe _id is not very accurate. |
Tendency to drop info and id from the object name. If id then identifier . "user_device" had some positive feedbacks, but as not all devices might have an user, also device is one option.Discussion with poll to be opened => see #117 |
msisdn |
phone_number , mobile_number |
MSISDN is really restricted to mobile phone numbers, but phone number is more generic. While MSISDN is very common in Telco industry it may not be friendly to general devs | General understanding that phone_number is the best name for an E.164 number (which covers fixed or mobile), MSISDN is too specific, as only mobile |
ipv4Addr |
ip_v4_address |
At some moment we may think in consolidating both V4 and V6 formats in one single property ip_address as version can be deducted from value |
ip_v4_address agreed. As the API consumer can provide both IPv4 and IPv6 address in device/application_server objects, we keep them seperated |
ipv6Addr |
ip_v6_address |
ip_v6_address agreed |
|
externalId |
external_id |
Description should be enhanced to inform about this option. Pending on discussions in commonalities around adoption of 3GPP GPSI | The term external_id is "telco centric" as internal/external refers to the 3GPP system. GPSI can't be used as it is a) not known outside 3GPP experts (there is not even a Wikipedia page for it) and b) it would include again the MSISDN (phone number) as an option. The external identifier is actual an "Network Access Identifier" (NAI) as defined in RFC 4282. So network_access_identifier could be an option. Discussion and poll to be opened => see #118 |
asId |
app_server_info , app_server |
It should be aligned with the verbosity chosen for ueId | application_server added to the options. Poll to be opened => #119 |
uePorts |
device_ports , client_ports |
uePort used for device identification in NAT scenarios should be consolidated within device info object | device_ip_ports as additional proposal, to make clear that the port(s) refer to an IP connection. client_ports wouldn't be consistent with device term. Final to be determined after term for ueId is decided => see poll #120 for the appendix |
asPorts |
app_server_ports , server_ports |
term for asId togehter with either _ports or _ip_ports |
|
id |
session_id |
In the context of the response it is implicit, but as we refer to it as sessionId in the notification event, it may be clearer to use same name everywhere |
session_id agreed, but specific to QoD session resource, therefore this term will not go into the Commonality glossary |
qos |
qos_profile |
QoS is very generic while in fact we are referring here to a QoS profile specifically | qos_profile agreed, but specific to QoD session resource, therefore this term will not go into the Commonality glossary |
Please vote on your preferred options to the open topics above in the polls #117, #118, #119, #120!
In order to integrate the common glossary in Commonalities it is needed to provide the first version of subproject relevant terms by 15th of March.
@hdamker I think we already have clear winners. The only stopper I see is the ongoing debate about snake_case vs lowerCamelCase, which affects the PR we should do.
@jlurien I agree on the winners in the polls and we said to keep them open only until today. Would you like to take our entries to the Commonalities WG in https://github.com/camaraproject/WorkingGroups/pull/120 or should I?
Regarding snake_case vs lowerCamelCase I think that we should deliver towards Commonalities now in snake_case and will adapt our API definition only later when both issues are (hopefully) closed.
The winners from the polls are:
device
for ueId
network_access_identifier
for externalId
application_server
for asId
device_ports
for uePorts
application_server_ports
for asPorts
The remaining terms as agreed already above.
@jlurien I agree on the winners in the polls and we said to keep them open only until today. Would you like to take our entries to the Commonalities WG in camaraproject/WorkingGroups#120 or should I?
As you prefer, no problem in doing it. Another task is to update the yaml spec to the new property names. I can take on that. Should we open a PR now or wait until until the new terms are consolidated in the Glossary?
These are the terms that could be shared to the Commonalities Glossary, as others such as Session Id or QoS Profile are more in the scope of this API. Should we list them also there?. I added some possible descriptions but I'm happy to hear about comments or improvements.
Term | Property names | Description |
---|---|---|
Device | device |
End-user equipment able to connect to a mobile network. Examples of devices include smartphones or IoT sensors/actuators. |
Application Server | applicationServer |
A server hosting backend applications to deliver some business logic to clients. |
Phone Number | phoneNumber |
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. |
Network Access Identifier | networkAccessIdentifier |
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. |
IP v4 Address | ipv4Address |
Identifier of a node in a network using Internet Protocol version 4 (IPv4). IPv4 uses 32-bit addresses, which are insufficient to allocate unique addresses to all current devices. In order to mitigate this, network operators use Network Address Translation (NAT), mapping a private IP address space to a public one. |
IP v6 Address | ipv6Address |
Identifier of a node in a network using Internet Protocol version 6 (IPv6). IPv6 uses 128-bit addresses, allowing every device connected to the network to have a globally unique identifier. |
(IP) Port | devicePorts , applicationServerPorts |
Identifier of a connection endpoint within a node, used by transport protocols TCP and UDP, over IP networks. For TCP and UDP, a port number is a 16-bit unsigned integer, thus ranging from 0 to 65535. |
Thank you for your contribution to the commonalities glossary. https://github.com/camaraproject/WorkingGroups/blob/main/Commonalities/documentation/Glossary.md
https://github.com/camaraproject/WorkingGroups/pull/120