Possible rename of the response property phoneNumChanged

[maxl2287]

Problem description
After getting in touch with this API for the first time, I was slightly confused about the naming of the property phoneNumChanged in the response.
The current property name phoneNumChanged in the API response may cause confusion because it implies that the phone number itself has changed, which is not accurate.
The intent of this property is to indicate whether the subscriber associated with the phone number has changed.

Possible evolution
Rename the property to something more descriptive and aligned with its actual purpose and to have a better alignment between the property name and its actual functionality.
Suggested alternatives may be:

• subscriberChanged
• isSubscriberChanged
• phoneNumberRecycled
• isNumberRecycled
• etc.

Additional context

        phoneNumChanged:
          type: boolean
          description: |
            Set to true (Boolean, not string) when there has been a change in the subscriber associated with the specific phone number after “specifiedDate”.

[yamamoto0104]

Dear @maxl2287, Thank you for your suggestion.
The YAML file has been discussed over the past three months and merged. The attribute name was agreed upon in the early stages. We also discussed similar issue (#19) and closed last month.
Therefore, I would like to proceed as is.
I understand that this does not breach any regulations.

[maxl2287]

Maybe we can discuss about it for the release after the upcoming.
As already @bigludo7 has raised up this issue in #19 I think it's worth to discuss about it.

From my point-of-view it still could look like that the "phone number has changed" instead of the actual subscriber.
I appreciate to not put it in the Release r1.1, but we need to find here a better naming.

BR
Max

[yamamoto0104]

@maxl2287
I'm fine with discussing the naming for the next release. However, it might be a good idea to discuss the naming rules in Commonalities before discussing this issue because there is no clear rule for naming in the API design guidelines. It's a bit difficult for us to reach a consensus on the naming issue without a common rule.

[eric-murray]

Converting this to a discussion, as it is not yet an "issue". If a conclusion is reached in the discussion that there is a issue here, then an new issue can be created accordingly.

[hdamker]

Converting this to a discussion, as it is not yet an "issue". If a conclusion is reached in the discussion that there is a issue here, then an new issue can be created accordingly.

@eric-murray I don't agree that this isn't an issue for the current release in Spring25. Without a proper parameter name which is reflecting the right semantic the API definition will be useless for us at DT. Changing the parameter name only in Fall25 will be a breaking change which can be avoided by changing it now before the first release candidate.

From my (DT) perspective this is an issue which needs to be corrected before the release candidate.

[eric-murray]

Maybe it does qualify as an issue, but the original issue as raised did not:

• The topic of the property name was never brought to and actively discussed in any KYC meeting
• The issue, and indeed the one raised by Ludovic, were noted in the meeting minutes, but there was no active discussion or opinions expressed in the meetings
• The issue was not raised by a maintainer of the API
• The language really suggested this was just a question for discussion:

  After getting in touch with this API for the first time, I was slightly confused ...
  The current property name ... may cause confusion

Priority issues for DT should ideally be raised by a maintainer and flagged as such, and certainly should be actively discussed in the meetings

[hdamker]

@eric-murray Thanks for the explanation, I get fully your points that on the time of the transfer it looked from your perspective like a discussion. My perspective was different as I had the internal DT background and wasn't aware that @maxl2287 has no official role here in this repository - he is e.g. maintainer in DeviceStatus and DeviceLocation and active in Commonalities.

After @Noel-Wirzius-DT and also @bigludo7 have confirmed that it is an issue for them, what is your proposed way to handle it again as an issue?

[eric-murray]

Hi @hdamker

As the next KYC meeting is not until 18th February, we need to resolve this offline within the github comments. I will convert back to an issue, which should maintain the current comment thread.

I would look to @yamamoto0104 to come back with a specific proposal. If consensus cannot be reached, we need to have a vote between the maintainers.

Vodafone's opinion would be key to such a vote. Personally, I don't have an opinion as I only have a technical role here to support progress of this API and its compliance with the API design guidelines. I'll tag our product manager (and maintainer) @luislopezcorpas for his opinion.

[Noel-Wirzius-DT]

I see some ambiguity in the naming, even for the initial release. The attribute name doesn’t align with the value being returned, which could lead to a poor developer experience.

For example, PhoneNumChanged suggests that the phone number itself has changed, but in this case, we’re dealing with the recycling status of an MSISDN. The phone number isn’t changing—what’s changing is the status or the customer associated with it.

To improve clarity, I’d recommend using phoneNumberRecycled or isNumberRecycled, even for the first release. These names more accurately reflect the status being tracked.

The other options from @maxl2287 seem to imply a relationship with a "contract," which could be confusing in this context.

[yamamoto0104]

Thank for your feedback.
This might be a repetitive answer, but the YAML file has been discussed over the past three months and merged. The attribute name was agreed upon in the early stages. We also discussed similar issue #19 and closed.
Therefore, I would like to proceed as is.
I understand that this does not breach any regulations.

[maxl2287]

@yamamoto0104 I understand that the YAML file has been discussed over the past three months and that the attribute name was agreed upon in the early stages. However, this does not mean that it cannot or should not be improved. The goal should always be to ensure clarity and a good developer experience.

Again - while I understand the decision to shorten "phoneNumberChanged," the core issue is not just the abbreviation, but that the name does not accurately describe the property’s purpose. It implies that the phone number itself has changed, rather than indicating a change in the subscriber or the recycling status of the MSISDN.

Since at least three people (myself, @bigludo7 and @Noel-Wirzius-DT) have independently found the current name ambiguous, it’s worth considering a more precise name like phoneNumberRecycled or isNumberRecycled to better reflect the actual purpose of the property.

cc @hdamker

[yamamoto0104]

@maxl2287 , As I said, I'm OK to discuss the naming to Autumn 25 Meta release. However, I cannot accept to change the naming at Spring 25 meta release. Because we are developing YAML file and test file based on the feedback from Code owners and Release management teams for the Meta release and the YAML file need to be aligned with ICM and Commonalities. We are also developing our product for Spring 25 meta release.

[hdamker]

@maxl2287 , As I said, I'm OK to discuss the naming to Autumn 25 Meta release. However, I cannot accept to change the naming at Spring 25 meta release. Because we are developing YAML file and test file based on the feedback from Code owners and Release management teams for the Meta release and the YAML file need to be aligned with ICM and Commonalities. We are also developing our product for Spring 25 meta release.

@yamamoto0104 Wouldn't it make more sense to do the change now, before there is even a release candidate of the API approved and released, instead of risking that the Fall25 release will introduce a breaking change for your API consumers when the product is in use? At the current point of time it wouldn't be a change of a released API, as the README of the the repository clearly says:

The repository has no (pre)releases yet, work in progress is within the main branch.

And the template for the CHANGELOG.md, which you rightly used in the release PR, also is clear about that:

Please be aware that the project will have frequent updates to the main branch. There are no compatibility guarantees associated with code in any branch, including main, until it has been released. For example, changes may be reverted before a release is published. For the best results, use the latest published release.

I'm a little bit disappointed that you are only arguing with formal arguments (also in #19) but not responding to the obvious semantic mismatch between the attribute name and the scope and intention of the API. I also don't consider this a case for Commonalities, as this is about the semantic of the specific API.

[bigludo7]

I fully respect the work done by @yamamoto0104 and the team but from Orange perspective we are aligned with DT to consider an attribute name change as soon as possible. Consistency between api is a factor for adoption.

If we want to be formal the §6.2 of the design guideline specify phoneNumber as attribute and we should try to stick to this.

[yamamoto0104]

@hdamker, @eric-murray and @bigludo7
Thank you for your precious comments. We are discussing the issue internally and feedback later.

[hdamker]

The discussion is now back into an issue, please continue within #36

[Masa8106]

This discussion was moved to the issue #36 and the related PR #37 has merged. Therefore, I will close this discussion.