Stream: graphql
Topic: flatten breaks spec?
Anthony Master (Jul 20 2021 at 16:22):
I am learning HL7/FHIR and come from a web app development background that uses GraphQL/React/Next.JS
Having a very good understanding of GraphQL and the specification both building GraphQL API's and consuming auto generated API's I am seeing the flatten directive for the first time. Dgraph (which can generate a GraphQL API) has the concept in it's DQL language construct but it has not been able to represent it in GraphQL. SO seeing this I decided to jump in here. I am being considered for a position as a Interface Specialist and wanted to get my hands dirty before I accept the position. The position is mainly using MIRTH with Javascript and MySQL which I have strong fundamentals with JS and SQL.
My pending question back to this OP is how does the flatten directive not break the GraphQL specification? Is there anyone that has successfully implemented this directive in their API? And then I have a few more questions regarding its implementation if anyone is interested in helping out a newby in FHIR.
Matt Printz (Jul 20 2021 at 17:14):
Is your concern with the usage, or just the deviation from the strict specification?
As this is an optional directive, I think it is meant as a convenience, in the cases where one thinks it useful.
The directive is not required and if it violates the spec, I believe you are free to not implement/ignore/disable it.
That said, I don't know the GraphQL spec well enough to say if it definitively does or does not break the spec. I can see how it might, but I'm not sure. Do you have a reference to the part of the GraphQL spec that you are thinking this violates?
Josh Mandel (Jul 20 2021 at 17:38):
http://spec.graphql.org/draft/#sec-Language.Directives seems quite open-ended and flexible; I can imagine this poses challenges for interop (e.g., how do you programmatically describe expected schema changes in light of arbitrary @-directives?) but I don't see anything forbidden or "off the table".
Anthony Master (Jul 20 2021 at 21:10):
Matt Printz said:
Do you have a reference to the part of the GraphQL spec that you are thinking this violates?
Spec section 1: To achieve congruence with the structure of these applications, a GraphQL query itself is structured hierarchically. The query is shaped just like the data it returns
Also section 1: Every GraphQL server defines an application‐specific type system. Queries are executed within the context of that type system. Given a query, tools can ensure that the query is both syntactically correct and valid within the GraphQL type system before execution, i.e. at development time, and the server can make certain guarantees about the shape and nature of the response.
5.7.3 Directives are used to describe some metadata or behavioral change on the definition they apply to
So if the flatten directive changes the structure of the response, then it breaks a principle of GraphQL in section 1. If the response cannot be guaranteed, then it breaks another principle in section 1. And if a directive restructures the response instead of performing a metadata or behavioral change on the definition they apply to then it is also breaking 5.7.3 IMO. So by applying a directive on a field, I can expect it to modify that field, as long as the response is still guaranteed (String field is still a string field), but it cannot return some other field structure
that was not in the original query hierarchy.
I understand implementing the directive is optional and not required, but wouldn't any API implementing this directive make it out of spec and less compatible with GraphQL clients and tools?
Anthony Master (Jul 20 2021 at 21:15):
Another major concern from implementing this would be ambiguous responses. From my very brief understanding, nothing in HL7 or FHIR is allowed to be ambiguous. I might be wrong about FHIR, if I am please correct me. But again from the example page flattening the response of 3 unique patients then returns 5 given names and 2 family names without any form of blocking to represent which given names belong together and which related patient was missing a given name. If the example allowed for a null response in the family name that would make more sense if the directive was even in spec in the first place. This portion of the spec just seems to be an ill-formed draft and needs revisions and corrections to be compatible and usable.
I am probably still missing some larger scale use of this flatten directive if it is implemented anywhere, but the example use case does not give it justice in this form.
Lloyd McKenzie (Jul 20 2021 at 21:23):
Flattening can make data unsafe, but then again, so can filtering out modifier elements or other things that provide context. Flattening is there because, from a UI perspective, there are times when removing nesting structures makes for simpler code. GraphQL on FHIR is generally a one-way trip. There is little to no expectation that updates could flow back. Certainly if that was your intention, flatten couldn't be used.
Anthony Master (Jul 20 2021 at 21:29):
Lloyd McKenzie said:
Flattening can make data unsafe, but then again, so can filtering out modifier elements or other things that provide context. Flattening is there because, from a UI perspective, there are times when removing nesting structures makes for simpler code. GraphQL on FHIR is generally a one-way trip. There is little to no expectation that updates could flow back. Certainly if that was your intention, flatten couldn't be used.
makes sense. I suppose a server would never be known to be out of spec giving out a mismatched response vs query unless a client told was expecting something particular and it was not guaranteed. So this falls back onto a client problem. For any kind of client that is just consuming the raw data like a fetch request without implementing any kind of client cache that was not a strongly typed client such as something built with typescript and strongly typed, it wouldn't make a difference. The main thing would be that the client knew what it was getting by adding the directive and what to expect. anything past that is not on the fault of the server but the client because it asked for it flattened.
Bottom line, it would work until you tried to use the flatten directive to build some kind of strongly typed application layer or client side cache or need to perform later updates on queried data.
Carter Cao (Aug 06 2021 at 13:52):
I am using @graphql-mesh/fhir as handler, I see some values get returned have been capitalized when I try to fetch FHIR resource, like 'gender' in Patient resource shows 'Female', not 'female', any suggestion?
Matt Printz (Aug 06 2021 at 15:26):
@Carter Cao I think you're pulling the "Display" value instead of the "Code" value.
Carter Cao (Aug 06 2021 at 17:23):
i am just displaying the resource from fhir server using GraphQL. In FHIR server the gender is 'female', looks like mesh fhir handler convert it to 'Female'
Last updated: Apr 12 2022 at 19:14 UTC
