Justification

[davaya]

It would be good to have a description of "what problems does it solve" near the beginning, because people aren't going to read about it if they don't know what it adds to the tools and techniques they are currently using. This isn't well-thought-out yet to propose text, but something like:

Problem: different strings representing the same thing can't be compared for equality or sorted into order. There's no way to compare times without converting to a common format; the information 1690402891 decimal or 64C1804B hex correspond to time in a wide variety of formats (XSD has 9 different built-in times):
"07/26/2023 @ 4:21pm"
"2023-07-26T16:21:31+00:00"
"Wed, 26 Jul 2023 16:21:31 +0000"
"Wednesday, 26-Jul-23 16:21:31 UTC"

JSON at least has a number type, but XSD has only strings - "decimal" is a string of digits, and "integer" is a subclass of decimal with no fractional digits. That's backwards, and because XSD doesn't it can't tell that "1.0E6" is the same as "1,000,000" or "1000000".

Problem: UML has four fundamental kinds of collections: ordered/unordered + unique/non-unique. Defining those 4 as information building blocks with standard representations in JSON and XML would allow [25, 89] to be recognized as equal to {"x": 25, "y": 89}

Problem: RDF has widespread adoption, but it is saddled with being based on XML and its string and structure limitations. RDF defines datatypes but does not require support for them or define any mechanism to define them, nobody uses them. An IM could be the basis for an "Information RDF" where "time" information values are distinguished from lexical representations and datatypes like {"x": 25, "y": 89} can be defined, operated on, and reasoned about without the overhead of assigning indices and cluttering the graph with unnecessary nodes. JSON Schema with path property names, regexes, and ABNF as datatype expressions usable directly in RDF/XML should be explored.

(That was the motivation for updating the parsing diagram to include classtype and datatype as distinct kinds of collection).

Problem: complex-to-read schemas. The advantage of using JIDL as a template language for JSON Schema and XSD should be highlighted up front. JADN needs to be translated into existing technologies supported by mature tools in order to be accepted, it can't be pitched as an alternative. The vision of "common front end for XML, JSON, plus CBOR, Protobuf" needs better explanation.

[dlemire60]

CN02 has an up-front section on Motivation for JADN. The introductory paragraph is very concise and could be expanded with a brief summary of the benefits of JADN, something along the lines of:

• Unambiguous definition of the meaning of information separate from its representation for transmission or storage
• Ready translation of JADN models to widely-used format such as JSON Schema and XML Schema that can then be used with common tooling for those formats
• Serialization rules for JSON and CBOR, easily extensible to other representations
• Conversion of representation between formats that preserves the underlying meaning
• Concise, readable format that accurately represents the information model and is readily translatable

This could be followed by a brief example in JIDL form with its corresponding JSON Schema and XSD representations before diving into the 1.1.x subsections. Ideally that example would showcase a meaningful range of JADN data types without trying to be exhaustive (i.e., overwhelming).

More detail related to the problems identified above could be added throughout 1.1.x but starting with "accentuating the positive" seems like a good strategy.

[davaya]

Great set of bullets. The examples in the introduction probably cannot cover a "meaningful range" without being overwhelming, but something with a Record, a Choice and an Enumerated (e.g., an excerpt from the music library) might do the trick.

[dlemire60]

I'm thinking that the Track-Info record from the music library (with some explanatory tweaking of the comments) has enough variety of types, provides a good example of how concise JIDL is vs. JSON or XML schema, and can be supported with a forward reference to the full example later in the document. It does lack a Choice (boo) but does show the use of an Integer as an unambiguous representation of track length (yay).

Track-Info = Record                                // information about the individual audio tracks
   1 track_number     Integer                      // track sequence number
   2 title            String                       // track title
   3 length           Integer{1..*}                // length of track in seconds; 
                                                   // anticipated user display is mm:ss; minimum length is 1 second
   4 audio_format     Audio-Format                 // format of the digital audio (enumeration)
   5 featured_artist  Artist unique [0..*]         // optional notable guest performers 
   6 track_art        Image optional               // each track can have optionally have individual artwork
   7 genre            Genre                        // musical genre of the track (enumeration)

We don't show much by way of examples of Choice in the CN and it isn't actually used in any of the Section 3.3 examples.