Open APIs

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"
    }
],

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

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.

"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"  }]