Clarification on Single Instance Limit for Collection Data Items in PDS API

Hi,

While reviewing the API catalogue documentation for updating PDS records, I noticed that several collection data items (e.g., names, addresses, telecoms) specify that a patient should only have one instance at a time.

For example: “A patient should only have one instance of each telecom value on their record at a time.”

Could you clarify whether this “one instance” rule takes into account the validity period of the data item?

For instance, if a patient previously had a home phone number with a period end date in the past, would it be acceptable to add a new home phone number with a current validity period (e.g., starting today with no end date)? Or is the expectation that the existing home phone number should be updated—overwriting the previous value and adjusting the period accordingly?

Any guidance on this would be greatly appreciated.

Hi,

In short, no. If there is an instance of that data item present, regardless of the value(s) in the period object, that should be the only occurrence.

No, there is no expectation that you overwrite particular fields in the data item.

If a single-cardinality data item is to be updated, such as a home phone number for which there should only be one on a PDS record, you can

  • replace the requisite values or
  • remove the current home number and add a completely new object.

Either is permissible.

Hi David,

Thank you for the clarification, the first point does make it more simple for an implementation to reason about

happy to support remove then add, but there are some follow-up questions:

  • can we remove then add in the same patch request? i.e. remove a home phone and then add a new home phone, in that order within the array of patch commands?
  • I assume remove then add would not apply to usual name, given we are not permitted to remove a usual name?

No worries.

As to your follow-up questions:

Yes.

You can remove and add the usual name.

In the PDS FHIR docs,

  • cannot remove the usual name.

means, you cannot remove the usual name without replacing it (or rather, there must always be exactly one usual name).