search

FIXTradingCommunity / fix-simple-binary-encoding

A FIX standard for binary message encoding
Other
261 stars 69 forks source link

Clarifies text in schema extension example #135

Closed codefromthecrypt closed 1 year ago

codefromthecrypt commented 3 years ago

While correct, the schema extension example could be misinterpreted due to vocabulary used. For example, a new reader who missed the implicit zero based versioning, could misunderstand how version 1 appeared in updates.

This change walks through the thinking behind the example, so that readers have less cognitive break even if they misread the spec.

codefromthecrypt commented 3 years ago

Thanks for the feedback @donmendelson. I do think that there's something unclear hence me trying to straw man how to address it in the example.

For example, about version, the way the spec is written hints there is an implicit version zero.

The root element contains a version number attribute. By default, version is zero, the initial version of a message schema.

On sinceVersion, the MAY part below allows for some ambiguity... basically unless you have a history of that schema, you won't know which version something was added unless it is present. Mixed use of sinceVersion is allowed, in other words

the extension may be documented by adding a sinceVersion attribute to the element

For example, when I am working in a typed language like Java, if a @since tag is missing, I have to look through source history to figure out when it was added. Of course, it can also be wrong!

I don't completely agree that sporadic use of sinceVersion is cluttered, but I do see where you are coming from. Over time, I would expect it to feel opposite in some schema, ex that lack of sinceVersion is the anomoly that might break some people's mind leading to research to figure out when it was added. Lack of uniform use of sinceVersion creates this ambiguity. I feel what you are saying is that it is ok for that ambiguity to exist as the cure is worse than the disease, that intentionally suggesting if you are going to use sinceVersion.. always do that.. could make some people feel it is cluttered in initial phases of the schema. Fair enough.

Anyway, if I have misunderstood the meaning further let me know. Happy to remove the section you mentioned, but I would also like to know what I don't know, as the point of this change was to help others not scratch their heads as I did. Sometimes as a spec writer we can know too much in other words.

Cheers!

codefromthecrypt commented 3 years ago

PS I intentionally didn't want to change semantics, but perhaps a less extreme example could be to say something like.. if you use sinceVersion, you should use it consistently to prevent ambiguity about when types or fields became available.

^^ is probably the heart of my tension, which might be easier to unravel than my preceding ramble.

Cheers!