Stream: IG creation
Topic: Examples
Bob Milius (Apr 12 2018 at 19:19):
In the examples section of the IG Publisher Documentation, it points to the \build\test\ig which is used for testing the tooling. I notice there are others in that directory as well, e.g., ig10, ig14, ig30, ig40, which I assume are for different releases of FHIR. The current release would be ig and is equivalent to ig30. And ig40 is a version using the new framework approach described in http://wiki.hl7.org/index.php?title=FHIR_IG_Framework.
Is that assumption correct?
Should the most recent version of org.hl7.fhir.igpublisher.jar work on all these examples?
Lloyd McKenzie (Apr 12 2018 at 19:27):
It should...
Eric Haas (Apr 12 2018 at 19:59):
for something a bit fancier you can use mine.
https://github.com/Healthedata1/IG-Template2
Bob Milius (Apr 12 2018 at 20:20):
@Eric Haas thanks! Nicely documented. I'm beginning to understand that while there are rules around the IG and the IG Publisher, there seems to be several approaches to authoring the material to be published.
Lloyd McKenzie (Apr 12 2018 at 20:43):
One of our to-dos is to come up with standard templates for HL7-Int'l developed IGs
Eric Haas (Apr 12 2018 at 20:46):
@ Bob Milius there are some caveats I need to mention. all the profile have 3 included pages that I autogenerate. you need to add them to the folder by hand if you don't. The TOC next to the breadcrumbs is hand generated and can be a pain to create. let me know if you have any questions. it should run right out of the box.
Eric Haas (Apr 12 2018 at 20:48):
@Lloyd McKenzie template wars...
Brian Reinhold (Nov 12 2018 at 13:03):
I would like to be able to place comments in my json examples that can help implementers understand the mappings from IEEE devices to the various resource elements. However, I do not see a way to do this if I enter examples as a resource. On the other hand, if I place the example in an markdown page then I can do it. Would using this approach be considered a violation of the FHIR IG 'look and feel'?
It just that I feel examples can be VERY helpful to implementers especially if one can directly comment on how the specific elements derive from the IEEE concepts.
Grahame Grieve (Nov 12 2018 at 13:21):
you can put comments in XML examples, but not JSON?
Lloyd McKenzie (Nov 12 2018 at 13:31):
That's a limitation of the JSON syntax. It's not anything FHIR can get around.
Brian Reinhold (Nov 12 2018 at 13:32):
you can put comments in XML examples, but not JSON?
There is no 'standard' that I am aware of to place comments in JSON. In my case we have people who know FHIR but don't know IEEE (the majority of readers) but also those who know IEEE but don't know FHIR (a rare breed). Having comments in the examples really helps both sides.
Grahame Grieve (Nov 12 2018 at 13:33):
we like comments in examples. All our examples are XML for that reason
Brian Reinhold (Nov 12 2018 at 13:33):
That's a limitation of the JSON syntax. It's not anything FHIR can get around.
So to get around it can I put my examples as md pages instead of example resources or would this be a breach of contract?
Brian Reinhold (Nov 12 2018 at 13:35):
we like comments in examples. All our examples are XML for that reason
In my case I am using an actual gateway implementation from real PHDs to create the examples (helps eliminate easy-to-make errors when done by hand ... assuming the implementation is right) so it would be very hard to change.
Grahame Grieve (Nov 12 2018 at 13:36):
I generate examples like that and then annotate them
Lloyd McKenzie (Nov 12 2018 at 13:44):
It's important to define your examples as "real" instances so they can be validated. Best practice is to author as XML with comments. That way you get comments plus full validation - and the JSON and RDF versions get generated for you.
Lloyd McKenzie (Nov 12 2018 at 13:45):
Perhaps we could generate the "HTML" view of the JSON with comments too? Not sure how hard that would be...
Brian Reinhold (Nov 12 2018 at 13:46):
It's important to define your examples as "real" instances so they can be validated. Best practice is to author as XML with comments. That way you get comments plus full validation - and the JSON and RDF versions get generated for you.
How do I validate my examples? Does the IG generation do that? Where is that done?
Brian Reinhold (Nov 12 2018 at 13:46):
Perhaps we could generate the "HTML" view of the JSON with comments too? Not sure how hard that would be...
Maybe I can do both. An md page and then a list of resources.
Grahame Grieve (Nov 12 2018 at 13:49):
the IG publisher automatically validates all resources, and puts errors in qa.html in the output directory
Grahame Grieve (Nov 12 2018 at 13:49):
I could generate a JSON variant with comments, yes
Brian Reinhold (Nov 12 2018 at 13:49):
the IG publisher automatically validates all resources, and puts errors in qa.html in the output directory
Learn something new every day! The server must have just gone down. http://build.fhir.org/org.hl7.fhir.igpublisher.jar gives 404 and I cant run the build
Grahame Grieve (Nov 12 2018 at 13:51):
what error do you get?
Brian Reinhold (Nov 12 2018 at 13:52):
what error do you get?
404 Not Found. In the build I get this error
Error opening connection java.io.FileNotFoundException: http://build.fhir.org/org.hl7.fhir.igpublisher.jar
Was working 15 minutes ago.
Grahame Grieve (Nov 12 2018 at 13:53):
..works for me...
Lloyd McKenzie (Nov 12 2018 at 13:54):
Ditto. Perhaps a transitory network issue?
Brian Reinhold (Nov 12 2018 at 13:54):
..works for me...
looks like its back ... still waiting for a response but when the error came it was immediate.
Lloyd McKenzie (Nov 12 2018 at 13:55):
Note that your examples need to actually be referenced by your IG in order for them to validate (or publish properly)
Brian Reinhold (Nov 12 2018 at 13:57):
Note that your examples need to actually be referenced by your IG in order for them to validate (or publish properly)
The single example I have so far DOES do that and it creates the rather intense display in the artifacts window
Eric Haas (Nov 12 2018 at 19:36):
you can create your own pseudo comments in Jekyll using markdown for code blocks which will display in red (as errors )
for example
{ "foo"; "bar" \\adding comment here is shown as a error in jekyll, }
Sarah Gaunt (Jan 13 2020 at 03:00):
DELETED - issue was my fault!
Sarah Gaunt (Jan 13 2020 at 03:09):
IGNORE! I think I have an issue with that Encounter profile! My bad...
Last updated: Apr 12 2022 at 19:14 UTC
