Open APIs

 View Only

  • 1.  relatedParty array and uniqueness of the id in each object in the array

    Posted Sep 11, 2025 13:35

    Hi All,

    a vendor just told me that a relatedParty array like the following is illegal because the same 'id' can not be used more than once, given that the 'id' must be unique. I disagree, because the 'id' (and 'href') are in this case just references to a managed entity, and uniqueness applies only to that entity id. What do you think? If there were such limitation, the resulting systems would be very restricted.

    "relatedParty": [
    {
        "id": "54",
        "href": "https://serverRoot/tmf-api/party/v4/individual/54",
        "name": "Carlos Mafalda",
        "role": "director",
        "@referredType": "individual"
    },
    {
        "id": "54",
        "href": "https://serverRoot/tmf-api/party/v4/individual/54",
        "name": "Carlos Mafalda",
        "role": "shareholder",
        "@referredType": "individual"
    }
],


    ------------------------------
    Jesus Ruiz
    TO BE VERIFIED
    ------------------------------


  • 2.  RE: relatedParty array and uniqueness of the id in each object in the array

    TM Forum Member
    Posted Sep 12, 2025 02:36
    Hello Jesús,
     
    From my perspective, since the only mandatory fields in a reference are the href and the id, it makes sense that this pair should be unique. I have not seen this explicitly stated anywhere, but if you look at the second volume of the TMF630 API Design Guidelines v4.0.0, you can find some hints.
     
    In fact, in the example starting on page 32, you can see a list of references to parties where an identifier is repeated (but with a different href). This makes complete sense, as references can originate from multiple sources, and the identifier should be unique within each source, but cannot be guaranteed to be unique across all of them.
     
    Anyway, that is my perspective - I hope it helps.
     
    Best regards,


    ------------------------------
    Abel Ruiz Huerta
    alvatross
    ------------------------------

    Original Message


  • 3.  RE: relatedParty array and uniqueness of the id in each object in the array

    TM Forum Member
    Posted Sep 12, 2025 04:38
    Edited by Matthieu Hattab Sep 12, 2025 04:50

    Hello,

    In general, arrays are not sets, you can repeat values as much as you like, even identical objects. There's no schema-level uniqueness enforced by JSON.

    I really doubt TMF APIs would enforce this. I've seen examples of relatedParty array with duplicate Party Id.

    In v4 APIs the generic RelatedParty object is a polymorphic reference. You choose what the id/href point to by setting @referredType.

    If you vendor require unicity in the array, use PartyRole instead, with your example:

    "relatedParty": [
  {
    "id": "pr-54-director",
    "href": "https://serverRoot/tmf-api/partyRole/v4/partyRole/pr-54-director",
    "name": "Director role of Carlos Mafalda",
    "role": "director",
    "@referredType": "PartyRole",
    "@type": "RelatedParty",
    "@baseType": "unknown"
  },
  {
    "id": "pr-54-shareholder",
    "href": "https://serverRoot/tmf-api/partyRole/v4/partyRole/pr-54-shareholder",
    "name": "Shareholder role of Carlos Mafalda",
    "role": "shareholder",
    "@referredType": "PartyRole",
    "@type": "RelatedParty",
    "@baseType": "unknown"
  }
]

    Now you have unique Ids in the array by referencing the partyRole managed entity (role+party together) and not the party.

    But the meaning is different you no longer have the Party Id (you can get the party Id from the partyrole endpoint)

    You have 2 options to discuss with your vendor.



    ------------------------------
    Kind regards,

    Matthieu Hattab
    Digital Sales Domain Architect
    Lyse Tele AS
    ------------------------------

    Original Message


  • 4.  RE: relatedParty array and uniqueness of the id in each object in the array

    Posted Sep 12, 2025 08:34

    Thanks, Matthieu.

    This is essentially the same reasoning that I am doing: the array elements in relatedParty do not have a uniqueness requirement of the id (or the href, for that matter) within the array, because the id is not the identifier of the entry within the array, but the identifier of the entity being referenced.

    But the documentation is not very clear on that. For example, in TMF630 REST API Design Guidelines Part 1, there are examples without id (which would be forbidden if the array elements had an "identity":

    "relatedParty": [
    {
        "href": " /billManagement/customer/1234",
        "role": "Originator"
    },
    {
        "href": " /partyMangement/individual/1234",
        "role": "Owner"
    }
]

    Maybe this is a third option: do not use id if the vendor has a problem.

    Anyway, thanks again.



    ------------------------------
    Jesus Ruiz
    TO BE VERIFIED
    ------------------------------

    Original Message