Harmonization: turn ParameterItem.semanticsText into a mandatory attribute

Editing of harmonisation proposals prior to a harmonization meeting is restricted to the proposal submitter and the co-chairs of the steward comittee. Other changes will be undone. Please add comments to the "discussion" page associated with this proposal.

Recommendation for HL7 RIM Change	RECOMMENDATION ID:
Submitted by: INM	Revision (# and date): 20060509
Date submitted:	Committee status: Approved - 20060509
Submitted by: Rene Spronk
NAME: turn ParameterItem.semanticsText into a mandatory attribute

Stewards Position

REQUIRED - This table should contain one row for each Steward Committee affected by the recommendation.

TC	RECOMMENDATION APPROVAL STATUS	AFFECTED ENTITIES OF INTEREST TO TC (responsibility level: S=Steward; I=Interested)
INM	Under review	S

Issue

1. The parameterItem RIM class is defined to be a key/value pair. The v3 design principle states that when it comes to the interpretation of RIM-derived models one should be able to derive the full semantics of the model without having to look at the names of cloned classes. Queries as defined by committees quite often contain parameterItem clones without a semanticsText attribute. This way a value is conveyed without an underlying key.
2. The use of Templates/TemplateID requires some kind of "code" to be present in the class.

Recommendation(s)

• Change parameterItem.semanticsText into a mandatory attribute.
• Enforce with the aid of tooling (upon model validation) that a fixed value is assigned to this attribute.

Backwards compatibility: there are no backwards compatibility issues. Those able to process the old (erroneous) queries [there are some that have already gone normative] will certainly be able to process the new queries (with semanticsText).

Alternative Solution

Alternative is to create new mandatory attribute parameterItem.parameterKey (CV), and to declare parameterItem.semanticsText to be deprecated. The value of semanticsText is effectively used as a code. A drawback of this option is that one has to send the root OID, which will almost always be the OID of an HL7 (Universal) vocabulary.

Rationale

All paremeterItem derived classes have to have the semanticsText attribute with a predefined (default) value. The only circumstance where a parameterItem-clone would not have to have semanticsText is a query that has only 1 parameterItem.

The RIM states that parameterItem is a name-value pair. SemanticsText contains the "name" part of the name-value pair. See the "Link between parameterItem and RIM attributes" section of the Query Parameters Wiki page for a discussion on how to define the semantics associated with a parameter.

Note that although widely used by implementers of XML v3 Interactions, the name of the class-clone does not carry any semantic meaning and therefore can't be used (in abstract models, like R-MIMs) to distinguish between one parameterItem clone and another one. Using the className is XML ITS specific.

Recommended Action Items

• Implement the proposed solution

Discussion

Prior to the harmonization meeting the underlying issue was discussed:

(Rene) SemanticsText is an unstructured string. As such it can contain anything and everything. If a committee values it with "MothersMaidenNameAtTimeOfAdoption" or "MMM@adopTime" (and they do this today) then both are fine. They'll have to document the logic behind the string anyway. An expression of the underlying logic (what attribute or attributes the receiver should use to match the parameter with) doesn't end up in semanticsText, but in the documentation. semanticsText is a meaningless identifier of a parameter type, just like the cloneClass name of the parameterItem class, or the code contained in Act.class.

(Lloyd) If there's not a formal, computer-interpretable definition of what goes in semanticsText, it makes *no* sense to make semanticsText mandatory. Having semantics vary from committee to committee or implementer to implementer means that the attribute has absolutely no value. (If a human has to get involved, they may as well go read the spec.) The intended purpose of semanticsText was to provide a rigorous semantic definition. "How to do it" is undefined at the moment, because we don't have a language we can use to express it.

(Lloyd) We presently have a formal structure for expressing semantics in the "top half" of the RIM. As such, all clone names used in the top half should not be used to imply semantic value. However, in the case of query parameters, we have no formal way of representing semantics. Given that we already have the ability to give each parameter an ad-hoc human-meaningful name (the clone name), it makes little sense to use an attribute to basically accomplish the same thing, particularly when the purpose for the attribute in the first place was to provide a formal definition. We actually used to have another attribute on Parameter called "name". It's purpose was to provide such a meaningless identifier. We removed it at harmonization 2 to 2.5 years ago based on the premise that it was redundant with the existing clone name.

(Rene) Why would this only be true for the "top half" of the RIM. "The v3 design principle states that when it comes to the interpretation of RIM-derived models one should be able to derive the full semantics of the model without having to look at the names of cloned classes." XML as an ITS is exceptional in that it actually uses cloneNames as part of the encoding. Once we're going to develop ITSs that don't depend on cloneNames (e.g. ER7 to use a silly example) the above statement means we have to make semanticsText mandatory, and have committees assign a fixed value.

(Lloyd) The spirit of the harmonization principle is: "The v3 design principle states that when it comes to the interpretation of RIM-derived models one should be able to derive the full *computable* semantics of the model without having to look at the names of cloned classes. *The purpose of the clone names is to both ensure unique type names for code generation and instance validation, as well as to make those semantics clear to the average human reader*" In the case of query parameter, we don't yet have any mechanism of expressing the parameters in a computationally interpretable way. We already have a human-interpretable mechanism via the clone names. I can be convinced to make semanticsText mandatory, but *only* if it allows computers to infer the same sorts of semantics they can already infer by looking at the structural and coded attributes in the top part of the RIM.

(Rene) It seems you would support an alternative, but more radical idea that was briefly discussed in INM: deprecate semanticsText, and create a new attribute (let's call it parameterType) of data type CS or CV, with a fixed value assigned to it at committee design-time. Currently semanticsText is of data type SC (string with optional code). If we want a unique name as well as processability, a code is the thing to go for, just like the "top half of the RIM".

(Lloyd) I would support such a proposal, but only if the ITS didn't require sending it over the wire. I'm also not sure that semanticsText needs to be deprecated. Conceptually, I'd like to hold out hope that we'll get our constraint language that allows us to formally express the semantics of a query parameter. Once there, we can look at making the element mandatory.

(Rene) Summary: deprecate semanticsText, and create a new attribute (let's call it parameterType) of data type CS or CV, with a fixed value assigned to it at design-time (i.e. by committee, not by implementers). It would be a "structural attribute" which (just like other structural codes) need not be sent on the wire.

(Grahame): hang on. using templates with parameterized queries would be a good idea. If we want this, we need slightly different rules - the parameterType need not be set by committee. In fact, the committee stage is too early - forcing committees to always define all the parameterTypes would mean that at times they would have to create more general parameter types (such as "some database field" instead of "database field x"), which would be difficult for implementers. Implementors don't want to confront templated queries at run-time, but need to do so at application design time. This has implications for templates which are taken up in the template specification. So agree to deprecate semanticsText, and create parameterType, but let committees define parameterType where suitable. When committees define parameterType, it won't be sent over the wire unless fixed and default values are being sent.