Documentation with considerations for upgrading to 5.0

[lmsurpre]

point-in-time analysis is scattered between #2065 and various threads on chat.fhir.org

We should update that analysis when R4B is close to being ready for publication.
maybe a blog post on the project site?

[lmsurpre]

The number 1 issue to highlight is that any existing Evidence or EvidenceVariable could prevent a successful upgrade... these are the only two resource types that exist in both R4 and R4B for which an R4 instance may no longer parse successfully.

In the case of Evidence:

Many new constraints, but all at the "warning" level (shouldn't break anything).

Removed elements:

• name
• shortTitle
• subtitle
• jurisdiction
• effectivePeriod
• topic
• exposureBackground*
• exposureVariant
• outcome

Added elements:

• citeAs
• assertion
• variableDefinition*
• synthesisType
• studyType
• statistic
• certainty

The * indicate required fields.

Because a required field was removed, parsing valid 4.0.1 instances with our updated parser will always result in errors like the following:

com.ibm.fhir.model.parser.exception.FHIRParserException: Unrecognized element: 'exposureBackground' [Evidence]

This can be bypassed by setting the server to "lenient" mode. Or, if using fhir-model directly, by calling parser.setIgnoringUnrecognizedElements(true) before the parse.

However, even in this case, the addition of a new required element will mean that we'll get the following error if we keep parse validation on:

com.ibm.fhir.model.parser.exception.FHIRParserException: Missing required element: 'variableDefinition'

In the case of EvidenceVariable

Removed elements:

• jurisdiction
• copyright
• approvalDate
• lastReviewDate
• effectivePeriod
• topic
• type

Added elements:

• handling
• category

If an R4 instance had any of the removed elements, it would result in a FHIRParser "Unrecognized element" exception (unless the server is set to "lenient" mode).

---

In both cases, element ordering was adjusted...but that should only matter for the XML representation.