Difference between revisions of "DataTypes Comments Section 2"

From HL7Wiki
Jump to navigation Jump to search
Line 34: Line 34:
 
*# P4 We need some examples here if we're going to include this.  Is AddressPartType the only non-hierarchical representation.  What does "hierarchichal in nature mean anyway"
 
*# P4 We need some examples here if we're going to include this.  Is AddressPartType the only non-hierarchical representation.  What does "hierarchichal in nature mean anyway"
 
*# "Status" and "Level discussion is just plain confusing.
 
*# "Status" and "Level discussion is just plain confusing.
 
 
 
* [http://wiktolog.com/hl7/datatypes.html#datyp2introform 2.4 Formal Data Type Definition Language(DTDL)]
 
* [http://wiktolog.com/hl7/datatypes.html#datyp2introform 2.4 Formal Data Type Definition Language(DTDL)]
# ''A formal definition of data types is defined here in order to clarify the semantics ...'' - huh?  
+
*# P1 ''A formal definition of data types is defined here in order to clarify the semantics ...'' - say, what?
# ''The formal definition only specifies the meaning'' of the data values through statements defining semantic relationships and behavior. - ''I'd argue whether it specifies the "meaning" at all. Is this necessary, or can we shorten this to "The formal definition defines the semantic relationships and behavior of conforming data values".
+
*# P2
# ... but the resemblance is ''semantic'': it does not imply any procedural machinery. - say what?
+
*#* ''The formal definition only specifies the meaning'' of the data values through statements defining semantic relationships and behavior. - '' Does the formal specification really specify "meaning" at all? Is this necessary, or can we shorten this to "The formal definition defines the semantic relationships and behavior of conforming data values".
# ''Concision'' - lord, is that even a word?
+
*#* ''... but the resemblance is ''semantic'': it does not imply any procedural machinery.''  What does it mean to say the resemblance is ''semantic''?  Perhaps the author intended ''syntactic'', or something similar?
 
+
*#* ''Concision'' - "Those who would enforce circumcision on Gentile Christians." or "conciseness: terseness and economy in writing and speaking achieved by expressing a great deal in just a few words".  How about ''Conciseness''?
# named values of a fully enumerated extension - ''if''?
+
*# ''named values of a fully enumerated extension'' - since this only occurs in one place (right?), how about ''named values in the case of the Boolean type'' and just forget about the intension/extension stuff?
# ''semantic properties'' - ''WHAT'' are semantic properties, and why do we have to even metion "unary", "binary and the like?
+
*# P4 ''... and signatures of the new type's <strike>semantic</strike> properties.'' - unless you can differentiate semantic from non-semantic, don't confuse the poor reader.  Properties is properties.
 
+
*#* '''2.4.1 Declaration'''
# Given that BL is the ''only'' type with finite values, maybe we can downplay that part?  
+
*#*# P3 - since Boolean is the exception, perhaps we can downplay this little nuance?
 
+
*#*# P6
# Specializes is out of place?
+
*#*#* would recommend moving this up, so the declaration is explained in the order that it occurs (type, alias, specializes...)
# genus and species? Isn't there a better way to describe this?  If we use it, perhaps we should put "genus" and "species" in quotes as this is not a very common usage.
+
**#*#* genus and species? Isn't there a better way to describe this?  If we use it, perhaps we should put "genus" and "species" in quotes as this is not a very common usage.
# "Specialization can include the definition of additional properties "
+
*#*# P6 and P7 "Specialization can include the definition of additional properties " - perhaps the "Definition 2" (aka Example 2) could have a more complete example?  It would be useful to be able to see what this is talking about.
# "It is generally held that inheritance should not retract properties defined for the genus" - it is more than generally held.  A "species" cannot retract properties asserted in the "genus".  It is possible, however, for a "species" to contstrain a non-mandatory "genus" type to only a null value, thereby effectively declaring it as not present.
+
*#*# P8 "It is generally held that inheritance should not retract properties defined for the genus" - it is more than generally held.  A "species" cannot retract properties asserted in the "genus".  It is possible, however, for a "species" to ''constrain'' a non-mandatory "genus" type to only a null value, thereby effectively declaring it as not present.
 
+
*#*# Abstract - "An abstract type is a type where no ''non-exceptional'' value can be of this type." What is an ''exceptional'' value?  What is an example of an ''exceptional'' value being of an abstract type.
# Abstract - what does it mean for an ''exceptional value'' to be of an abstract type?
+
*#* 2.4.2 Invariant Statements
 
+
*#*# 2.4.2.2  We need to learn a bit about the <nowiki>X<T></nowiki> construct before it is introduced in an example.  Otherwise it is confusing.
* 2.4.2 Invariant Statements
+
*#* 2.4.3 Type Conversion
# Again, are these "definitions, or "examples"
+
*#*# P2 It isn't clear at this point which direction is a ''demotion'' and which is a ''promotion''.  Need to stick something in that uses the "genus"/"species" analogy or an equivalent.
# Curiously, there is no reference to the "X<T>" construct in the assertion expressions, yet it is immediately used in 2.4.2.2
+
*#*# P4 - is the
 
 
 
# "Definition 7" - you might want to also mention that this is a "promotion" or "demotion" (it isn't clear at this point which goes from "genus" to "species"...   
 
# "Definition 7" - you might want to also mention that this is a "promotion" or "demotion" (it isn't clear at this point which goes from "genus" to "species"...   
 
# 2.4.3.1 and 2.4.3.2 clarifies the direction, but, if you are going to use the "genus" and "species" notation (or equivalent), use it agaain in these two examples.
 
# 2.4.3.1 and 2.4.3.2 clarifies the direction, but, if you are going to use the "genus" and "species" notation (or equivalent), use it agaain in these two examples.

Revision as of 18:38, 8 March 2008

2 Data Type Definitions

  1. This specification defines data types in several ways, using including textual descriptions, ...
  2. domains - this isn't addressed anywhere below. What is it? What does it mean?
  3. The describes each of these ways.The following sections describe how each of these different ways are used and represented.
  4. Each type is defined with the following sections:Every data type definition contains the following components:
    • A unique natural language name
    • A unique abbreviation or mnemonic
    • The parent data type(s), if any
    • A prose definition
    • A table of "primary" properties
    • A formal Data Type Definition Language (DTDL) definition
    • A prose explanation of key points of the DTDL
    • A table of domain definitions for coded types or properties
    • Notes identifying common misunderstandings, usage expectations, open questions, and other important points that don’t fit neatly into the above categories (optional)
  5. GENERAL - this is a wonderful start. If the sections below followed the order above, this would be a very approachable and comprehensible document. One of the issues, however, is exactly how the UML diagrams fit into the rest of the picture. One possibility would be to include a paragraph on UML diagrams immediately following the bulleted list and then put the section on UML diagrams into the corresponding spot.
  • 2.1 Unified Modeling Language (UML) Diagrams
    1. As mentioned above - this is really out of place. The introductory paragraph only briefly mentions UML and then it is given first chair in remainder of the document.
    2. P3 - A number of stereotypes, enclosed in guillemots («»)", are ..
    3. P10
      • Putting the colour name in color would be very helpful, as not everyone's eye is coded the same. This is doubly important as the shading of the various diagram components fades across the component itself.
      • Color shouldn't ever be used as a primary mechanism of communication, as the color blind (and generally blind) will not be able to follow. Is there any way that secondary queues could be provided as well?
  • 2.2. Tables of Properties
    1. General - Would recommend inserting three short sections:
      1. Natural Language Names (what they are, where they are used, ...)
      2. The abbreviation or mnemonic ( " )
      3. Parent data types (what the meaning of specializes is)
      4. Prose Definition - purpose, scope, how used
    • THEN put in section 2.2
    1. The fuzziness component is a bit confusing. If they are merely suggestions, perhaps the table components should have similar weasel words (e.g. a possible name, a suggested data type, a suggested definition)?
  • 2.3 Concept Domain Definitions and Bindings
    1. GENERAL This is another section that seems quite out of place. It isn't mentioned in the introductory material and just kind of pops in out of the blue. If I understand it correctly, it applies to the the formal DTDL section, and can be the type of one of the arguments or values. If this is the case, should it be a subsection of the DTDL section? Another possibility would be to eliminate it completely, as DTDL's in general appear to depend on other DTDL's anyway...
    2. P2 There is a lot of non-obvious verbiage here... what is universally bound or even bound for that matter. Does everyone know what an OID is? Why is "code system" spelled "codeSystem"?
    3. P3 "Where possible, a set of illustrative codes from the code system will be provided. For externally defined code systems, the list is illustrative,..." - Not sure I understand where this is going. Are the illustrative codes from non-externally defined code systems not illustrative?
    4. P4 We need some examples here if we're going to include this. Is AddressPartType the only non-hierarchical representation. What does "hierarchichal in nature mean anyway"
    5. "Status" and "Level discussion is just plain confusing.
  • 2.4 Formal Data Type Definition Language(DTDL)
    1. P1 A formal definition of data types is defined here in order to clarify the semantics ... - say, what?
    2. P2
      • The formal definition only specifies the meaning of the data values through statements defining semantic relationships and behavior. - Does the formal specification really specify "meaning" at all? Is this necessary, or can we shorten this to "The formal definition defines the semantic relationships and behavior of conforming data values".
      • ... but the resemblance is semantic: it does not imply any procedural machinery. What does it mean to say the resemblance is semantic? Perhaps the author intended syntactic, or something similar?
      • Concision - "Those who would enforce circumcision on Gentile Christians." or "conciseness: terseness and economy in writing and speaking achieved by expressing a great deal in just a few words". How about Conciseness?
    3. named values of a fully enumerated extension - since this only occurs in one place (right?), how about named values in the case of the Boolean type and just forget about the intension/extension stuff?
    4. P4 ... and signatures of the new type's semantic properties. - unless you can differentiate semantic from non-semantic, don't confuse the poor reader. Properties is properties.
      • 2.4.1 Declaration
        1. P3 - since Boolean is the exception, perhaps we can downplay this little nuance?
        2. P6
          • would recommend moving this up, so the declaration is explained in the order that it occurs (type, alias, specializes...)
            • genus and species? Isn't there a better way to describe this? If we use it, perhaps we should put "genus" and "species" in quotes as this is not a very common usage.
        1. P6 and P7 "Specialization can include the definition of additional properties " - perhaps the "Definition 2" (aka Example 2) could have a more complete example? It would be useful to be able to see what this is talking about.
        2. P8 "It is generally held that inheritance should not retract properties defined for the genus" - it is more than generally held. A "species" cannot retract properties asserted in the "genus". It is possible, however, for a "species" to constrain a non-mandatory "genus" type to only a null value, thereby effectively declaring it as not present.
        3. Abstract - "An abstract type is a type where no non-exceptional value can be of this type." What is an exceptional value? What is an example of an exceptional value being of an abstract type.
      • 2.4.2 Invariant Statements
        1. 2.4.2.2 We need to learn a bit about the X<T> construct before it is introduced in an example. Otherwise it is confusing.
      • 2.4.3 Type Conversion
        1. P2 It isn't clear at this point which direction is a demotion and which is a promotion. Need to stick something in that uses the "genus"/"species" analogy or an equivalent.
        2. P4 - is the
  1. "Definition 7" - you might want to also mention that this is a "promotion" or "demotion" (it isn't clear at this point which goes from "genus" to "species"...
  2. 2.4.3.1 and 2.4.3.2 clarifies the direction, but, if you are going to use the "genus" and "species" notation (or equivalent), use it agaain in these two examples.
  3. Promotion examples - "he specification of the promotion must indicate what these values are or how they can be generated.", yet the examples show no such thing.
  • 2.4.4 Literal Form
  1. Where do other non-literal conversions come into play? Is it necessary to mention this?
  2. Q: "This syntax may therefore not be completely straightforward from a computing perspective." - is it possible for all literal forms to be unambiguously converted back to the corresponding value? This is important to know...
  1. 2.4.4.1 - I'm mssing something here - since all literals convert to strings, what possibile information is added in "Definition 11"?
  • 2.4.5 Generics