Merge pull request #46 from donmendelson/v2-0-issue35

Better distinction between encoding type and field

Author: donmendelson

v2-0-RC1/doc/01Introduction.md

@@ -137,7 +137,7 @@ and data examples.
 This is a sample encoding specification
 
 ```xml
-<type name="short" primitiveType="int16" semanticType="int" />
+<type name="short" primitiveType="int16"/>
 ```    
 
 This is sample data as it would be transmitted on the wire
@@ -149,7 +149,7 @@ References
 
 ### Related FIX Standards 
 
-*Simple Open Framing Header*, FIX Protocol, Limited. Release Candidate 1
+*Simple Open Framing Header*, FIX Protocol, Limited. Version 1.0 Draft Standard
 specification has been published at
 <http://www.fixtradingcommunity.org/>
 

v2-0-RC1/doc/02FieldEncoding.md

@@ -11,18 +11,17 @@ and message schema but are introduced here as an overview.
 
 ### Semantic data type
 
-The FIX semantic data type of a field tells a data domain in a broad
-sense, for example, whether it is numeric or character data, or whether
-it represents a time or price. Simple Binary Encoding represents all of
+The FIX semantic data type of a field tells a data domain interpreted at the application layer, for example, whether it is numeric or character data, or whether it represents a time or price. Simple Binary Encoding represents all of
 the semantic data types that FIX protocol has defined across all
 encodings. In message specifications, FIX data type is declared with
 attribute semanticType. See the section 2.2 below for a listing of those
 FIX types.
 
 ### Encoding
 
-Encoding tells how a field of a specific data type is encoded on the
-wire. An encoding maps a FIX data type to either a simple, primitive
+Encoding tells how a data element is encoded on the wire. Encoding belongs strictly to the presentation layer. It is context-free and carries no business semantics. 
+
+An encoding maps a FIX data type to either a simple, primitive
 data type, such as a 32 bit signed integer, or to a composite type. A
 composite type is composed of two or more simple primitive types. For
 example, the FIX data type Price is encoded as a decimal, a composite
@@ -142,17 +141,10 @@ Attributes are optional unless specified otherwise.
 | maxValue          | The highest valid value of a range (inclusive unless specified otherwise). Applies to scalar data types, but not to String or data types.                                          |
 | semanticType      | Tells the FIX semantic type of a field or encoding. It may be specified on either a field or its encoding.                                                                         |
 
-### Inherited attributes
-
-The attributes listed above apply to a field element or its encoding
-(wire format). Any attributes specified on an encoding are inherited by
-fields that use that encoding.
-
 ### Non-FIX types
 
 Encodings may be added to SBE messages that do not correspond to listed
-FIX data types. In that case, the encoding and fields that use the
-encoding will not have a semanticType attribute.
+FIX data types. In that case, the fields that use the encoding will not have a semanticType attribute.
 
 Integer encoding
 -------------------------------------------------------------------------------------------------------------------------------------------------------------
@@ -386,17 +378,17 @@ FIX Qty data type is a float type, but a decimal may be constrained to
 integer values by setting exponent to zero.
 
 ```xml
-<composite name="intQty32" semanticType="Qty">
+<composite name="intQty32">
     <type name="mantissa" primitiveType="int32" />
     <type name="exponent" primitiveType="int8"
         presence="constant">0</type>
 </composite>
 ```
 
-Field inherits semanticType from encoding
+A field uses the encoding and adds semanticType.
 
 ```xml
-<field type="intQty32" name="OrderQty" id="38"
+<field type="intQty32" name="OrderQty" id="38" semanticType="Qty"
  description="Total number of shares" />
 ```
 
@@ -515,7 +507,7 @@ control character (code 0).
 This is the standard encoding for char type.
 
 ```xml
-<type name="char" primitiveType="char" semanticType="char" />
+<type name="charType" primitiveType="char"/>
 ```
 
 Wire format of char encoding of "A" (ASCII value 65, hexadecimal 41)
@@ -553,10 +545,9 @@ encoding.
 A typical string encoding specification
 
 ```xml
-<type name="string6" primitiveType="char" semanticType="String"
- length="6" />
+<type name="string6" primitiveType="char" length="6" />
 
-<field type="string6" name="Symbol" id="55" />
+<field type="string6" name="Symbol" id="55" semanticType="String"/>
 ```
 
 Wire format of a character array in character and hexadecimal formats
@@ -568,11 +559,10 @@ M S F T
 A character array constant specification
 
 ```xml
-<type name="EurexMarketID" semanticType="Exchange"
- primitiveType="char" length="4" description="MIC code"
+<type name="EurexMarketID" primitiveType="char" length="4" description="MIC code"
  presence="constant">XEUR</type>
 
-<field type="EurexMarketID" name="MarketID" id="1301" />
+<field type="EurexMarketID" name="MarketID" id="1301" semanticType="Exchange"/>
 ```
 
 ### Variable-length string encoding
@@ -628,9 +618,9 @@ Encoding specification for variable length data up to 65535 octets
 
 ```xml
 <composite name="varString" description="Variable-length string">
-    <type name="length" primitiveType="uint16" semanticType="Length"/>
+    <type name="length" primitiveType="uint16"/>
     <type name="data" length="0" primitiveType="uint8"
-    semanticType="data" characterEncoding="UTF-16"/>
+    characterEncoding="UTF-16"/>
 </composite>
 
 <data name="SecurityDesc" id="107" type="varString"/>
@@ -743,8 +733,8 @@ Encoding specification for variable length data up to 65535 octets
 
 ```xml
 <composite name="DATA" description="Variable-length data">
-    <type name="length" primitiveType="uint16" semanticType="Length"/>
-    <type name="data" length="0" primitiveType="uint8" semanticType="data" />
+    <type name="length" primitiveType="uint16"/>
+    <type name="data" length="0" primitiveType="uint8"/>
 </composite>
 
 <data name="RawData" id="96" type="DATA"/>
@@ -797,7 +787,7 @@ required and optional elements.
 The standard encoding specification for MonthYear
 
 ```xml
-<composite name="monthYear" semanticType="MonthYear">
+<composite name="monthYear">
     <type name="year" primitiveType="uint16" presence="optional"
     nullValue="65536" />
     <type name="month" primitiveType="uint8" minValue="1" maxValue="12" />
@@ -810,7 +800,9 @@ The standard encoding specification for MonthYear
 
 Example MonthYear field specification
 
-<field type="monthYear" name="MaturityMonthYear" id="200" />
+```xml
+<field type="monthYear" name="MaturityMonthYear" id="200"  semanticType="MonthYear"/>
+```
 
 Wire format of MonthYear 2014 June week 3 as hexadecimal
 
@@ -869,7 +861,7 @@ Enumeration of time units:
 Timestamp with variable time units:
 
 ```xml
-<composite name="UTCTimestamp" description="UTC timestamp with precision on the wire" semanticType="UTCTimestamp" >
+<composite name="UTCTimestamp" description="UTC timestamp with precision on the wire">
     <type name="time" primitiveType="uint64" />
     <type name="unit" primitiveType="uint8" />
 </composite>
@@ -878,7 +870,7 @@ Timestamp with variable time units:
 Timestamp with constant time unit:
 
 ```xml
-<composite name="UTCTimestampNanos" description="UTC timestamp with nanosecond precision" semanticType="UTCTimestamp" >
+<composite name="UTCTimestampNanos" description="UTC timestamp with nanosecond precision">
     <type name="time" primitiveType="uint64" />
     <type name="unit" primitiveType="uint8" presence="constant" valueRef="TimeUnit.nanosecond" />
 </composite>
@@ -887,7 +879,7 @@ Timestamp with constant time unit:
 Time only with variable time units:
 
 ```xml
-<composite name="UTCTime" description="Time of day with precision on the wire" semanticType="UTCTimeOnly" >
+<composite name="UTCTime" description="Time of day with precision on the wire">
     <type name="time" primitiveType="uint64" />
     <type name="unit" primitiveType="uint8" />
 </composite>
@@ -896,7 +888,7 @@ Time only with variable time units:
 Time only with constant time unit:
 
 ```xml
-<composite name="UTCTimeNanos" description="Time of day with millisecond precision" semanticType="UTCTimeOnly" >
+<composite name="UTCTimeNanos" description="Time of day with millisecond precision">
     <type name="time" primitiveType="uint64" />
     <type name="unit" primitiveType="uint8" presence="constant" valueRef="TimeUnit.millisecond" />
 </composite>
@@ -905,7 +897,7 @@ Time only with constant time unit:
 Date only specification:
 
 ```xml
-<type name="date" primitiveType="uint16" semanticType="UTCDateOnly" />
+<type name="date" primitiveType="uint16"/>
 ```
 
 ### Examples of date/time fields
@@ -915,7 +907,7 @@ hours, 17 minutes and 22 seconds since the UNIX epoch) with default
 schema attributes
 
 ```xml
-<composite name="UTCTimestampNanos" description="UTC timestamp with nanosecond precision" semanticType="UTCTimestamp" >
+<composite name="UTCTimestampNanos" description="UTC timestamp with nanosecond precision">
 <type name="time" primitiveType="uint64" />
 <type name="unit" primitiveType="uint8" presence="constant" valueRef="TimeUnit.nanosecond" />
 </composite>
@@ -930,7 +922,7 @@ byte order
 since midnight UTC) with default schema attributes
 
 ```xml
-<composite name="UTCTimeOnlyNanos" description="UTC time of day with nanosecond precision" semanticType="UTCTimeOnly" >
+<composite name="UTCTimeOnlyNanos" description="UTC time of day with nanosecond precision">
     <type name="time" primitiveType="uint64" />
     <type name="unit" primitiveType="uint8" presence="constant" valueRef="TimeUnit.nanosecond" />
 </composite>
@@ -944,7 +936,7 @@ Wire format of UTCTimeOnly
 default schema attributes
 
 ```xml
-<type name="date" primitiveType="uint16" semanticType="UTCDateOnly" />
+<type name="date" primitiveType="uint16"/>
 ```
 
 Wire format of UTCDateOnly
@@ -964,7 +956,7 @@ time at the market instead of UTC time.
 The standard encoding specification for LocalMktDate
 
 ```xml
-<type name="localMktDate" primitiveType="uint16" semanticType="LocalMktDate" />
+<type name="localMktDate" primitiveType="uint16"/>
 ```
 
 Local time encoding
@@ -997,7 +989,7 @@ elements within the composite encoding. See section 4.4.4.3 below.
 Standard TZTimestamp encoding specification
 
 ```xml
-<composite name="tzTimestamp" semanticType="TZTimestamp">
+<composite name="tzTimestamp">
     <type name="time" primitiveType="uint64" />
     <type name="unit" primitiveType="uint8" />
     <!-- Sign of timezone offset is on hour subfield -->
@@ -1036,7 +1028,7 @@ elements within the composite encoding. See section 4.4.4.3 below.
 Standard TZTimeOnly encoding specification
 
 ```xml
-<composite name="tzTimeOnly" semanticType="TZTimeOnly">
+<composite name="tzTimeOnly">
     <type name="time" primitiveType="uint64" />
     <type name="unit" primitiveType="uint8" />
     <!-- Sign of timezone offset is on hour subfield -->
@@ -1169,13 +1161,7 @@ Standard encoding specifications for required and optional Boolean
 fields
 
 ```xml
-<enum name="booleanEnum" encodingType="uint8" semanticType="Boolean">
-    <validValue name="false">0</validValue>
-    <validValue name="true">1</validValue>
-</enum>
-
-<enum name="optionalBoolean" encodingType="uint8" presence="optional"
-    nullValue="255" semanticType="Boolean">
+<enum name="booleanEnum" encodingType="uint8">
     <validValue name="false">0</validValue>
     <validValue name="true">1</validValue>
 </enum>
@@ -1184,7 +1170,9 @@ fields
 Example optional Boolean field
 
 ```xml
-<field type="optionalBoolean" name="SolicitedFlag" id="377" />
+<field type="requiredBoolean" name="SolicitedFlag" id="377" presence="required" semanticType="Boolean" />
+
+<field type="optionalBoolean" name="SolicitedFlag" id="377" presence="optional" nullValue="255" semanticType="Boolean" />
 ```
 
 Wire format of true value as hexadecimal

v2-0-RC1/doc/03MessageStructure.md

@@ -439,7 +439,7 @@ Recommended encoding of repeating group dimensions
 ```xml
 <composite name="groupSizeEncoding">
     <type name="blockLength" primitiveType="uint16"/>
-    <type name="numInGroup" primitiveType="uint16" semanticType="NumInGroup"/>
+    <type name="numInGroup" primitiveType="uint16"/>
 	<type name="numGroups" primitiveType="uint16" />
     <type name="numVarDataFields" primitiveType="uint16" />
 </composite>
@@ -454,7 +454,7 @@ any repeating groups or variable-length fields.
 
 The number of entries in this repeating group, called NumInGroup in FIX.
 
-##### Number of repeating groups
+#### Number of repeating groups
 
 A count nested repeating groups in this repeating group.
 
@@ -473,7 +473,7 @@ The occurrences of a repeating group may be restricted to a specific range by mo
 Example of a restricted group encoding
 
 ```xml
-<type name="numInGroup" primitiveType="uint16" semanticType="NumInGroup" minValue="1" maxValue="10" />
+<type name="numInGroup" primitiveType="uint16" minValue="1" maxValue="10" />
 ```
 
 Sequence of message body elements