Difference between revisions of "Harmonization: turn ParameterItem.semanticsText into a mandatory attribute"

Latest revision as of 21:01, 26 October 2011

This page documents a Resolved, but not fully actioned MnM Hot Topic, i.e. a methodology issue requiring a resolution from Modeling and Methodology.

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

Position of Concerned Organizations

ORG.NAME	RECOMMENDATION APPROVAL STATUS	AFFECTED ENTITIES OF INTEREST TO ORG
InM	Approved, 20060509	Query classes
MnM	Under Review	Methodology issues
ITS	Under Review	Impact on ITSs, e.g. RIM based ITS
RIMBAA	Under Review	RIM based ITS

Issue

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.
The use of Templates/TemplateId requires some kind of "code" to be present in the class.

Recommendation(s)

Create new mandatory attribute parameterItem.parameterType (CV), and to declare parameterItem.semanticsText to be deprecated. The value of semanticsText is effectively used as a code.
- A drawback is that one has to send the root OID, which will almost always be the OID of an HL7 (Universal) vocabulary.
- parameterType gets a fixed value assigned to it at committee design-time.

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 parameterType).

Non-blue classes: if & when "top of the RIM" classes were used for queries (which was intended in 2006; and may still happen at some point in the future), the concept of parameterType has a direct equivalent: Act.code.

Rationale

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

The RIM states that parameterItem is a name-value pair. ParameterType 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 R1 specific.

Recommended Action Items

Implement the proposed solution

Discussion

See the discussion page for discussions related to a prior version of this proposal.

(Lloyd, 2006) 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, 2009) ..if with ITS you mean XML ITS R1 then I agree. A RIM based ITS should require it to be sent on the wire.

(Rene, 2006) It would be a "structural attribute" which (just like other structural codes) need not be sent on the wire.

(Grahame, 2006): 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.

A bit of history:

Sometime in 2006: Proposal dropped - moot point, depends on outcome of the blue classes v. top half of RIM discussion.
January 2009: turned into an active item again, because of issue related to Clone names by Patrick Loyd.
January 2009: RIMBAA also has an interest in resolvong this, because of RIM based ITS. The creation of such an ITS requires that there be no dependencies on clone names.

René: it seems there are a couple of open questions which need to be resolved:

Is it still possible to use semanticsText as it was originally intended by means of a Constraint Language? Depending on the answer semanticsText should, or shouldn't, be deprecated.
Should the value of parameterType be sent over the wire? In the current XML ITS R1? In an RIM based ITS?
When should parameterType be valued? Should it always be valued?
- Rene: to me the requirements of a RIM based ITS are such that in that ITS you'd always need to have a value for parameterType.

Resolution

Rene will submit a harmonization proposal (as per commitment at Jan. 2011 WGM

@@ Line 1: / Line 1: @@
-{{INM Workitem}}
+{{MnM Resolved Hot Topic}}
 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.
@@ Line 21: / Line 22: @@
 |}
-== Stewards Position ==
+== Position of Concerned Organizations ==
-REQUIRED - This table should contain one row for each Steward Committee affected by the recommendation.
 {|width=100% cellspacing=0 cellpadding=2 border=1
 |-
-|bgcolor="#aaaaff" align=center| '''TC'''
+|bgcolor="#aaaaff" align=center| '''ORG.NAME'''
 |bgcolor="#bbbbff" align=center| '''RECOMMENDATION APPROVAL STATUS'''
-|bgcolor="#aaaaff" align=center| '''AFFECTED ENTITIES OF INTEREST TO TC''' <br/> (responsibility level: S=Steward; I=Interested)
+|bgcolor="#aaaaff" align=center| '''AFFECTED ENTITIES OF INTEREST TO ORG'''
 |-
-|| INM
+|| InM
-|| Under review
+|| Approved, 20060509
-|| S
+|| Query classes
 |-
+|| MnM
+|| Under Review
+|| Methodology issues
+|-
+|| ITS
+|| Under Review
+|| Impact on ITSs, e.g. [[RIM based ITS]]
+|-
+|| RIMBAA
+|| Under Review
+|| [[RIM based ITS]]
 |}
 == Issue ==
-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.
+#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.
-*Queries as defined by committees quite often contain parameterItem clones without a semanticsText attribute. This way a value is conveyed without an underlying key.
+#The use of [[Template]]s/[[TemplateId]] requires some kind of "code" to be present in the class.
 == Recommendation(s) ==
-*Change parameterItem.semanticsText into a mandatory attribute.
+*Create new mandatory attribute parameterItem.parameterType (CV), and to declare parameterItem.semanticsText to be deprecated. The value of semanticsText is effectively used as a code.
-*Enforce with the aid of tooling (upon model validation) that a fixed value is assigned to this attribute.
+**A drawback is that one has to send the root OID, which will almost always be the OID of an HL7 (Universal) vocabulary.
+**parameterType gets a fixed value assigned to it ''at committee design-time''.
-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).
+'''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 parameterType).
-=== Alternative Solution ===
+'''Non-blue classes:''' if & when "top of the RIM" classes were used for queries (which was intended in 2006; and may still happen at some point in the future), the concept of parameterType has a direct equivalent: Act.code.
-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.
+All paremeterItem derived classes have to have the parameterType attribute with a predefined (default) value. The only circumstance where a parameterItem-clone would not have to have parameterType 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.
+The RIM states that parameterItem is a name-value pair. ParameterType 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.
+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 R1 specific.
 == Recommended Action Items ==
@@ Line 59: / Line 71: @@
 == 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.
+See [[Talk:Harmonization:_turn_ParameterItem.semanticsText_into_a_mandatory_attribute| the discussion page]] for discussions related to a prior version of this proposal.
-:(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, 2006) 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, 2009) ..if with ITS you mean XML ITS R1 then I agree. A [[RIM based ITS]] should require it to be sent on the wire.
+:(Rene, 2006) It would be a "structural attribute" which (just like other structural codes) need not be sent on the wire.
-:(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.
+::(Grahame, 2006): 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.
-::(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.
+A bit of history:
+*Sometime in 2006: '''Proposal dropped - moot point, depends on outcome of the [[MessageCommunicationsControl|blue classes v. top half of RIM]] discussion.'''
+*January 2009: turned into an active item again, because of issue related to Clone names by Patrick Loyd.
+*January 2009: [[RIMBAA]] also has an interest in resolvong this, because of [[RIM based ITS]]. The creation of such an ITS requires that there be no dependencies on clone names.
-:(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.
+René: it seems there are a couple of open questions which need to be resolved:
+#Is it still possible to use semanticsText as it was originally intended by means of a [[Constraint Language]]? Depending on the answer semanticsText should, or shouldn't, be deprecated.
-::(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".
+#Should the value of parameterType be sent over the wire? In the current XML ITS R1? In an [[RIM based ITS]]?
+#When should parameterType be valued? Should it always be valued?
-::(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: to me the requirements of a [[RIM based ITS]] are such that in that ITS you'd always need to have a value for parameterType.
-::(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- they would have to create very abstract parameter types 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.
 == Resolution ==
+Rene will submit a harmonization proposal (as per commitment at Jan. 2011 WGM
 [[Category:Harmonization Proposal]]

Difference between revisions of "Harmonization: turn ParameterItem.semanticsText into a mandatory attribute"

Latest revision as of 21:01, 26 October 2011

Contents

Position of Concerned Organizations

Issue

Recommendation(s)

Rationale

Recommended Action Items

Discussion

Resolution

Navigation menu

Personal tools

Namespaces

Variants

Views

More

Search

Navigation

groups

meetings

general

Tools