Enhancement: Add business-level outcome guidance

[yyeAduna]

It is to implement the common PR: camaraproject/Commonalities#578 for SIMSwap API.

Problem description

The SIM Swap API specification does not include responses for 200 status codes that demonstrate the use of CONTEXT_CODE (e.g., regulatory or privacy restrictions) in business-level outcomes. This issue is propose updating the Simswap API spec with contextCode/contextMessage as SUBJECT_CONTEXT.
This ensures that consumers can see how SUBJECT_CONTEXT(contextCode/contextMessage) are used alongside primary outcome fields in successful responses.

Additional context
This update aligns the API documentation with CAMARA API Design Guide section 3.1 https://github.com/camaraproject/Commonalities/blob/main/documentation/CAMARA-API-Design-Guide.md#31-business-level-outcomes-in-successful-responses, ensuring business-level outcomes are visible and context fields are properly demonstrated. No changes to info.description were deemed necessary at this time.

Possible evolution

In order for the data is understandable machine2machine. It is important to define a semi-standard context_code that applicable to the SimSwap API.

Following are a list of CONTEXT_CODE for SIMSwap API (optionally, it could be an enum to limit the random code to be used):

• NUMBER_DEACTIVATED: The phone number has been cancelled or deactivated. The network cannot provide a recent swap date because the primary subject no longer exists in an active state.

• UNSUPPORTED_MVNO: The number belongs to a Mobile Virtual Network Operator that operates on the host network, but the host network does not have the authority or visibility to share the MVNO's SIM swap logs.

• RESTRICTED_ACCOUNT_TYPE: The number belongs to a corporate, government, or specialized enterprise account where data sharing is restricted by master service agreements.

• CUSTOMER_OPT_OUT: The end-user has explicitly exercised a privacy control (e.g., via their carrier settings) blocking the sharing of network-level authentication data.

• OTHERS

Alternative solution

[bigludo7]

Hello @yyeAduna
This is probably a point to discuss in Commonalities as we should have same behavior whatever the API. I mean your 4 contexts are also relevant for other API - I cc @rartych to get his view.

About the provided UC for Sim Swap:

• CUSTOMER_OPT_OUT: for this one the flow will either stop at the /token request (when the API is used in 3-legs) or via a dedicated 401 Unauthorized in the API response
• NUMBER_DEACTIVATED: today you have a 404 NOT_FOUND
• UNSUPPORTED_MVNO and RESTRICTED_ACCOUNT_TYPE: today we have 422 + SERVICE_NOT_APPLICABLE

I'm not sure adding context is required as you have already the information no? what is the point for an app to know that we cannot deliver last sim swap date because this is an unsupported MVNO or a restricted line?
As OpCo I'm not sure to be confortable to expose more granularity behind the 422 + SERVICE_NOT_APPLICABLE.

Looking for feedbacks from the team...

[albertoramosmonagas]

Hi @yyeAduna, thanks for opening the issue. After reviewing the proposal in more detail, and also align with @bigludo7 comment, I think two different discussion are being mixed here. From my perspective, if this is really a horizontal need, then it should first be discussed in Commonalities rather than solved specifically in SimSwap. In fact, the contexts you propose do not seem exclusive to this API, but potentially applicable to others as well.

Also, for the concrete SimSwap cases you listed, there is already defined behavior today in most cases:

• CUSTOMER_OPT_OUT: in a 3-legged flow, this would normally stop already at the /token request, or otherwise be handled as a 401 Unauthorized.
• NUMBER_DEACTIVATED: today this fits under 404 Not Found.
• UNSUPPORTED_MVNO and RESTRICTED_ACCOUNT_TYPE: today these fit better under 422 + SERVICE_NOT_APPLICABLE.

Because of that, I do not clearly see the value of adding more granularity in a successful response for those cases. From an application consumer perspective, it is not obvious what additional decision could be taken with that level of detail. And from an operator perspective, exposing more granularity behind 422 + SERVICE_NOT_APPLICABLE may even be uncomfortable for privacy, internal policy, or contract simplicity reasons.

In parallel, I am concerned that the issue, as currently written, goes beyond simply “showing examples of business-level outcomes” and in practice opens the door to extending the API semantics with a semi-standard taxonomy specific to SimSwap. I think that adds complexity without a clear need, especially for a stable API.

My preference would be one of these two options:

• bring the discussion about context codes to the Commonalities WG, if this is considered a horizontal requirement, or
• limit any SimSwap change to very narrow documentation / examples only, without introducing an API-specific catalogue of context codes.

Furthermore, this guideline applies primarily to new initial/major releases; for stable APIs, it is optional and evolutionary, not mandatory, and certainly does not justify introducing new semantics without a clear need.

[rartych]

There is open issue to define common guidance when to use 2xx with Context and initial cross-CAMARA analysis prepared by @PedroDiez
@yyeAduna Please have a look at https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/581632006/Informative+-+Business-Level+Outcome+2xx+vs+4xx+scenarios
Ofcourse the input from SimSwap would be helpful to define common guidance.