Skip to content

Offsets within composite types #11 #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Dec 21, 2015
Merged

Offsets within composite types #11 #14

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
67db0ef
Offsets within composite types #11
donmendelson Dec 14, 2015
c914e26
Composites reusing other types #12
donmendelson Dec 14, 2015
39fb8e8
Change name "positionAttributes" to "alignmentAttributes".
donmendelson Dec 21, 2015
0968985
#11 offset within composite
donmendelson Dec 21, 2015
f0c92a7
Update 04MessageSchema.md
donmendelson Dec 21, 2015
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 39 additions & 8 deletions v1-0-RC4/doc/04MessageSchema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -58,7 +58,7 @@ their encodings.
| id | Unique identifier of a schema | unsignedInt | | Should be unique between counterparties |
| version | Version of this schema | nonnegativeInteger | | Initial version is zero and is incremented for each version |
| semanticVersion | Version of FIX semantics | string | optional | FIX versions, such as “FIX.5.0\_SP2” |
| byteOrder | Byte order of encoding | token | default = littleEndian | littleEndian bigEndian |
| byteOrder | Byte order of encoding | token | default = littleEndian | littleEndian bigEndian |
| description | Documentation of the schema | string | optional | |
| headerType | Name of the encoding type of the message header, which is the same for all messages in a schema. | string | default= messageHeader | An encoding with this name must be contained by \<types\>. |

Expand Down Expand Up @@ -145,8 +145,7 @@ The element value represents a constant if attribute
| maxValue | Highest acceptable value | string | | |
| length | Number of elements of the primitive data type | nonnegativeInteger | default = 1 | Value “0” represents variable length. |
| offset | If a member of a composite type, tells the offset from the beginning of the composite. By default, the offset is the sum of preceding element sizes, but it may be increased to effect byte alignment. | unsignedInt | optional | See section 4.4.4.3 below |
| primitiveType | The primitive data type that backs the encoding | token | required | char int8 int16 int32 int64 uint8 uint16 uint32 uint64 float double
|
| primitiveType | The primitive data type that backs the encoding | token | required | char int8 int16 int32 int64 uint8 uint16 uint32 uint64 float double |
| semanticType | Represents a FIX data type | token | optional | Same as field semanticType – see below. |
| sinceVersion | Documents the version of a schema in which a type was added | nonnegativeInteger | default = 0 | Must be less than or equal to the version of the message schema. |
| deprecated | Documents the version of a schema in which a type was deprecated. It should no longer be used in new messages. | nonnegativeInteger | optional | Must be less than or equal to the version of the message schema. |
Expand Down Expand Up @@ -208,7 +207,7 @@ constant exponent, which is not sent on the wire.

If a message designer wishes to control byte boundary alignment or map
to an existing data structure, element offset may optionally be
specified on simple types within a composite type. Offset is the number
specified on a simple type, enum or bitset within a composite type. Offset is the number
of octets from the start of the composite; it is a zero-based index.

If specified, offset must be greater than or equal to the sum of the
Expand All @@ -221,6 +220,37 @@ For a composite type, nullness is indicated by the value of its first
element. For example, if a price field is optional, a null value in its
mantissa element indicates that the price is null.

### Reference to reusable types

A composite type often has its elements defined in-line within the `<composite>` XML element as shown in the example above. Alternatively, a common type may be defined once on its own, and then referred to by name with the composite type using a `<ref>` element.

#### `<ref>` attributes

| \<ref\> attribute | Description | XML type | Usage | Valid values |
|--------------------|----------------------------------------------------------------------------------------------------------------|--------------------|-------------|------------------------------------------------------------------|
| name | Usage of the type in this composite | symbolicName\_t | required | |
| type | Name of referenced encoding | symbolicName\_t | required | Must match a defined type, enum or set name attribute. |
| sinceVersion | Documents the version of a schema in which a type was added | nonnegativeInteger | default = 0 | Must be less than or equal to the version of the message schema. |
| deprecated | Documents the version of a schema in which a type was deprecated. It should no longer be used in new messages. | nonnegativeInteger | optional | Must be less than or equal to the version of the message schema. |

#### Type reference example

In this example, a futuresPrice is encoded as 64 bit integer mantissa, 8 bit exponent, and a reused enum type. Note that a
reference may carry an offset within the composite encoding that contains it.

```xml
<enum name="booleanEnum" encodingType="uint8" semanticType="Boolean">
<validValue name="false">0</validValue>
<validValue name="true">1</validValue>
</enum>

<composite name="futuresPrice">
<type name="mantissa" primitiveType="int64" />
<type name="exponent" primitiveType="int8" />
<ref name="isSettlement" type="boolEnum" offset="9" />
</composite>
```

### Enumeration encodings

An enumeration explicitly lists the valid values of a data domain. Any
Expand All @@ -238,10 +268,10 @@ The encoding of an enumeration may be char or any unsigned integer type.
|--------------------|----------------------------------------------------------------------------------------------------------------|--------------------|-------------|-----------------------------------------------------------------------------------|
| name | Name of encoding | symbolicName\_t | required | Must be unique among all encoding types. |
| description | Documentation of the type | string | optional | |
| encodingType | Name of a simple encoding type | symbolicName\_t | required | Must match the name attribute of a scalar \<type\> element *or* a primitive type: char uint8 uint16 uint32 uint64
| sinceVersion | Documents the version of a schema in which a type was added | nonnegativeInteger | default = 0 | Must be less than or equal to the version of the message schema. |
| encodingType | Name of a simple encoding type | symbolicName\_t | required | Must match the name attribute of a scalar \<type\> element *or* a primitive type: char uint8 uint16 uint32 uint64 |
| sinceVersion | Documents the version of a schema in which a type was added | nonnegativeInteger | default = 0 | Must be less than or equal to the version of the message schema. |
| deprecated | Documents the version of a schema in which a type was deprecated. It should no longer be used in new messages. | nonnegativeInteger | optional | Must be less than or equal to the version of the message schema. |

| offset | If a member of a composite type, tells the offset from the beginning of the composite. By default, the offset is the sum of preceding element sizes, but it may be increased to effect byte alignment. | unsignedInt | optional |

#### `<validValue>` element attributes

Expand Down Expand Up @@ -300,6 +330,7 @@ The encoding of a bitset should be an unsigned integer type.
| encodingType | Name of a simple encoding type | string | required | Must match the name attribute of a scalar \<type\> element *or* a primitive type: uint8 uint16 uint32 uint64 |
| sinceVersion | Documents the version of a schema in which a type was added | nonnegativeInteger | default = 0 | Must be less than or equal to the version of the message schema. |
| deprecated | Documents the version of a schema in which a type was deprecated. It should no longer be used in new messages. | nonnegativeInteger | optional | Must be less than or equal to the version of the message schema.
| offset | If a member of a composite type, tells the offset from the beginning of the composite. By default, the offset is the sum of preceding element sizes, but it may be increased to effect byte alignment. | unsignedInt | optional |

#### `<choice>` element attributes

Expand Down Expand Up @@ -558,4 +589,4 @@ Reserved element names
| unit | timestamp, TZ time |
| version | messageHeader |
| week | MonthYear |
| year | MonthYear |
| year | MonthYear |
43 changes: 29 additions & 14 deletions v1-0-RC4/resources/SimpleBinary1-0.xsd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -171,13 +171,6 @@
<xs:attribute name="maxValue" type="xs:string" use="optional" />
<xs:attribute name="length" type="xs:nonNegativeInteger"
default="1" />
<xs:attribute name="offset" type="xs:unsignedInt" use="optional">
<xs:annotation>
<xs:documentation>Offset from start of a composite type as a
zero-based index.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="primitiveType" use="required">
<xs:simpleType>
<xs:restriction base="xs:token">
Expand All @@ -197,6 +190,7 @@
</xs:attribute>
<xs:attribute name="characterEncoding" type="xs:string"
use="optional" />
<xs:attributeGroup ref="sbe:alignmentAttributes" />
<xs:attributeGroup ref="sbe:presenceAttributes" />
<xs:attributeGroup ref="sbe:semanticAttributes" />
<xs:attributeGroup ref="sbe:versionAttributes" />
Expand All @@ -215,8 +209,10 @@
<xs:element name="enum" type="sbe:enumType" />
<xs:element name="set" type="sbe:setType" />
<xs:element name="composite" type="sbe:compositeDataType" />
<xs:element name="ref" type="sbe:refType" />
</xs:choice>
<xs:attribute name="name" type="sbe:symbolicName_t" use="required" />
<xs:attributeGroup ref="sbe:alignmentAttributes" />
<xs:attributeGroup ref="sbe:semanticAttributes" />
<xs:attributeGroup ref="sbe:versionAttributes" />
</xs:complexType>
Expand All @@ -234,6 +230,7 @@
<xs:attribute name="name" type="sbe:symbolicName_t" use="required" />
<xs:attribute name="encodingType" type="sbe:symbolicName_t"
use="required" />
<xs:attributeGroup ref="sbe:alignmentAttributes" />
<xs:attributeGroup ref="sbe:semanticAttributes" />
<xs:attributeGroup ref="sbe:versionAttributes" />
</xs:complexType>
Expand All @@ -254,6 +251,19 @@
</xs:simpleContent>
</xs:complexType>

<xs:complexType name="refType" mixed="true">
<xs:annotation>
<xs:documentation>
A reference to any existing encoding type (simple type, enum or set)
to reuse as a member of a composite type
</xs:documentation>
</xs:annotation>
<xs:attribute name="name" type="sbe:symbolicName_t" use="required" />
<xs:attribute name="type" type="sbe:symbolicName_t" use="required" />
<xs:attributeGroup ref="sbe:alignmentAttributes" />
<xs:attributeGroup ref="sbe:versionAttributes" />
</xs:complexType>

<xs:complexType name="setType" mixed="true">
<xs:annotation>
<xs:documentation>
Expand All @@ -266,6 +276,7 @@
<xs:attribute name="name" type="sbe:symbolicName_t" use="required" />
<xs:attribute name="encodingType" type="sbe:symbolicName_t"
use="required" />
<xs:attributeGroup ref="sbe:alignmentAttributes" />
<xs:attributeGroup ref="sbe:semanticAttributes" />
<xs:attributeGroup ref="sbe:versionAttributes" />
</xs:complexType>
Expand Down Expand Up @@ -302,13 +313,6 @@
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="offset" type="xs:unsignedInt" use="optional">
<xs:annotation>
<xs:documentation>Offset from start of a block as a zero-based
index.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<!-- start of time period - default is UNIX epoch -->
<xs:attribute name="epoch" type="xs:string" default="unix" />
<xs:attribute name="timeUnit" type="xs:string" default="nanosecond">
Expand All @@ -317,6 +321,7 @@
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attributeGroup ref="sbe:alignmentAttributes" />
<xs:attributeGroup ref="sbe:presenceAttributes" />
<xs:attributeGroup ref="sbe:semanticAttributes" />
<xs:attributeGroup ref="sbe:versionAttributes" />
Expand Down Expand Up @@ -359,6 +364,16 @@
</xs:attribute>
</xs:attributeGroup>

<xs:attributeGroup name="alignmentAttributes">
<xs:attribute name="offset" type="xs:unsignedInt" use="optional">
<xs:annotation>
<xs:documentation>Offset from start of a composite type or block
as a zero-based index.
</xs:documentation>
</xs:annotation>
</xs:attribute>
</xs:attributeGroup>

<xs:attributeGroup name="presenceAttributes">
<xs:attribute name="presence" default="required">
<xs:simpleType>
Expand Down