Skip to content

Commit 90e7e88

Browse files
committed
Update 05SchemaExtensionMechanism.md
Added statement that suggested strategy is non-normative.
1 parent 30ac579 commit 90e7e88

File tree

1 file changed

+5
-3
lines changed

1 file changed

+5
-3
lines changed

v1-0-RC4/doc/05SchemaExtensionMechanism.md

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -35,7 +35,7 @@ Compatibility is only ensured under these conditions:
3535
wire format does not change.
3636

3737
Changes that break those constraints require consumers to update to the
38-
current schema used by publishers. An message template that has changed in an incompatible way should be assinged a new template "id" attribute.
38+
current schema used by publishers. An message template that has changed in an incompatible way must be assinged a new template "id" attribute.
3939

4040
Message schema features for extension
4141
-------------------------------------
@@ -115,13 +115,15 @@ encoding.
115115

116116
Comaptibility strategy
117117
-----------------------
118-
A message decoder should compare the schema version in a received message header to the version that the decoder was built with.
118+
*This suggested strategy is non-normative.*
119+
120+
A message decoder compares the schema version in a received message header to the version that the decoder was built with.
119121

120122
If the *received version is equal to the decoder's version*, then all fields known to the decoder may be parsed, and no further analysis is required.
121123

122124
If the *received version is greater than the decoder's version* (that is, the producer's encoder is newer than the consumer's decoder), then all fields known to the decoder may be parsed but it will be unable to parse added fields.
123125

124-
Also, an old decoder may encounter unexpected enumeration values. The application layer must determine whether an unexpected value is a fatal error. Probably so for a required field since the business meaning is unknown, but it may choose to allow an unknown value of an optional field to pass through. For example, if OrdType value J="Market If Touched" is added to a schema, and the consumer does not recognize it, then the application should return an order rejection with reason "order type not supported", even if it does not know what "J" represents. Note that this is not strictly a versioning problem, however. This exception handling is indistinguishable from the case where "J" was never added to the enum but was simply sent in error.
126+
Also, an old decoder may encounter unexpected enumeration values. The application layer determines whether an unexpected value is a fatal error. Probably so for a required field since the business meaning is unknown, but it may choose to allow an unknown value of an optional field to pass through. For example, if OrdType value J="Market If Touched" is added to a schema, and the consumer does not recognize it, then the application returns an order rejection with reason "order type not supported", even if it does not know what "J" represents. Note that this is not strictly a versioning problem, however. This exception handling is indistinguishable from the case where "J" was never added to the enum but was simply sent in error.
125127

126128
If the *received version is less than the decoder's version* (that is, the producer's encoder is older than the consumer's decoder), then only the fields of the older version may be parsed. This information is available through metadata as "sinceVersion" attribute of a field. If sinceVersion is greater than received schema version, then the field is not available. How a decoder signals an application that a field is unavailable is an implementation detail. One strategy is for an application to provide a default value for unavailable fields.
127129

0 commit comments

Comments
 (0)