How does FHIR handle multiline markdown inside JSON?

Question

I am working on a project to get medical data from a laboratory system. We want to use FHIR to serialize the data for exchange.

I am now manually producing a few examples in which I take existing human-readable lab reports and structure them into FHIR, using the JSON representation. Then our team and the lab system's team will use the examples to code the import and export respectively.

I now ran into a weird issue. In FHIR, the DiagnosticReport resource defines a DiagnosticReport.conclusion element of type "markdown". This is compatible with our needs, because our physicians are very strict about the formatting of generated documents. And so I want to preserve the text as it appears in the printed report - including newlines.

The moment I do this, my JSON validator balks, and with good reason. The JSON standard does not allow for multiline strings. But the Markdown standard does not allow for an escaped character that represents a newline. There seem to be solutions to force a new paragraph when rendering in HTML, but they require adding something (a backslash or spaces) to the end of a line in the marked-down input. At the same time, the FHIR standard prescribes this element to be Markdown and not, say, HTML or some other form of formatted text.

I saw a question about multiline strings in Markdown, but the suggested solutions assume that somebody is programming a full system in a given language, and should use an escape sequence recognizable by the language that processes the Markdown. But the whole point of our project is interoperability, and there is a very strong requirement to represent the data in ways independent on the systems that will consume it, while following the relevant standards strictly.

I am aware that the final solution will be less than ideal. But the question is: which of the less-than-ideal options is the preferred one in the FHIR context? I can't be the first person running into that issue. Is there an established practice which the FHIR community follows in such cases?

Answer 1

What you're describing is a situation where you have nested data formats. You are embedding Markdown in JSON.

Consider the Markdown doc

# Foo

"hi"

You have to escape the newline and quotes to make this valid JSON, so the serialized JSON string is

"# Foo\n\n\"hi\""

This is no longer valid Markdown, but that's fine, when you deserialize the JSON and print out the field value it will be.