Update commonalities glossary with qod-subproject relevant terms

[shilpa-padgaonkar]

camaraproject/WorkingGroups#120

[hdamker]

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?

[jlurien]

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

[jlurien]

Version 0.8.0 properties

• Proposed alternatives follow the guideline in commonalities to name properties in snake_case.

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

[jlurien]

@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!

[hdamker]

Notes from the discussion we had in our call on Friday, Feb 10th:

• Tendency to be more verbose where it might help to understand the term (e.g. application_server instead app_server)
• Where there is not yet a clear picture we will open a discussion with a poll with the (remaining) options (see links below)
• We discuss here only the recommendations from QoD perspective, for terms used across Camara APIs further discussion will happen in Commonalities afterwards

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), MSISDNis 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_idis "telco centric" as internal/external refers to the 3GPP system. GPSIcan'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_portsas 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

[hdamker]

Please vote on your preferred options to the open topics above in the polls #117, #118, #119, #120!

[rartych]

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.

[jlurien]

@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.

[hdamker]

@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?

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]

@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?

[jlurien]

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.

[shilpa-padgaonkar]

Thank you for your contribution to the commonalities glossary. https://github.com/camaraproject/WorkingGroups/blob/main/Commonalities/documentation/Glossary.md