FHIR Chat · Documenting Custom(-ish) Resources · hapi

Stream: hapi

Topic: Documenting Custom(-ish) Resources

Karl M. Davis (Dec 28 2017 at 17:01):

Very general question here: How are folks documenting their resources? In our case:

• We use HAPI as a RESTful server facade in front of our DB.
• Let's just talk about our Patient data...
• We are only using a small subset of the available Patient fields. In addition, we're using a couple of extension fields to capture data that doesn't fit into the base Patient resource type.

I imagine pretty much everyone is in a similar situation there. But what would folks recommend we do for documenting what our Patient resources look like? We want consumers of our FHIR API to know what to expect.

Karl M. Davis (Dec 28 2017 at 17:05):

I know very little about them, but perhaps folks are using FHIR profiles for this? If so, is there any implementation guidance available on how to get started using custom profiles with HAPI and to generate documentation?

Karl M. Davis (Dec 28 2017 at 17:06):

(And Happy Holidays to all! Thanks in advance for any guidance you can provide.)

Christiaan Knaap (Dec 28 2017 at 19:36):

I'm not an expert on HAPI, but the gist of going about this is IMHO:
- define what a Patient from your system looks like in a profile (most people use Forge to do so)
- include definitions for the extensions you had to invent (and are they special to your situation or more general / reusable / already existing)
- do the same for any other resourcetypes you serve
- publish them for others to find / read / download, e.g. on Simplifier.net
- assemble them in an Implementation Guide.
- adjust your CapabilityStatement to mention the custom profiles
That way the outside world will know what your FHIR Facade will serve.

I have not heard of creating Java code out of custom profiles, but since the custom elements have to be serialized as extensions anyway that is not a requirement either.

Then you mentioned 'to generate documentation' - what kind of documentation besides the things mentioned above would you like to generate?

Karl M. Davis (Dec 29 2017 at 13:43):

@Christiaan Knaap That's super useful, thanks! I think "assemble them in an Implementation Guide" is the main piece I was missing. That's likely the documentation I was referring to. As an example, I've seen this: http://hl7.org/fhir/us/daf-research/index.html, and wondered how I'd produce something similar.

Do you know where the best place to start learning about how to create an Implementation Guide would be?

(Thanks again!)

Christiaan Knaap (Dec 29 2017 at 14:32):

There are two main tools for creating Implementation Guides:
- IG Editor on Simplifier.net, described in the help
- HL7 IG Publisher, described on the HL7 Wiki

For background: ImplementationGuide is also a resourcetype.

Josh Mandel (Jan 29 2018 at 23:54):

@James Agnew if I do

curl \
 -H "Accept: application/fhir+json" \
 -H "Content-type: application/fhir+json"\
 -X POST\
  https://fhirtest.uhn.ca/baseDstu3/Patient/$validate \
 --data '{"resourceType": "Patient"}'

... should this result in a newly created resource? I thought by default there would be no action, but this is telling me :

  "issue": [
    {
      "severity": "information",
      "code": "informational",
      "diagnostics": "Successfully created resource \"Patient/783176/_history/1\" in 3ms"
    },
    {
      "severity": "information",
      "code": "informational",
      "diagnostics": "No issues detected during validation"
    }
  ]

Josh Mandel (Jan 29 2018 at 23:55):

Also for a payload with multiple errors it appears to be returning only the first (whereas previously it used to return a whole set). Is this by design?

Josh Mandel (Jan 29 2018 at 23:55):

Darn it, I see my $ problem. I need single quotes. Fixing that, I still have the issue that I only learn about a single error...

Josh Mandel (Jan 29 2018 at 23:57):

like {"resourceType": "Patient", "birthDate": 13, "badProp":5} fails on birthDate with no further info.

James Agnew (Jan 30 2018 at 00:55):

Oh that's interesting..... Lemme try and replicate.

Last updated: Apr 12 2022 at 19:14 UTC