STU3 vs. XDS Oddities in DocumentReference

Having been working on an MHD project, I’ve spotted a few oddities about how the DocumentReference resource has been constructed, including what I believe to be a misunderstanding about how the XDS class and types codes are intended to be used.

The normal expectation in XDS is that broad “classCode” (FHIR Documentreference.class) should be the broad “inclusive” categorisation which users would utilize for searching, with the typeCode(FHIR Documentreference.type) being a much finer specificaiton used primarily for “display”, allowing a user to pick what might be of interest. I’d be the first to accept that the IHE specificaitons are rather ill-defined in this respect, but amonst those of us who have been using XDS for the last decade it is “common knowledge”. In the vast majority of respects, the alignment between the Documentreference resource and XDS is extremely good (even including wierd and confusingly named fields such a practiSettingCode!), but for these 2 particular fields, there are 2 problems:

  1. DocumentReference.class is optional. Clearly this is a problem for interoperability via MHD between the two. It can of course be “hacked” with a server-side type=>class mapping, but this does seem odd, given how well the rest of the content is aligned. Is there a good rationale for this decision?

  2. The STU3 descriptions of these fields appear to be reversed:

  • class (in “requirements” ! ) : Helps humans to assess whether the document is of interest when viewing a list of documents.
  • type (in Comments) : Key metadata element describing the document, used in searching/filtering.

At the very least, it would be nice to see standardisation on comments/requirements, but much more importantly the conflict between these uses and the normal expected XDS use, combined with the cardinality of “class” seems to create a significant and avoidable barrier between XDS & FHIR interoperability.

Am I “late to the party”, having missed discussions as to why this has turned out the way it has, or have I just spotted a genuine mistake?

DocumentReference is used in FHIR for more than just XDS. I think the MHD profile makes DocumentReference.class mandatory, but it’s not necessary in other contexts where DocumentReference is used. I’ll ask the MHD author to comment further.

As a core resource everything is optional. The intention is that MHD makes things like the cardinality clear. I think it says that as well as it can today. IHE is working on structureDefinition (s) so it is even more clear.

You are not late at all… please give us recommendation for issues. What would you like class and type to say?


Thanks both of you for the very quick responses. Putting what you say together with what I see as needs here and as guidance for similar implementers, my suggestions are that the comments/requirements for these fields in STU3 be changed as follows:

  1. Remove the “requirements” info for class

  2. In comments for class it should say:
    a. Key metadata element describing the document, used in searching/filtering.
    b. Profiles intended for interoperability with XDS via MHD should consider changing the cardinality to 1…1

  3. In comments for type is should say:
    Helps humans to assess whether the document is of interest when viewing a list of documents.

Does this make sense, or would my proposal (especially the one on cardinality) break the profiling rules?


Good suggestion. Can you put that in a CR? There are some changes that will be discussed today at the workgroup meeting. I think some of your suggestions are in that group.

Take a look at the current build. There was a block vote at the workgroup meeting that resulted in some cleanup. Including relaxing cardionality. I am still not sure I understand the type vs class confusion. class is to be a higher-level concept, where type is to be a specific concept within that higher class. There is no normative definition of this ontology, as it is today managed within a domain (e.g. XDS Affinity Domain). An example value-set might be useful, but could only be an example.