You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: v1-0-RC4/doc/05SchemaExtensionMechanism.md
+5-3Lines changed: 5 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -35,7 +35,7 @@ Compatibility is only ensured under these conditions:
35
35
wire format does not change.
36
36
37
37
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.
39
39
40
40
Message schema features for extension
41
41
-------------------------------------
@@ -115,13 +115,15 @@ encoding.
115
115
116
116
Comaptibility strategy
117
117
-----------------------
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.
119
121
120
122
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.
121
123
122
124
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.
123
125
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.
125
127
126
128
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.
0 commit comments