IG-wide review and discussions

[ShahimEssaid]

This is a discussion issue for IG-wide issues that might need to be addressed at some point, and that might come up as we review the current state of the IG. It's a place to share thoughts and get some early feedback without the need to create many separate issues. At some point, and only if needed, separate dedicated issues can be created to dig deeper into a topic.

[ShahimEssaid]

I'd like to refactor how our content is laid out across our FSH files. I briefly looked at what other IG's are doing but I don't think there is one right way for doing this as in the case for the XML/JSON formats. Here are a few thoughts:

• Each "conformance resource" gets its own file. For example, each resource profile will be in a separate file.
• The file name reflects the type of conformance resource and with the name or id appended. For example, the Phenotypic Feature profile will be in a file named "profile-PhenotypicFeature.fsh".
• Should the profile examples be in the same file as the profile? I noticed other IGs doing this, and it kind of makes sense that the examples are with their profiles. If not, we can adopt a file naming pattern that clearly links the example to its profile. For example, "ex-PhenotypicFeature-CHF-with-severity.fsh".

Rationale:

• Easier to find specific items, open them in different editor views, etc.
• The Git change history for a file is more meaningful since it shows the history of one specific item.
• Easier to work on specific tasks in parallel on different items without having to touch the same files causing Git merge issues.
• Easier to submit changes through PRs and have the set of affected files clearly give a sense of which items are being changed.

@julsas thoughts?

[julsas]

Yes, we should do this and refactor to our preferences. There's no right our wrong. But I find the current structure difficult to navigate.

Each "conformance resource" gets its own file. For example, each resource profile will be in a separate file.

+1

The file name reflects the type of conformance resource and with the name or id appended. For example, the Phenotypic Feature profile will be in a file named "profile-PhenotypicFeature.fsh".

+1

Should the profile examples be in the same file as the profile?

I'm not strictly against it, but I prefer separate files and to organize FSH files into subdirectories. Typically I set up a FSH repo similar to this:

my-project
├── input
|   └── fsh
|      └── capabilitystatements
|      └── codesystems
|      └── extensions
|      └── instances
|          ├── example1.fsh
|      └── logicalmodels
|      └── capabilitystatements
|      └── profiles
|          ├── profile1.fsh
|          ├── profile2.fsh
|          └── profile3.fsh
|      └── searchparameters
|      └── valuesets
└── sushi-config.yaml

[ShahimEssaid]

I like the idea of folders per item type. I'm working on pulling out the PhenotypicFeature content accordingly.

How about a convention for "id", "url", "name", and "title"? We're using a mix of patterns for "id" especially for the instances. This also affects our canonical URLs. Let's discuss today, adopt some conventions, and do all the breaking changes all at once.