Update Glossary.md

[shilpa-padgaonkar]

This change extends the glossary document so that it not only explains the meaning of the terms already used in the APIs/documentations but also suggests developer friendly alternatives for existing identifiers which if agreed within our Camara project, can be replaced from current APIs and documentation

Fixes #108

[shilpa-padgaonkar]

Issues have been created under every subproject to add their updates to the PR
camaraproject/QualityOnDemand#90
camaraproject/HomeDevicesQoD#20
camaraproject/EdgeCloud#54
camaraproject/DeviceLocation#12
camaraproject/OTPValidation#11
camaraproject/NumberVerification#10
camaraproject/DeviceStatus#15
camaraproject/SimSwap#11
camaraproject/CarrierBillingCheckOut#45
https://github.com/camaraproject/AnonymisedSubscriberIdentifier/issues/4
camaraproject/DeviceIdentifier#4

[FabrizioMoggio]

A closed bracket is needed in the third column "Usage(API/Documentation)".

Anyway I'm wondering about that column.
I suggest to discriminate on "Parameters" and "Terms". I mean we can have a text like this in the documentation: "The UeId parameter represents the User Equipment". In the Glossary I think it is important to first work on the Term (User Equipment) and then we can also suggest to adopt a common Paramenter name.

So:

Current:
Term: User Equipment
Paramenter: UeId
Suggested:
Term: Device
Parameter: DevId

"Term" is used to describe the "Paramenter", in the YAML and in the Documentation.

[shilpa-padgaonkar]

@FabrizioMoggio : The Intention is to not create too many documents that we would have to refer to in the end. Hence, a consolidated Glossary. I have changed the format of the doc slightly, which I hope would address your concerns.

[FabrizioMoggio]

@shilpa-padgaonkar: thank you, the modified table addresses my comment. Just one more comment, in my understanding the last column is to propose a possible alternative for the Parameter/Field. So, maybe, it should be:

"Alternative developer-friendly Parameter/Filed"

[eric-murray]

I agree a glossary would be useful, but I think the initial definitions need a bit more thought. In particular, whilst I can't really argue with "Device Identifier" being "Identifier for a device", this doesn't really capture how APIs are using this identifier.

In most cases, the identifier is actually being used to identify the mobile subscription. For most APIs, if the SIM was moved to a different UE, the behaviour of the API would be unchanged, because it is the mobile subscription that is relevant. That is why it is called the "Anonymised Subscriber Identifier" API, and not the "Anonymised Device Identifier" API. Moving your SIM to a different UE doesn't change the identity you get back.

But there is a Device Identifier API, which returns IMEI. So changing UE changes the response of the API. In that case, the device identifier is not a "UEId", but is still a "Device Identifier".

I think the trick is to come up with definitions for the glossary that allow developers who do not fully understand the distinction between a "mobile device" and a "mobile subscription" to understand that distinction where it affects how the API is used.

[shilpa-padgaonkar]

@eric-murray Those are just sample entries as stated in the note at the end of the document. Issues have been created under every subproject to add the real/actual entries they need with a description that accurately reflects the usage of the specified identifier. Feel free to update the entries as deemed fit.

I agree with your point that we would need to put more thought into some of the tricky terms/fields.
But IMHO, it will be difficult to start with perfect terms and descriptions. They will be refined over the course of time as we start adding to the Glossary and it will be a living document for the project which matures over time.

[jordonezlucena]

@shilpa-padgaonkar: thanks for creating this PR. I agree we need to populate (and enhance) the table over course, as we get inputs from the Sub-Project leaders.
Two suggestions on the proposed table:

• Add a new column called "In-scope APIs", just after or before "Usage in API (Parameter/Field)" column. This new column aims to list the CAMARA APIs that make use of this term.
• Re-name "description" column to "definition". When providing the term definition, encourage contributor to include reference to relevant standard/industry fora (e.g., GSMA, ITU, 3GPP, IETF) where this term was originally defined.

[shilpa-padgaonkar]

@jordonezlucena : I can update description to definition.
For your first point, I can add the column, but I do wonder if all APIs will update this glossary regularly and keep it up to date or will it go stale over time! Also, we will then be expected to mention all the documentations where a term has been used (thereby making the list too long)?

[jordonezlucena]

@jordonezlucena : I can update description to definition.
For your first point, I can add the column, but I do wonder if all APIs will update this glossary regularly and keep it up to date or will it go stale over time! Also, we will then be expected to mention all the documentations where a term has been used (thereby making the list too long)?

My point is that, e.g. for "UeId", note that the API family "x", "y" and "z" make use of them. I'd not expect too many APIs make use of the same parameter. Anyway, we can try it out, and if we realise that it's quite complicated to keep this information updated, we can simply remove this column.

[shilpa-padgaonkar]

@PedroDiez and @eric-murray : Could you kindly update your contributions to use camelCase? I will then consolidate the contributions from other subprojects here myself.

[PedroDiez]

done @shilpa-padgaonkar