Talk:Extensibility Page

What do we call the 80%?

One of the pieces of feedback from ITS was that we needed a succinct name for those things that weren't extensions. "eighty percent" is a lot of syllables, and it's only an adjective. My recommendation is "core". I.e. A resource or datatype will have "core properties" - those deemed likely to be implemented by at least 80% of implementers and "extension properties" - those deemed likely to be used by a smaller percentage.

• Have adopted convention of using "Core" to talk about elements that are part of the resource definition

Schema compatibility of future versions

We've said that it will be possible for HL7 to elevate "extension" properties into "core" properties in future versions of a resource, either because experience has shown that we goofed in our assessment that fewer than 80% of implementers would use something, or because industry practice has evolved such that something that was once rare is now common-place. It makes sense to be able to do this. However, due to limitations of XML Schema, it's not possible to design a loose enough schema that still parses deterministically (and thus is 'valid' according to many tools) to accommodate future extensions unless you put them into a foreign namespace.

I'm pretty sure we don't want to mess around with namespaces in our primary resource representation. Therefore, we can't add new core elements into the main resource structure once the resource is finalized (i.e. passed normative ballot). The only way we'd do this is if we were willing to break backward compatibility, which would mean deprecating the old resource and creating a new one with a distinct name - e.g. Person2. Obviously we'd only undertake this step if we *really* screwed up and the implementers were willing to suck up the pain of doing the migration.

That said, I still think it's useful to have the ability to "migrate" content into core. We could do this by setting a flag on the extension. We might not be able to put them in the schema, but we could at least list these "core extensions" in the publication so it's clear to implementers "this is something we think you should seriously consider implementing because its adoption is widespread". Such extensions would go through the same review process and balloting as they would if we were actually able to add them to the schema.

• Have decided that migration of HL7-defined extensions will not occur. Migration of non-HL7-defined extensions will be possible, but will be "rare". Possibility of publishing some extensions as part of the core will be revisited when we get there.

Issue with extension.state

We're using state to convey whether something has been promoted into core and whether it's "must understand". Those are orthogonal concepts, and both could be true. I think we should split them into separate indicators of "core" and "mustUnderstand" with default values of "false". The "core" property would only need to be declared as metadata. There's no longer any need for it to be declared in the instance, because stuff can't be moved.

• Extension.state has been dropped

Providing an alternate view of extensions

Some implementers are going to hate extensions. That's because they visually break the object graph of a resource into multiple pieces. Some may struggle with stitching the pieces back together. And it's going to create a strong push-back against having stuff in extensions, particularly once people realize that anything that's not in core in version 1 will *never* be in core.

It's possible to render resource instances in an isomorphic way such that all of the extensions are simply embedded as part of the resource definition. This can be done via transforms or as part of the standard generated interface code. Furthermore, it should even be possible for the code generator to suck in a conformance statement, identify all the extensions that are supported and move just those into the core structure, leaving the remainder of other unsupported extensions sitting in the extensions property (and yelling if any of those stuck there are "must understand").

The process would look like this:

Schema-valid instance

<SomeResource>
  <id>29347781</id>
  <name id="1">This is my name</name>
  <type>
    <coding>
      <code>ABC123</code>
      <codeSystem>1.2.3.4</codeSystem>
    </coding>
    <coding id="2">
      <code>Q517os4</code>
      <codeSystem>5.6.7.8</codeSystem>
    </coding>
  </type>
  <extensions>
    <extension>
      <id>ISRESTRICTED</id>
      <definition>http://www.hl7.org/fhir/extensions</definition>
      <ref>1</ref>
      <mustUnderstand>true</mustUnderstand>
      <value type="boolean">true</value>
    </extension>
    <extension>
      <id>VALUESET</id>
      <definition>http://www.hl7.org/fhir/extensions</definition>
      <ref>2</ref>
      <extensions>
        <extension>
          <id>v-CD.valueSet.version</id>
          <definition>http://www.hl7.org/fhir/extensions</definition>
          <value type="humanDate">2014-07-18</value>
        </extension>
        <extension>
          <id>823.23425.15</id>
          <definition>http://www.somewhere.org/my-project/fhirext/2013</definition>
          <value type="string">John Smith</value>
        </extension>
      </extensions>
    </extension>
  </extensions>
</SomeResource>

Integrated instance

<SomeResource xmlns:h="http://www.hl7.org/fhir/extensions" xmlns:x="http://www.somewhere.org/my-project/fhirext/2013">
  <id>29347781</id>
  <name>
    <value>This is my name</value>
    <h:ISRESTRICTED type="boolean" mustUnderstand="true">true</h:ISRESTRICTED>
  </name>
  <type>
    <coding>
      <code>ABC123</code>
      <codeSystem>1.2.3.4</codeSystem>
    </coding>
    <coding id="2">
      <code>Q517os4</code>
      <codeSystem>5.6.7.8</codeSystem>
      <h:v-CD.valueSet>
        <h:v-CD.valueSet.version type="humanDate">2014-07-18</h:v-CD.valueSet.version>
        <x:823.23425.15 type="string">John Smith</x:823.23425.15>
      </h:v-CD.valueSet>
    </coding>
  </type>
</SomeResource>

We could even publish future versions of a resource incorporating "core extensions" this way if we wanted to.

• Code generation will be able to take a conformance profile as input, however we won't produce instances that use namespacing to move extensions inline. If implementers want to do that behind the scenes, they can, but those instances aren't considered compliant FHIR.

Vetting

We need to add a section that talks about vetting of extensions and include a vetted flag as part of the metadata. Vetting an existing extension will generally involve creating a new extension that might clarify definitions, fix mappings, etc.

• Ideas around "vetting" need to be revisited now that extensions are maintained inside profiles rather than being registered stand-alone. We can have HL7-vetted profiles, but whether that's done with a flag or by including an existing profile in an HL7 registry is unclear.

Translations

(low priority) How will we capture translations of registered extensions? Will be slightly more complex than doing so for the resources themselves, but still important.

• Extensions are captured in profiles. Translations for profiles will be handled in the same way as translations for resources - once we get there.

Datatypes

Why aren't all the datatypes legal? I would think extensions could be of type boolean, integer, etc.?

• They're all legal now.

ref location

I'm assuming that "ref" can only be declared on extensions that aren't nested inside other extensions. (Because presumably there's no need for it inside the extension hierarchy?)

• Extensions have been remodelled - no longer applies

What are the formal semantics of 'must understand'

It's going to be tempting for people to flag things as "must understand" when they really should just flag the element as required. I think the semantics of "must understand" are "the content of this element can alter the semantic interpretation of other elements within the containing resource or extension". If it doesn't change the interpretation of something else, and you don't care about that particular element, there's no reason why you must understand it. (Though a conformance profile may indicate that you're required to support it.) Where this gets messy is if one extension can alter the understanding of another extension. Technically that's a "must understand". But it's really only "must understand" if the instance contains the other extension, and the receiver doesn't ignore that other extension. We *could* change "must understand" to "must understand for elements" and provide a list of elements whose semantics could be impacted, but that's not really practical.

• Have revamped the description of must understand to clarify that it impacts on all elements within the parent

Rejecting extensions

We say "Conformant applications are not allowed to reject resources because they contain extensions, though they may need to reject resources because of the specific contents of the extensions."

I agree with this in principle. However, there are regulatory environments where accepting a message means accepting full responsibility for the entire content. The common practice in these environments is to reject instances that contain anything unexpected. I'm thinking of places like FDA. It would be bad to force such implementers totally outside the bounds of conformance. Can we define a conformance mechanism that allows this to occur, while discouraging it and flagging the fact that doing this causes serious interoperability issues?

• We'll worry about this if/when someone raises a fuss

Uniqueness of extensions

It's not clear that the definition URI is going to be the namespace for id. However, given that ids aren't required to be unique (and have no real way of being forced to be unique outside the context of the registering authority), there's no choice other than to make them namespaced by the definition URI.

• Extensions are defined within the namespace of a profile, which has a URI

Extension Registry

We need to talk about what the registry is going to look like and how it's going to work (and what we're going to do in the near term where committees will be defining extensions and we won't have a registry to publish things in.) Considerations include:

• What search criteria are there?
• Can entries be edited once created?
  • by whom?
  • what sort of edits are legal, given that extensions may already be used by someone?
• What's best practice in terms of registering extensions? (If there are lots of restrictions on what can be changed, we don't want people registering extensions until they're super final.)
• Will the HL7 registry be tied to having a web userid? (Membership isn't required to get one, and it does give a basis of security and accountability against spammers, plus a mechanism for allowing updates if we allow them)
• Will we have links from the resource definitions to an auto-populated sort of the extensions defined for that resource?
• What should the user interface look like?
• What's the relationship between this and OHT's artifact repository?
• What will we allow as the naming convention for extension codes?
  • Are they case sensitive? (e.g. can I register "OriginalText" and "originalText" with separate definitions?
  • Do we need to filter for organization names? (e.g. Can I create an extension called "MicrosoftSucks"? (Less of an issue if we require a login.) What about

• Extension Registry is profile registry. Search criteria, etc. are defined as part of that resource

How are ids declared?

"ref" properties are supposed to identify an element. But it doesn't identify how an element declares the id specified in the ref. I'm guessing it would have to be an XML attribute given that some elements will have child text nodes. However, I don't know what the attribute is to be called. If this is defined somewhere else, including a link would be useful.

• Now defined in the spec

Missing ref

The spec says: If present, the id in the ref element identifies a target element that is extended by the content as if it contained the extension itself. The id must point within the same resource.

So where does the extension apply if no id is specified? Does the absence of an id mean the extension must apply at the root?

• Now clarifies what absence means. (Applies to resource root.)

Extensions that can apply to multiple paths

There are some extensions that can apply in many places. For examples, extensions to the "identifiers" structure that will appear on many entity-based resources, or extensions on datatypes to convey originalText. We don't want to have to re-define these extensions multiple times if everything about the extension (RIM mapping, definition, component extensions, etc.) is going to be the same. And we don't really want to have to enumerate the full list of paths where the extension might apply as part of the extension definition.

Suggest the easiest way is to allow each resource element to identify that it belongs to 0..* "patterns" (likely a space-separated list of NMTOKENs in the CSV file). Belonging to a pattern means that all extensions associated with that pattern can be applied to that element. The FHIR governance team would be in charge of defining patterns. Each pattern would have a name, a brief description and a RIM mapping that describes the characteristics that must be true for the element to which the pattern label is applied. Extensions would then identify either an element path *or* a pattern name to define what they're allowed to attach to.

• Have revamped this. Can now identify an extension as applying to a particular reference model pattern (i.e. anything that maps to RIM structure X)

Conformance for extensions

How can we declare conformance for extensions? Isn't that something that has to be delegated to the constraint statements that reference it? The only time this really makes sense is if you have an extension that contains other extensions. In that circumstance, you might want to indicate that some of the child extensions are required. However, that raises the interesting question of *who* is allowed to mark an extension as required within the context of a given parent extension? Ideally, this should be constrained to whatever system created the base extension (or HL7). But that may not be manageable.

Recommendation

1. Conformance may only be declared on extensions that have either been flagged as core, or that are extending another extension. Non-core extensions that directly extend a resource are, by definition, optional. (Conformance can be tightened in profiles.)
2. Conformance may only be declared on extensions that have been "vetted" by HL7 (whether core or not). If you're not going through the vetting process, then conformance is automatically optional.

• Conformance extensions is relegated to the profiles that use them.

Linking extensions

We need to be able to say that one extension is superseded by another extension, essentially saying that, if possible, you should use the new extension rather than an extension that was submitted as a duplicate item.

• We have "superseded" as a status on Profile with supporting text that can point to the new profile. Not clear that anything more than that is within the 80%

What's the context for determining 80%?

Many resources, such as Person, Patient, Provider, etc. will be used in two contexts:

• As 'primary' resources, when working with registry systems for patient, provider and other information
• As 'secondary' resources referenced in the context of other information (e.g. referencing patient and provider as part of a lab order)

Our guideline for determining "what's 'core' and what's 'extension'" is we will include those elements in 'core' that 80% of systems will need. However, what registry systems will need is quite distinct from what 'referencing' systems will need. Which do we target?

• Focus for core is "systems that maintain this resource", not "systems that reference this resource"