FHIR defines a useful framework for adding/updating/removing Tags against resource instances. A tag is a pair of URLs (a scheme, and a term) which can optionally have a textual "label" as well.

A specific resource instance's tags can be found in the resource metadata map, using the key of ResourceMetadataKeyEnum.TAG_LIST. The following example shows how to access the tags in a client following a "read" operation:

      IGenericClient client = FhirContext.forDstu2().newRestfulGenericClient("http://fhir.healthintersections.com.au/open");
      Patient p = client.read(Patient.class, "1");

      // Retrieve the list of tags from the resource metadata
      TagList tags = ResourceMetadataKeyEnum.TAG_LIST.get(p);

      // tags may be null if no tags were read in
      if (tags == null) {
         System.out.println("No tags!");
      } else {

         // You may iterate over all the tags
         for (Tag next : tags) {
            System.out.println(next.getScheme() + " - " + next.getTerm());

         // You may also get a list of tags matching a given scheme
         List<Tag> someTags = tags.getTagsWithScheme("http://hl7.org/fhir/tag");
         // Or a specific tag (by scheme and term)
         Tag specificTag = tags.getTag("http://hl7.org/fhir/tag", "http://foo");

Adding Tags to a Resource

In a server implementation, you might want to add tags to a resource being returned. This is done by adding a TagList instance to the resource's metadata, as shown in the example below.

The server will then do the "right thing" with the tags. If the method is for a search operation, the tags will be added to the category element in the returned bundle. If the method is for a read operation, the tags will be added to the response "Category" headers.

   public List<Patient> getAllPatients() {
      ArrayList<Patient> retVal = new ArrayList<Patient>();
      // Create a patient to return
      Patient patient = new Patient();
      // Create a tag list and add it to the resource
      TagList tags = new TagList();
      ResourceMetadataKeyEnum.TAG_LIST.put(patient, tags);

      // Add some tags to the list
      tags.addTag(Tag.HL7_ORG_FHIR_TAG, "http://foo/tag1.html", "Some tag");
      tags.addTag(Tag.HL7_ORG_FHIR_TAG, "http://foo/tag2.html", "Another tag");
      return retVal;