Update JADN Type Definition Description (Sect 3.1 & subs)

imjadn-v1.0-cn02.md

@@ -832,7 +832,7 @@ use of JADN in information modeling.
 ## 3.1 JADN Overview
 
 Figure 3-1 provides a high-level view of the JADN concepts that
-will be described in this section. JADN provides simple and
+will be described in this section. JADN provides primitive and
 compound data types that can be refined using type and field
 options (field options only apply within compound types). JADN
 can also be represented in multiple formats, both textual and
@@ -844,6 +844,26 @@ authoritative, but each representation has advantages.
 ###### Figure 3-1 -- JADN Concepts
 ![Figure 3-1 -- JADN Concepts](images/JADN-Concepts.drawio.png)
 
+A JADN schema in its native form is a JSON document containing an object labeled
+"info" and an array labeled "types". 
+
+* The "info" object contains metadata about
+the schema contained in the document, including the types exported from this
+schema and namespace information to connect it with other JADN schema documents.
+
+* The "types" section of the schema document is an array of arrays, with each of
+the inner arrays defining one type in the schema. Each type in the schema
+document will use one of JADN's core types and may be either simple or compound.
+Each type array has five fields, two of which are themselves arrays: one for
+type options and one for the fields or elements that make up a compound type.
+
+* The fields / elements array is always empty in the definition of a primitive type.
+For compound types, each field or element within the fields / elements array is
+also an array, with three items in an element array and five items in a field
+array. 
+
+These structures are illustrated and explained in more detail 
+in [Section 3.1.5.1, Native JSON Representation](#3151-native-json-representation).
 
 The JADN information modeling language was developed against specific objectives:
 
@@ -853,16 +873,15 @@ The JADN information modeling language was developed against specific objectives
  4) Specification is data that can be serialized
  5) Specification has a fixed structure designed for extensibility
 
-As described in the [[JADN Specification](#jadn-v10)] introduction:
+As stated in the [[JADN Specification](#jadn-v10)] introduction:
 
 > JADN is a formal description technique that combines type
 > constraints from the Unified Modeling Language (UML) with data
 > abstraction based on information theory and structural
 > organization using results from graph theory.
 
-> **EDITOR'S NOTE:** consider whether the following adds clarity or
-> confusion; it might need to be re-written to guide the reader
-> through the concepts a bit more.
+> **EDITOR'S NOTE:** adjust and/or remove the following discussion to mesh with
+> the updated introduction.
 
 From UML JADN takes the concept of modeling information/data
 using Simple Classifiers (see [[UML](#uml)], 10.2 Datatypes) as
@@ -872,7 +891,7 @@ way that can be validated and signed.  The JADN use of the UML
 primitive types defined in [[UML](#uml)], Table 21.1, can be found
 in [Appendix D.1](#d1-jadn-vs-uml-primitive-data-types).
 
-The [[JADN Specification](#jadn-v10)] defines twelve base types:
+The [[JADN Specification](#jadn-v10)] defines twelve core types:
 
 | **Primitive** | **Compound** | **Selection /<br> Union** |
 |:-------------:|:------------:|:-------------------------:|
@@ -889,6 +908,8 @@ The [[JADN Specification](#jadn-v10)] defines twelve base types:
 > to use "compound" in order to avoid any potential confusion
 > with UML's use of "structured".
 
+> **To-Do:** The revised figure 3-2 groups Enumerated and Choice under Compound
+> types; need to reconcile the table above and that figure.
 
 
 Each of the compound types is a *container*, a named group of related items
@@ -898,7 +919,7 @@ has *multiplicity* attributes, including limits on the number of items,
 whether the items have a sequential ordering, and whether duplicate items
 are allowed.
 
-The JADN compound type and its options are chosen for an IM based on the
+The JADN compound types and their options are chosen for an IM based on the
 information characteristics to be modeled:
 
 * Array and ArrayOf contain a group of values.
@@ -998,10 +1019,10 @@ The five elements are:
 
  1. A **TypeName**, which is simply a string used to refer to
 that type.
- 2. The **BaseType** of the type, which is one the twelve base
+ 2. The **BaseType** of the type, which is one the twelve core
     types shown in Figure 3-2.
  3. Zero or more of the available JADN **TypeOptions** that
-    refine the base types to fit particular needs.
+    refine the core types to fit particular needs.
  4. An optional **TypeDescription** string that provides
     additional information about the type.
  5. For any of the Compound types, Enumerated, or Choice, a set
@@ -1011,7 +1032,7 @@ that type.
 ###### Figure 3-2 -- JADN Type Definition Structure
 ![JADN Type Definition Structure](images/JADN-Structure_Overlay.png)
 
-A firm requirement of JADN is that a TypeName must not be a JADN
+A firm requirement of JADN is that a TypeName in a schema must not be a JADN
 predefined type. There are also conventions intended to improve
 the consistency and readability of JADN specifications. These
 conventions are defined in JADN but can be overridden within a
@@ -1051,15 +1072,15 @@ Specification:
 > - The first character is the option ID.
 > - The remaining characters are the option value.
 
-TypeOptions are classifiers that, along with the base type,
+TypeOptions are classifiers that, along with the BaseType,
 determine whether data values are instances of the defined type.
 For example, the *pattern* TypeOption is used with the String
 BaseType to define valid instances of that string type using a
 regular expression conforming to [[ECMAScript](#ecmascript)]
 grammar.
 
 Table 3-3 lists the complete set of type options, including the
-option name, type, ID character, and description; the ID
+option name, type, ID character, and description. The ID
 characters are used in standard JADN representation 
 ([section 3.1.5.1](#3151-native-json-representation)) when specifying type
 options.
@@ -1086,7 +1107,7 @@ options.
 |  default   |  String  |   `!`  | Default value                                                     |
 
 Detailed explanations of each type option can be found in
-Sections 3.2.1.1-12 of the [[JADN Specification](#jadn-v10)].
+Sections 3.2.1.1 through 3.2.1.12 of the [[JADN Specification](#jadn-v10)].
 
 The `minv` and `maxv` type options are distinctive in that they
 can apply to both primitive and compound types, with a different
@@ -1236,33 +1257,40 @@ other representations using a simple example.
 
 This section illustrates the JSON representations of the Base
 Types described in [Section 3.1](#31-jadn-overview). Depictions
-are provided for each of three ways that the **Fields** array is
+are provided for overall structure of a JADN schema and for 
+each of three ways that the **Fields** array is
 used, depending on the base type used in a particular type
 definition.
 
-Figure 3-3 illustrates the structure of JADN for defining any
+Figure 3-3 illustrates the top-level structure of a native JADN schema document,
+as described in [Section 3.1](#31-jadn-overview).
+
+###### Figure 3-3 -- JADN Schema Top-Level Structure
+![JADN Schema Top-Level Structure](images/JADN-schema-overview-json.drawio.png)
+
+Figure 3-4 illustrates the structure of JADN for defining any
 Primitive **BaseType**, or ArrayOf or MapOf type; for all of these
 the **Fields** array is empty:
 
-###### Figure 3-3 -- JADN for Primitive, ArrayOf, MapOf Types
+###### Figure 3-4 -- JADN for Primitive, ArrayOf, MapOf Types
 ![JADN for Primitive, ArrayOf, MapOf
 Types](images/JADN-primitive-json.drawio.png)
 
 
-Figure 3-4 illustrates the structure of JADN for defining an
+Figure 3-5 illustrates the structure of JADN for defining an
 Enumerated **BaseType**; for enumerations each item definition in the
 **Fields** array has three elements:
 
-###### Figure 3-4 -- JADN for Enumerated Types
+###### Figure 3-5 -- JADN for Enumerated Types
 ![JADN for Enumerated
 Types](images/JADN-with-items-json.drawio.png)
 
 
-Figure 3-5 illustrates the structure of JADN for defining a
+Figure 3-6 illustrates the structure of JADN for defining a
 **BaseType** of Array, Choice, Map, or Record; for these types each
 field definition in the **Fields** array has five elements:
 
-###### Figure 3-5 -- JADN for Types with Fields
+###### Figure 3-6 -- JADN for Types with Fields
 ![JADN for Types With Fields](images/JADN-with-fields-json.drawio.png)
 
 
@@ -1329,14 +1357,14 @@ point for an example to illustrate the various JADN
 representations described in [Section 3.1.5.2](#3152-alternative-jadn-representations). The example
 begins with the ERD for the model:
 
-###### Figure 3-6 -- Simple University Example ERD
+###### Figure 3-7 -- Simple University Example ERD
 
 <img src="images/university-erd.png" height="600px">
 
 The package (see [Section 4.1](#41-packages-and-namespaces)) 
 containing the JADN corresponding to the above ERD is shown here:
 
-###### Figure 3-7 -- Simple University Example JADN (JSON format)
+###### Figure 3-8 -- Simple University Example JADN (JSON format)
 ```json
 {
  "info": {
@@ -1373,7 +1401,7 @@ containing the JADN corresponding to the above ERD is shown here:
 Converting the JSON to JIDL yields a representation that is both
 more readable and easier to edit:
 
-###### Figure 3-8 -- Simple University Example JADN (JIDL format)
+###### Figure 3-9 -- Simple University Example JADN (JIDL format)
 
 ```
      package: "http://example.com/uni"
@@ -1405,7 +1433,7 @@ which are quite readable but somewhat more challenging to edit
 than JIDL (the package information has been omitted from the set
 of property tables).
 
-###### Figure 3-9 -- Simple University Example JADN (table format)
+###### Figure 3-10 -- Simple University Example JADN (table format)
 
 A place of learning
 
@@ -1447,7 +1475,7 @@ of the example is easily generated from the JADN model.  In this
 specific example code for the widely-used GraphViz tool is
 provided.
 
-###### Figure 3-10 -- Simple University Example ERD Source Code (GraphViz)
+###### Figure 3-11 -- Simple University Example ERD Source Code (GraphViz)
 ```
 # package: http://example.com/uni
 # exports: ['University']
@@ -1645,6 +1673,9 @@ The corresponding JIDL representation would be:
   TrackNumber = Integer   // Track number for current song
 ```
 
+The JADN Integer primitive type encompasses the UML UnlimitedNatural primitive
+type through the use the `minv` Type Option: an Integer with a `minv` of `0` has
+the same range of values as an UnlimitedNatural.
 
 Table 3-7 lists the *format* options applicable to the Integer type:
 
@@ -1693,7 +1724,9 @@ using CBOR; see the [[JADN Specification](#jadn-v10)], Section
 | :--- | :--- | :--- |
 | **f16** | Number | **float16**: Serialize as IEEE 754 Half-Precision Float (#7.25). |
 | **f32** | Number | **float32**: Serialize as IEEE 754 Single-Precision Float (#7.26). |
+| **f64** | Number | **float64**: Serialize as IEEE 754 Single-Precision Float (#7.27). |
 
+> **To-Do:** clarify what the "(#7.xx)" references in the above table point to.
 
 
 #### 3.1.7.5 String
@@ -1963,7 +1996,7 @@ type options in the record's definition and the presence of the
 `optional` keyword on all fields of the record. This reflects a
 design pattern: the compound type's cardinality of `{1..*}`
 defines that there is a minimum number of required fields even
-though every individual field is optional. An empty `Hashes` map
+though every individual field is optional. An empty `Hashes` map is
 invalid, but a map where any one or more of the three hash types
 exists is valid. This is an example of one application of _minv_,
 _maxv_, as described above in [Section 3.1.2](#312-typeoptions).

sources/jadn-structure.plantuml.txt

@@ -1,26 +1,27 @@
 ' ************  JADN Structure figure for JADN-IM CN *************************
 '  Source code for the WBS portion of the JADN-Structure-Overlay.png diagram
 '  Use with the PlantUML online server to generate PNG
-'  Overlay was added using PowerPoint
+'  PUML diagram narrowed by vertical slicing and shifting
+'  Overlay (Primitive / Compound) was added using PowerPoint
 ' ****************************************************************************
 
 @startwbs
-*[#yellow] <size:15>**JADN Type Definition**</size>
-**[#lightgreen] **TypeName**\n{string}
-**[#indianred] <color:white>**BaseType**</color>\n<color:white>{choice}</color>
+*[#yellow] <size:15>**JADN Type Definition Structure**</size>
+**[#lightgreen] **TypeName**\n<i>String</i>
+**[#indianred] <color:white>**BaseType**</color>\n<color:white><i>Choice</i></color>
 ***_ Binary
 ***_ Boolean
 ***_ Integer
 ***_ Number
 ***_ String
-***_ Array
 ***_ ArrayOf(//vtype//)
-***_ Map
 ***_ MapOf(//ktype//, //vtype//)
+***_ Array
+***_ Map
 ***_ Record
 ***_ Choice
 ***_ Enumerated
-**[#violet] **TypeOptions**\nArray {0..n}
+**[#violet] **TypeOptions**\n<i>Array {0..n}</i>
 ***_ id (61)
 ***_ vtype (42)
 ***_ ktype (43)
@@ -37,8 +38,8 @@
 ***_ unordered (98)
 ***_ extend (88)
 ***_ default (33)
-**[#lightgreen] **TypeDescription**\n{string}
-**[#cyan] **Fields**
+**[#lightgreen] **TypeDescription**\n<i>String</i>
+**[#cyan] **Fields**\n<i>Array {0..n}</i>
 ***[#lightcyan] **For Any Of:**\n{Array, Choice,\nMap, or Record}
 ****[#PaleTurquoise]< FieldID\n{integer}
 ****[#PaleTurquoise]< FieldName\n{string}
@@ -51,7 +52,7 @@
 *****_ key (75)
 *****_ link (76)
 ****[#PaleTurquoise]< FieldDescription\n{string}
-***[#lightcyan]< **Unused for:**\n{Binary, Boolean,\nInteger, Number,\nString, Array,,\nArrayOf, MapOf}
+***[#lightcyan]< **Unused for:**\n{Binary, Boolean,\nInteger, Number,\nString, ArrayOf, \nMapOf}
 ***[#Aquamarine]< **For**\n{Enumerated}
 ****[#Aquamarine]< ItemID\n{integer}
 ****[#Aquamarine]< ItemValue\n{string}