---
# System prepended metadata

title: Cross-Version Scratch

---

* Question: Generate packages by target resource (e.g., R5 SubscriptionTopic)
* Currently working on reconciling the sources of truth:
    * Comparison of element definitions plus…
	* ValueSet concept maps
		* ConceptMaps in fhir-cross-version/input/codes, by binding element
		* Reconciling multiple instances into a single ValueSet mapping
		* (WIP) detecting manual mappings in FML from fhir-cross-version/input/R#toR#
	* Type mappings
		* ConceptMaps in fhir-cross-version/input/types, by version change
		* FML in fhir-cross-version/input/R#toR#/primitives.fml (manually extracted once since it doesn't change)
		* Manual serialization info from fhir/versions.html
	* Element changes
		* Renames from ConceptMaps in fhir-cross-version/input/elements, by version change
		* (WIP) FML files in fhir-cross-version/R#toR#, by resource/datatype
* Generating
	* Markdown comparisons (per version change: summary, per ValueSet, per type, per resource)
	* Concept Maps (per version change: per ValueSet, per type, per resource)
	* Structure Maps
* Working on UI (aspirational)
	* Process ValueSet
		* Set source and target (create maps from one VS to two, etc.)
		* Review concepts, set mapping info (target/s, relationship, etc.)
			* Relevant concept info (system, code, display)
			* Relevant concept map entries
			* Elements that use the value sets (where is this used)
			* Update element relationships based on changes
	* Process Structure (Complex Type, Resource)
		* Set source and target (map between changed structure names, split structures, etc.)
		* Review elements, set mapping info (target/s, relationship, etc.)
			* Relevant element info (cardinality, types, targets, descriptions)
			* Relevant concept map entries
			* Relevant FML lines
		* Nest into ValueSet comparison
		* Highlight Yes/No: Will this create an extension
			* Preview the extension information
	* Will NOT allow FML changes in first pass
	* Update definitions while changes are made (avoid re-running the entire comparison)
* Validate agreement on when and what the definitions have
	* When do we create a cross-version extension:
		* An element that has an *unrepresentable* change between two versions (either direction)
		* Not when
			* An element has the same type(s), target type(s), cardinality, and a compatible binding
			* Target is consistent but renamed
			* Multiple elements merge into a single target (e.g., CodeableConcept + Reference => CodeableReference)
			* Target is a narrower type definition (e.g., removed type, removed target, reduced cardinality)
			* Target has a wider set of concepts and is *not* a required binding
			    * Depends on where the code system comes from.  Using a code from a newer version would implicitly reference the newer code system, which may mean a different definition of the concept.
		* Specific causes for defining an extension
			* Target has higher cardinality (e.g., moving from scalar to array)
			* Target has one or more additional types (e.g., added to a choice type)
			* Target has one or more additional target profiles (e.g., added Reference(Device))
			* Target has a wider required binding (e.g., additional status codes)
			* Target has a wider binding strength (e.g., required -> extensible)
			* Target has the same binding with an expanded set of codes (e.g., new codes have been added)
	* What does the definition look like
		* TLDR: is each extension a representation of the target element or a differential between the current representation and the target?
		* Types
			* Does the extension include all types of the target, or only new types?
			* Does the extension include all target profiles, or only new targets?
		* Bindings
			* Do we use the target ValueSet or generate a differential ValueSet (would be per-version)
		* Allowed contexts
			* Do we try to determine the 'correct' contexts for the extensions, or just use Element?
		* Descriptions
			* What should the documentation template look like?  E.g., 'A cross-version extension to allow FHIR R4 Encounter resources to use the R5 Encounter.classStatus element…'
	* Can we generate them in packages per-target resource?  E.g., hl7.fhir.uv.cross-version.r5.encounter.r4 to contain the R4 extension definitions for the R5 Encounter resource.
	* What is our policy on extensions attached to the target?
		* Can we access extension definitions across versions (e.g., can an R4 instance use an R5 extension)
		* How do we define extensions (e.g., in the extensions pack) so that we have correct contexts when:
			* An element is renamed (context would not be a valid path in some versions)
			* An element is added (does context allow for Extension so that it can attach to cross-version extensions)
    * General questions about terminology access
        * Do we want to make core CodeSystems/ValueSets available in earlier versions too?  E.g., should cross-version extensions include those value sets (case: extension is defined with a binding to R5 and we want to use that extension in another version)


### Issues to discuss
* When array elements move into a deeper level (e.g., an element converted to backbone and is now a property), I *think* the desired behavior is to not define the CVE for the element that got moved and then define the rest of the properties with CVEs based on that array.
    * `Practitioner.communication` in R4 moved to `Practitioner.communication.language` in R5
    * R5 *also* added a boolean for `preferred`
    * In R4, it is required that we use `Practitioner.communication`, which means that the additional elements attached to the Backbone in R5 (`preferred`) need to attach to repetitions of the R4 `Practitioner.communication`.
    * It will be complicated to generate, but if we just lump the R5 elements together, we have 'lost' data that an R4 client will not be able to access.


### Extension Definitions and FHIR Versions
* When defining, the extension URL is rooted in the *first* FHIR version with a compatible definition.  For example, using a DSTU2 instance, let us consider:
    * An element that was:
        * Added in STU3 (R3)
        * Unchanged in R4
        * Modified in R7
    * Unique extension definitions must exist for the version of the element in
        * R3 (added)
            * `http://hl7.org/fhir/3.0/StructureDefinition/extension-[resource]-[element-path]`
        * R5 (modified)
            * `http://hl7.org/fhir/5.0/StructureDefinition/extension-[resource]-[element-path]`
    * So I am working in R2 and want to:
        * Add the R3 element to my resource:
            * `http://hl7.org/fhir/3.0/StructureDefinition/extension-[resource]-[element-path]`
        * Add the R4 element to my resource:
            * `http://hl7.org/fhir/3.0/StructureDefinition/extension-[resource]-[element-path]`
        * Add the R5 element to my resource:
            * `http://hl7.org/fhir/5.0/StructureDefinition/extension-[resource]-[element-path]`

    * Bas Proposal is to change this to:
        * Add the R3 element to my resource:
            * `http://hl7.org/fhir/3.0/StructureDefinition/extension-[resource]-[element-path]`
        * Add the R4 element to my resource:
            * `http://hl7.org/fhir/4.0/StructureDefinition/extension-[resource]-[element-path]`
        * Add the R5 element to my resource:
            * `http://hl7.org/fhir/5.0/StructureDefinition/extension-[resource]-[element-path]`

    * Grahame Proposal is to change this to:
        * Backbone elements are unversioned, only actual value elements are versioned
        * Add the R3 element to my resource:
            * `http://hl7.org/fhir/StructureDefinition/extension-[resource]-[element-path]`
        * Add the R4 element to my resource:
            * `http://hl7.org/fhir/4.0/StructureDefinition/extension-[resource]-[element-path]`
        * Add the R5 element to my resource:
            * `http://hl7.org/fhir/5.0/StructureDefinition/extension-[resource]-[element-path]`
