Clarifies text in schema extension example

[codefromthecrypt]

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.

[donmendelson]

Explanations of each version change in lines 125-177 are helpful. However, lines 204-209 are incorrect. The specification tells how to assign version and sinceVersion attributes; I don't see how you conclude that an attribute is not required or about a default interpretation. Nor do I agree about adding sinceVersion to an initial version; it's just clutter that does not change the meaning.

[codefromthecrypt]

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]

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!

[codefromthecrypt]

The main thing that's happening with this example is we are adding sinceVersion on a field contained by message lacking sinceVersion. I'm not sure if this was intentional design of the example, but it was behind my mind wondering about how helpful it is to know when a field was added, but not know when the message was added.

I can still remove this revision if it is considered distracting or should be on a different PR. let me know which way to go.