Version 1.0.0.13

This is the first offical version of the CLOD document definition.

Note

This version has been deprecated in favor of Version 2.0.0.14

1. Railroad Diagram

2. Segments

The CLOD document is broken into Segments by the Segment Terminator as defined by the Base Definition.

2.A. Segment Types

There are two additional types of Segments defined here besides the Base Control Segment: Control Segments and Data Segments.

3. Elements

Each Segment is broken into Elements by the Element Separator as defined by the Base Definition.

3.A. Element Count

There will be 4 and only 4 Elements in each of these additional Segments.

3.B. Identification Element

The first Element will be the Identification Element.

3.B.1. Uniqueness

The Identification Element will be unique for every Segment.

3.B.2. Non-Zero ID

The Identification Element cannot be DIGIT ZERO (30_hex), as that Identification is reserved to represent the CLOD document itself.

3.B.3. Exclusions

The Identification Element must not contain any characters that are defined by Base.[Control Characters], the Element Separator or the Segment Terminator.

3.B.4. Requirement

The Identification Element is mandatory and can not be empty.

3.C. Parent Element

The second Element will be the Parent Element.

3.C.1. Definition

The Parent Element for Segments will be the Identification Element value of that Segment's parent. Any Segments that only have the CLOD document as their parent will have a Parent Element equal to DIGIT ZERO (30_hex).

3.C.2. Exclusions

The Parent Element must not contain any characters that are defined by Base.[Control Characters], the Element Separator or the Segment Terminator.

3.C.3. Requirement

The Parent Element is mandatory and can not be empty.

3.D. Name Element

The third Element will be the Name Element.

3.D.1. Exclusions

The Name Element must not contain any characters that are defined by Base.[Control Characters], the Element Separator or the Segment Terminator.

3.D.2. Requirement

The Name Element is mandatory, but unless it is further defined in this Type definition, it can be empty.

3.E. Content Element

The fourth Element will be the Content Element.

3.E.1. Data Type

The Content Element is to be considered a string data type for the immediate processing of the CLOD document. Any further Data Type definitions are defined in a CLOD Schema document.

3.E.2. Exclusions

The Content Element must not contain any characters that are defined by Base.[Control Characters], the Element Separator or the Segment Terminator.

3.E.3. Requirement

The Content Element is mandatory, but unless it is further defined in this Type definition, it can be empty.

3.F. Repetition Separator

The Repetition Separator is used to separate a Content Element into unindexed array members of the Parent Element's Data Type as defined by a CLOD Schema document.

3.F.1. Allowed Values

The Repetition Separator will be CIRCUMFLEX ACCENT (5E_hex).

3.F.2. Example

57|45|colors|red^green^blue^orange~

4. Control Segments

Control Segments are defined as segments whose Identification Element is composed of characters that are defined by Base.[Letters]. Their purpose is to provide information about the CLOD document.

4.A. Name Element Requirement

The Name Element can not be empty.

4.B. Content Element Requirement

The Content Element can not be empty.

4.C. First Control Segment

The First Control Segment is immediately after the Base Segment in the CLOD document.

4.C.1. Purpose

To define the beginning of the CLOD document data and to uniquely define the CLOD document by using a UUID.

4.C.2. Element Values

• Identification = "first"
• Parent = 0
• Name = "uuid"
• Content = a hyphenated UUID without enclosing braces.

4.C.3. Example

first|0|uuid|aeaaecec-6d0d-45a0-9dea-c2b232e731e2~

4.C.4. Requirement

The First Control Segment is mandatory.

4.C.5. Quantity

There can be only one First Control Segment per CLOD document.

4.C.8. CLOD Regeneration

When a CLOD document is regenerated from source data, it must have a new UUID, even if the data it contains has not changed from prior CLOD documents.

4.C.9. CLOD Retransmission

When an existing CLOD document is retransmitted, it does not need a new UUID.

4.D. Specification Control Segment

The Specification Control Segment is after the First Control Segment and before any Data Segments in the CLOD document.

4.D.1. Purpose

To define the location of where the Specification for the CLOD Version can be found.

4.D.2. Element Values

• Identification = "specification"
• Parent = 0
• Name = "url"
• Content = a URL that contains the specification and any other supporting documentation for the CLOD Version.

4.D.3. Example

specification|0|url|https://clod.omegatower.net/versions/1-0-0-13/~

4.D.4. Requirement

The Specification Control Segment is recommended, but not mandatory.

4.D.5. Quantity

There can be only one Specification Control Segment per CLOD document.

4.E. Last Control Segment

The Last Control Segment is the last Segment in the CLOD document.

4.E.1. Purpose

To define the ending of the CLOD document and to contain the total count of Data Segments.

4.E.2. Element Values

• Identification = "last"
• Parent = 0
• Name = "count"
• Content = The total count of Data Segments in the CLOD document. NOTE: This is not guaranteed to be the highest value of Identification Element, as the Identification Element is not required to be sequential or any specific set of values.

4.E.3. Example

last|0|count|14~

4.E.4. Requirement

The Last Control Segment is mandatory.

4.E.5. Quantity

There can be only one Last Control Segment per CLOD document.

5. Data Segments

Data Segments are defined as segments whose Identification Element is composed of characters that are defined by Base.[Integers]. Their purpose is to contain the data that is being described by the CLOD document.

5.A. Dataset Schema Segment

A Dataset Schema Segment is defined as any Data Segment whose Parent Element is DIGIT ZERO (30_hex) as this represents the CLOD document itself. A Dataset is defined as all Dataset Data Segments that can trace their parentage back to a common Dataset Schema Segment.

5.A.1. Schema Name

The Name Element of any Dataset Schema Segment is the name of the Schema. All Datasets in a CLOD document with whose Dataset Schema Segment's Name Element match must follow the same Schema, whether that Schema is explicitly defined or not. The Name element of the Dataset Schema Segment can not be empty.

5.A.2. Schema URL

The Content Element of any Dataset Schema Segment can only be either empty or a URL that points to the Formal Schema document or Informal Schema documentation for this Dataset and its children. It is highly suggested that all Dataset Schema Segments have matching Schema documentation.

5.A.3. Example

1|0|recipe|https://clod.omegatower.net/schema-files/otdp/recipe-v1.clod~

5.A.4. Requirement

Each CLOD document must have at least one Dataset Schema Segment.

5.A.5. Quantity

Each CLOD document can contain multiple Dataset Schema Segments. If there are multiple Dataset Schema Segments in the CLOD document, they do not have to match.

5.A.6. Validity

If a Schema URL is defined, then a CLOD document will be considered invalid by all validity checking and parsing tools if the data in the CLOD document does not conform to all the requirements and specifications of that Schema file.

5.B. Dataset Data Segment

A Dataset Data Segment is defined as any Data Segment whose Parent Element is not DIGIT ZERO (30_hex) as this represents the CLOD document itself.

5.B.1. Purpose

The Dataset Data Segments of a CLOD document is where the bullk of the data will reside.

5.B.2. Example

61|60|1|Place all ingredients into medium sized bowl.~

5.B.3. Requirement

Each CLOD document must have at least one Dataset Data Segment.

5.B.4. Quantity

Each CLOD document can contain an unlimited number of Dataset Data Segments.

5.B.5. String Data

If the Name Element contains characters that are not defined by Base.[Integers], then the Data Segment is its own Data Type as defined by a CLOD Schema document.

5.B.6. Integer Data

If the Name Element only contains characters that are defined by Base.[Integers], then the Data Segment is an indexed array member of the Parent Element's Data Type as defined by a CLOD Schema document.

5.B.7. Empty Data

If the Name Element is empty, then the Data Segment is an unindexed array member of the Parent Element's Data Type as defined by a CLOD Schema document.

5.B.8. Validity

If a Schema URL is defined, then a CLOD document will be considered invalid by all validity checking and parsing tools if the data in the CLOD document does not conform to all the requirements and specifications of that Schema file.

5.C. Character References

The data in the Name and Content Elements can be encoded with Numeric Character References or Named Entities.

5.C.1. Segment Terminator Encoding

The Segment Terminator must be converted to a Numeric Character Reference or Named Entity when it is used in the Name or Content Elements.

5.C.2. Element Separator Encoding

The Element Separator must be converted to a Numeric Character Reference or Named Entity when it is used in the Name or Content Elements.

5.C.3. Repetition Separator Encoding

The Repetition Separator must be converted to a Numeric Character Reference or Named Entity when it is used in the Name or Content Elements.

5.D. NULL Values

There is no distinction between an empty Content Element and a NULL Content Element for the immediate processing of the CLOD document. Any further Data Type definitions are defined in the CLOD Schema document for the CLOD Dataset.

5.E. Data Typing

All further data typing, definitions, descriptors, limitations, etc... of the data in the CLOD document are defined in the CLOD Schema document for the CLOD Dataset.

5.F. Order

The Dataset Data Segments do not have to be in any specified order in the CLOD document. It is possible they are ordered by Identification. It is also possible they are ordered by Parent, then Identification. It is further possible that they are in any other order, including random. However, when a Parent Element's children are processed, they will be processed in sequential, numeric ascending order by their ID value.

6. Reserved Characters

The following characters are reserved for special use:

• CIRCUMFLEX ACCENT (5E_hex)