File names and folder structure

[pieter-edelman-nictiz]

Our current file name scheme is somewhat inconsistent:

• Profiles don't get any prefix
• Extensions are prefixed with "ext-" (this applies to the .id as well)
• ValueSets don't get any prefix
• CodeSystems get the prefix "codesystem-"
• ConceptMaps get the prefix "conceptmap-"
• For SearchParameters the proposal is to use the prefix "searchparameter-" (#139)

In een package zoals de IG Publisher of Simplifier ze maakt, heeft elk bestand de prefix van het type resource inclusief captilisatie. Nu vind ik dat juist voor profielen en extensies niet zo behulpzaam, want die zij beide "StructureDefinition". Mijn voorstel zou zijn (ook met het oog op andere repositories) om:

• profielen en extensies te houden zoals ze zijn maar ze te verplaatsen naar een folder "StructureDefinitions"
• voor alle terminologie-resources deze richtlijn over te nemen en ze te plaatsen in de folder "vocabulary" (naast StructureDefinitions) ("vocabulary" is een conventie vanuit de IG Publisher)
• voor alle SearchParameters, CapabilityStatements, etc. deze richtlijn over te nemen en ze te plaatsen in eigen folders (naast StructureDefinition dus)
• Voorbeeldmaterialen te houden zoals ze zijn maar (filename = id, folder "examples")

[niekvangalen]

Your text is somewhat inconsistent, regarding the sudden overgang van Engels naar Nederlands ;-)

Anyway, my two cents: Why would we use "searchparameter-" in lowercase as a prefix and use the CamelCased "SearchParameters" for the folder name? I would prefer having the same convention there, unless there is a valid reason not to. For examples I would prefer using a prefix "example-" in the id, which then also ends up in the filename. That way, it's easy to distinguish the files when you have downloaded the package and searching the files.

[pieter-edelman-nictiz]

Wat ik bedoelde is to use the convention for file name prefixes, so the PascalCased resource name as a prefix (except for profiles and extensions).

To be clear: adopting any of these conventions is just to keep our repositories manageable, there's no formal implication (in packages everything will be renamed).

From a manageability perspective, I think it makes sense to clump the following things together (this is just my intuition):

• Profiles and extensions
• Terminology related stuff -- ValueSets, ConceptMaps, CodeSystems and NamingSystems
• Example materials
• SearchParameters are on their own
• CapabilityStatement are on their own

For the zib repository, the profiles/extensions are the "core" elements, but this might not be true for some use case repo's, that's why I feel these things should be on the same folder level.

I'm not sure if prefixing examples with "example-" (and "fixture-" for fixtures?) is such a good idea, the file names/ids are already ballooning out of control at the moment. Besides, if you want to be consistent with the IG Publisher and Simplifier you'd use the resource type as prefix (e.g. Condition-nl-core-Problem-01 etc.). But they are in the "examples" folder anyway, so I don't see much added value.

[jd-nictiz]

Agree with the proposal.

Also do not agree with examples being prefixed with 'example'. At the moment Simplifier does its own thing trying to render an 'example title' (only showing id when it does not find enough data to render a title), but clearly shows 'Example' in package view. With Simplifier being Nictiz' 'package browser' of choice I do not see much added value.

I have doubts on what is a good time to process this request. With all branches being out there using the old structure, perhaps it would be wise on processing this at a point in time closer to the final release?

[pieter-edelman-nictiz]

I have doubts on what is a good time to process this request. With all branches being out there using the old structure, perhaps it would be wise on processing this at a point in time closer to the final release?

That's a valid point. It would however be easier to not make something special in the QA tooling for SearchParameters and than later on change that to accommodate the new file name/folder structure. So I would like to just go ahead.

For now, we could make a separate folder for SearchParameters and migrate the rest later.

[ogieling]

The filenames of CapabilityStatements also have variants among the projects. I would like to add the following suggestion to the file name scheme proposal:

CapabilityStatement-[informatie standaard]-{{scenario}-transactie}-[Rol] Rol: Client/Server

examples: CapabilityStatement-Lab-Client CapabilityStatement-Lab-retrieveLaboratoryResults-Client CapabilityStatement-Lab-Lab2Zorg-RetrieveLaboratoryResults-Client

[jd-nictiz]

I would say [project prefix] instead of [informatiestandaard] - which would be 'mp' in my case, and 'lu' in your case - matching the AD project. If you would like to use 'lab' instead of 'lu' that is perhaps another discussion.

'Scenario' and 'Transaction' are not terms that apply to every standard I guess. MP only uses 'transactions', MedMij speaks of 'use cases'. Perhaps we can generalize this somewhat to say 'use whatever grouping you want, from generic to specific'

Third, maybe only 'role' if this is applicable. See also https://bits.nictiz.nl/browse/MM-2163. Looking at http://hl7.org/fhir/capabilitystatement.html I would say that you would have a .rest for both client and server. Each CS then has both client and server info instead of separate files, but if these elements are identical for client and server this still leads to duplication of information. Is this easier to maintain than separate files, whether they are identical or not?

So: CapabilityStatement-[project prefix](-[group1])(-[group2])(-[group-etc])-[role (if applicable)]

[pieter-edelman-nictiz]

Since role would be optional, I suggest tweaking a bit to:

CapabilityStatement-[project prefix](.[group1])(.[group2])(.[group-etc])-[role (if applicable)]

[jd-nictiz]

Terminology related stuff -- ValueSets, ConceptMaps, CodeSystems and NamingSystems

At the moment, the task of refreshing terminology is somewhat harder because material made by hand and material generated (and thus 'automatically' refreshed) by Art-Decor are in the same folder. I would propose having two subfolders, one for the manual stuff and one for the AD stuff.

This mainly goes for ValueSets at the moment, as all ConceptMaps are made by hand and all CodeSystems are generated. As for NamingSystems: the ones that are there at the moment are manual, but there is an issue on that: #277

[pieter-edelman-nictiz]

Issue-pagina aangemaakt op https://informatiestandaarden.nictiz.nl/wiki/FHIR:Vissue-235_FHIR_Profiling_Guidelines_R4#Folder_structure_and_file_name

[ArdonToonstra]

@pieter-edelman-nictiz - reviewed the wiki issue-pagina. It correctly captures the above discussion for improved file names and folder structure. It does not capture

• the suggestion by Jorn to add subfolders to split the AD-generated resources (e.g. ValueSets) from manually created resources.
• the proposed guidelines for CapabilityStatement IDs and thus file names.

[pieter-edelman-nictiz]

@pieter-edelman-nictiz - reviewed the wiki issue-pagina. It correctly captures the above discussion for improved file names and folder structure. It does not capture

* the suggestion by Jorn to add subfolders to split the AD-generated resources (e.g. ValueSets) from manually created resources.

Because that's a consideration for this specific project, not a general rule. The guidelines state that subfolders may be used where needed.

* the proposed guidelines for CapabilityStatement IDs and thus file names.

I want to split this out into a separate issue, I think it is a bit to vague at this point.