FHIR Chat · application/yaml content type for fhir · implementers

Stream: implementers

Topic: application/yaml content type for fhir

Andrew Tropin (Oct 10 2018 at 14:16):

I can't find any discussion about yaml for fhir, but it seems logical to add following content-types to fhir spec:

• application/fhir+yaml
• appliaction/yaml

yaml subset isomorphic to json (can be converted from one format to another and vice versa without any additional meta-information) and adding yaml support will be very cheap, but yaml less verbose and therefore more human-readable. In additional to compactness and readability yaml is used in many huge opensource projects like kubernetes and also, pretty popular among web developers.

Here example of the same resource in both formats:

application/json:

  {
   "resource": {
    "name": [
     {
      "given": [
       "Peter"
      ]
     }
    ],
    "id": "1882cce7-dd00-4c9d-a1f5-adc5f6747955",
    "resourceType": "Patient",
    "meta": {
     "lastUpdated": "2018-09-19T17:44:01.252Z",
     "versionId": "167",
     "tag": [
      {
       "system": "https://aidbox.io",
       "code": "created"
      }
     ]
    }
   }
  }

application/yaml:

  - resource:
      name:
        - given:
            - Peter
      id: 1882cce7-dd00-4c9d-a1f5-adc5f6747955
      resourceType: Patient
      meta:
        lastUpdated: '2018-09-19T17:44:01.252Z'
        versionId: '167'
        tag:
          - system: 'https://aidbox.io'
            code: created

To play with both formats visit https://www.json2yaml.com/

@Lloyd McKenzie Is it possible that yaml will appear in fhir spec in near future?
@Grahame Grieve yaml supports comments and multiline strings ;)

Lloyd McKenzie (Oct 10 2018 at 14:58):

All things are possible. However, every new syntax imposes an additional burden on implementers and/or further fragments the interoperability community. Our objective is to drive standardization, which in most situations means reducing the number of available options. The syntaxes we support right now are there because they address the needs of different communities and/or their technology stacks have capabilities that can't be easily replicated elsewhere. It's not clear whether those criteria apply to YAML. If we were to introduce it, it would need to be something we'd explore in R5. The door is closed for such major enhancements for R4.

Grahame Grieve (Oct 10 2018 at 16:57):

it's possible... if enough people ask for it. It's not disallowed.

nicola (RIO/SS) (Oct 10 2018 at 19:29):

yaml is popular for API- human interaction - kubernetes, ansible, OpenAPI use it.
It's almost free because of isomorphism with json and mature libraries for all languages - so it's easy for implementers add one dependency and couple lines of code to support it :)

nicola (RIO/SS) (Oct 10 2018 at 19:30):

technically it's just json dialect :)

nicola (RIO/SS) (Oct 10 2018 at 19:31):

not heavyweight new format like xml or rdf

Grahame Grieve (Oct 10 2018 at 19:34):

it's more than a couple of lines of code for me to support it

nicola (RIO/SS) (Oct 10 2018 at 19:34):

Why?

Grahame Grieve (Oct 10 2018 at 19:35):

I don't have a YAML parser at hand.

nicola (RIO/SS) (Oct 10 2018 at 19:36):

Do you mean delphi?

nicola (RIO/SS) (Oct 10 2018 at 19:37):

@Grahame Grieve yaml has comments!

Lloyd McKenzie (Oct 10 2018 at 19:39):

The question for me is: "What community does it give us access to that the existing formats don't; or What capabilities does it enable that the other formats don't?" The benefit provided would need to outweigh the additional impact on the implementer community to support another syntax. "It's easy", "It's close to JSON" and "It's popular" don't answer those questions. "It's more concise than JSON" is a possible benefit, but it's not clear to me that the byte reduction on a compressed stream would be more than a percentage point or so, if that. If that plus the slight improvement in human-readability are the only benefits, it's not clear to me that it'd be worth it. However, I'm just one opinion. Are there other benefits YAML would bring to the table that wouldn't be supported by the other syntaxes?

nicola (RIO/SS) (Oct 10 2018 at 19:42):

http://sangsoonam.github.io/2017/03/13/yaml-vs-json.html - it's machine readable format for human. I predict, it will be actively used in all education tracks and materials because of readability and less-type. It looks not big deal at first glance - but it is!

nicola (RIO/SS) (Oct 10 2018 at 19:47):

For example, all kubernetes tutorials switched to yaml from json.

nicola (RIO/SS) (Oct 10 2018 at 19:49):

Or checkout this - https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.1.md. In less formal Open API docs you will see only yaml

nicola (RIO/SS) (Oct 10 2018 at 19:54):

I'm pretty sure we have to sell FHIR to modern web developers. And yaml is a small but sweet feature, they will expect from API specification.

Michele Mottini (Oct 10 2018 at 21:17):

Aren't the serialization formats going to be normative in R4 ? ...and so no additions / changes to the existing JSON and XML?

nicola (RIO/SS) (Oct 10 2018 at 21:19):

We do not need make yaml normative - let it be draft forever :)

Grahame Grieve (Oct 10 2018 at 21:45):

we can still add new formats if we want

Lloyd McKenzie (Oct 10 2018 at 22:35):

In theory we could deprecate a format at some point too. And different formats will be at different stages. JSON and XML are going Normative, but RDF is still STU in R4.

Grahame Grieve (Oct 10 2018 at 22:36):

.. and will be for a long time....

Andrew Patterson (Oct 11 2018 at 03:09):

I find YAML very useful because of the comments.. so for config files or examples - even though these are going to end up in an object model that is no more complex than json/xml (i.e. the comments are not part of the serialization).. having the ability to add comments is fantastic for documentation

Alejandro Metke (Oct 11 2018 at 03:39):

@Lloyd McKenzie I think YAML would be interesting for the genomics research community. I am part of the GA4GH Clinical & Phenotypic Data Capture Work Stream and I've been pushing the use of FHIR as a potential replacement of other standards such as Phenopackets (http://phenopackets.org/). Most of the arguments against using FHIR are around complexity (which by the way I don't agree with). I think a YAML rendering of FHIR would bring the perceived complexity down and might make it easier to author small snippets of information by hand (which apparently is something that some users want to do).

Grahame Grieve (Oct 11 2018 at 03:40):

it's a classic trade-off. Working with other users brings the advantage of collaboration but also means you deal with their uses as well as your own.

Philip Wilford (Oct 11 2018 at 03:43):

Hey Alejandro,
Keep me in the loop re Genomics. Would be good to understand where this is heading.

Alejandro Metke (Oct 11 2018 at 03:45):

Hey Alejandro,
Keep me in the loop re Genomics. Would be good to understand where this is heading.

Sure, will do.

Philip Wilford (Oct 11 2018 at 03:49):

Thanks

John Silva (Oct 11 2018 at 11:43):

I understand that there are converters back and forth between JSON and YAML but the thing I don't like about YAML is that the spacing matters and it's hard to see that 'by eye'. So, if you are hand-creating YAML files or even editing an existing one (by hand), it is very easy to 'mess it up' and then get some nondescript error when you go to use this. This has happened to me many times with YAML files for docker-compose! So, other than comments in YAML, I'm not sure of it's benefits compared to JSON.

Last updated: Apr 12 2022 at 19:14 UTC