Data Type Definition: Central Object

[knelson-farmbeltnorth]

The Data Type Definition (see #87) intends to replace both Representation and ContextItemDefinition in the ADAPT Standard. It has the following concepts:

1. Identifier Code. This is the key by which any usage would refer to the definition. See #89
2. Version. Following the Context Item paper, any non-zero value represents a change from a prior version. A data modeler may include an attribute on the LoggedVariable to signal that version used.
3. Base Type. I've extended the 3 types currently in the representation system with Flag (i.e., boolean / indicator). I purposely omitted Date Time, which I would advocate can be represented as an ISO 8601 string or 64bit integer at the DTD may define.
4. Localizations. I did not include a default name or description. Rather, each DTD requires 1 or more Localizations which themselves contain the definitions. Enumeration Items follow the same pattern, containing only a numeric code.
5. Presentations. See #90
6. Geo Political Context. See #91
7. Keywords. Optional query terms defined by the authors of the DTD, relevant only to the published instance of the definitions.
8. IsRetired flag, allowing for deprecation within the published definitions list.
9. Per-Type Attributes a. Enumeration. Each item has a numeric code and one or more localized names for the item. Also, there is a default item code. b. Text. An optional validation Regex. c. Numeric. i. One of several strict types allowing for concise binary representations of the data. ii. UOM Code. Required. Each item will carry a mandatory UOM. iii. Optional Minimum/Maximum/Default values universally applicable to the Data Type Definition. These are separate from user-defined Min/Max/Defaults which are coded as a usage attribute on the variable instance.

[knelson-farmbeltnorth]

Initial discussion in 15 March 2023 meeting. Feedback from the group:

• Should the DTD have a default localization? No strong opinions.
• Presentation indeed does not seem to belong in a data type registry. It may make sense to include as a defined structure in which an individual data modeler can pass known presentations to his consumers. I.e., within instances of the model vs. in the list of standard types
• It may be useful to augment NumericAttributes with number of significant digits.

[knelson-farmbeltnorth]

Adding 3 examples for discussion:

Numeric variable recorded in an Operation

Enumerated variable on an ADAPT Object

Text variable as a Context Item

[knelson-farmbeltnorth]

The above examples invite the question of whether the Keywords property should be moved to each individual Localization object.

[knelson-farmbeltnorth]

Agreement in the 22 March 2023 meeting to add name and description in English as required attributes on the DTD and Enumerated Items objects themselves. They may match one or more of the English localizations.

Also discussed was the need for reintroduction of the Model Scope concept, with a form to be determined.

[jim-wilson-kt]

I recommend changing the statement: "They may match one or more of the English localizations."

To this: "If one English localization is specified, they must match. If two or more English localizations is specified, they must match one of them with the same English localization used for all DTDs, and they may match other English localizations."

My reason for suggesting this is that it would be unclear to an implementer why a DTD name/description in English would differ from all English localizations of that name/description, which would be possible without the change I suggested.

[jim-wilson-kt]

I offer the following diagram to demonstrate a built-in GitHub feature. While a reproduction of one of Kelly's diagrams above (incomplete with likely errors), this diagram does not offer commentary or propose changes. Also, I am not proposing that people switch from their diagramming tool of choice to this. Just making you aware of an option. Check out this post's markdown source. (Note the rendering bug with multiline properties spilling over into the methods compartment. It's probably not an issue in practice since one would have property information expressed on multiple lines.) By the way, I could have made an ERD diagram like Kelly did.

---
title: Data Type Definition
---
classDiagram
    direction TB

    note "Product\n\n-Reference Id: 726\n-Description: UAN\n-Product Type (defined as DTD 2): 1"

    DataTypeDefinition "1" o-- "*" Localization1
    DataTypeDefinition "1" o-- "0..1" EnumeratedAttributes
    EnumeratedAttributes "1" o-- "*" EnumerationItem
    EnumerationItem "1" o-- "*" Localization2

    class DataTypeDefinition{
        -Identifier Code: 2
        -Version: 0
        -Base type: Enumerated
        -Localizations - see at left
        -Keywords: Product, Seed, Chemical
        -IsRetired: false
        Enumerated Attributes - see below
    }
    class Localization1{
        Language - en-US
        Label - Product Type
        Description - Classification of\nof the product as recorded in the\nADAPT model.
    }
    class Localization2{
        Language - en-US
        Label - Crop Nutrition
        Description - A product that\nprovides nutrients - a fertilizer
    }
    class EnumeratedAttributes{
        -Items - See at left
        -Default item code: 0
    }
    class EnumerationItem{
        -Code 1
        -Localizations - see above
    }

[knelson-farmbeltnorth]

Uploading revised diagrams for discussion to include name/description and a basic implementation of DTD scope

[knelson-farmbeltnorth]

Agreement in 5 April 2023 meeting that Scope should be a listing of ADAPT object names, not a textual description. Preliminary agreement to remove Presentation from the model.

[knelson-farmbeltnorth]

Open questions: -Is it satisfactory to have a list of strings corresponding to ADAPT object names as the Scope? -Do Keywords belong on the central object or on the Localization? -When would we retire a DTD? -Is "DataTypeDefinition" the correct name of this system or should we leave it as "Representation?"

[knelson-farmbeltnorth]

Decided in 19 & 26 April 2023 meetings: -Scope will be a list of enumerated values pointing to a single enumeration containing a list of ADAPT objects to which these data can be affixed. -Keywords & IsRetired will be left as proposed above. -We will continue to use "DataTypeDefinition."