DataTypes Comments Section 2

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.
       3. 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.
       4. 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.
       5. 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 - "For example the following is an explicit type conversion demotion (promotion?) from...
       3. 2.4.3.1 and 2.4.3.2 Still leave the issue a bit fuzzy. I'd think that loss of information would be from the child to the parent "species" to "genus" direction, but this isn't absolutely clear, especially as the second sentence says that Generally, this means that a more complex type is converted into a simpler type - which, if you think about the relationship between ST and ED, would make me think that demotion is the other direction. This is more confusing with the IVL/QTY examples, where the isn't a parent/child relationship. I would see the QTY / IVL examples as neither promotion nor demotion, as they don't have a direct relationship to each other - they are different things. These two sections have left me quite confused...
       4. 2.4.4 Literal Form
          1. P2 Where do other non-literal conversions come into play? Is it necessary to mention this?
          2. GENERAL 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...
          3. 2.4.4.1 - I'm mssing something here - since all literals convert to strings, what possible information is added in "Definition 11"?
     • 2.4.5 Generic Data Types
       1. The types MAY be supplied in this specification, in any dependent specification, or even at run-time. - what does it mean to supply types at run-time? How is this done? How does it relate to this specification? ITS?
       2. 2.4.5.1 Generic Collections - can we do something better than the reference to (§ )? As they it resolves to 2.4.5 Generics, could we just say "the previous section on Generics"?
       3. While undoubtedly necessary, some of the information in this section is so involved that it is really difficult to stay focused - especially as we are awaiting examples. I wonder whether it wouldn't make sense to take some of the really minute details and relegate them to an appendix, where we could refer the reader if they really felt the need for pain (sorry... ;-) )
     • 2.5.6 Flavors
       1. P2 - this is a tad confusing. If I understand this correctly, what it really trying to say is that, while very similar techniques are used elsewhere, they aren't true data type flavors. Is this correct? If so, could the explanation be simpler?
       2. GENERAL - I'm curious about the MAY/MUST language here. Since this is a data types specification, shouldn't it just quietly follow its own rules? What does it accomplish by stating them first...