>> Personally, I find most advisory notes in specifications to be a bit of
>> a cargo-cult thing.
> [...]
>
> Good point. I suppose the reason I'd like such notes not in a format
> spec is that the purpose of the spec is to define a line between valid
> and invalid values

You hit the nail on the head.

Whenever I read specs now, I like to put on my Jaded Programmer hat and
think of Jon Postel (Postel's law: be conservative in what you send and
liberal in what you accept).

> there might be a place to mention some likely
> implementation limits you might encounter, but it should be in an
> appendix IMHO so to make it clear it's not part of the definition of a
> valid value.

This is the internet age: we can put up a separate web page with an
up-to-date list of known implementations and their limits. Not all
useful information is useful to keep in a spec. As you so aptly
summarized, the spec's job is to say what is valid and what is invalid.
The rest can go into blog posts, emails and surveys.

Saying "implementations should state their limits in documentation" was
useful when there was no internet, no open source, and physical products
like A/V equipment shipped in boxes with wires as connectors. Now that
we download software from the internet, we can just look at the source
code or try sending it some bit values to see where it blows up. That's
more reliable than consulting documentation (which most programmers
don't like to write, and often forget to update).

Here too the rule for the spec author is "write about what is true, not
what you'd like to be true". From the Jargon File: "WIBNI (Wouldn't It
Be Nice If): What most requirements documents and specifications consist
entirely of." Claimed to be from Bell Labs.

This "write about what is true" rule is also why most range limits in
specs are baloney (technical term :) unless they are a hard limit of the
encoding, like a value stored as uint32 can't be bigger than 32 bits. It
makes no sense to say that there are forbidden characters in a string,
for example, unless you know everybody has a validator in the pipeline
to weed out those characters. If your strings are stored as bytes, weird
byte sequences are just going to end up in them. Likewise, giving a soft
limit on list length is useless if the element count is encoded as a
varint, etc.

With Jaded Programmer hat firmly on, the only true limits are hard limits.

> Also perfectly valid is for a spec to also standardise the declaration
> of implementation limits, as part of also specifying what counts as an
> implementation. It might say "Valid implementations are welcome to limit
> string size, integer range, whether or not they support floats, string
> character set, and total message size", thereby clearly placing an
> implementation that doesn't support characters as invalid, and giving
> users of the format some useful guidance that using long strings, large
> integers, floats, unusual character sets, and large messages might cause
> problems so should be avoided unless necessary. It also means that
> implementations have a defined set of axes to be compared along, which
> can be helpful when choosing them.

The thing is that a complex-enough format is going to be subsetted no
matter what is said in the spec. It could be argued that almost all
implementations of almost all specs are subset implementations. Full
conformance is for military and space applications. The rest of us
pretend to stipulate rules, but are mainly just giving advice. We are
only one step up the food chain from a guy waving a sign in the street
as people walk by. If we want to be listened to, we'd best make a sign
with a clear and simple message that people find easy to follow.

I would just leave out all mention of valid and invalid implementations
and soft limits altogether. Start from bits and bytes. A byte stores
values 0..255. That means 255 is a valid value. If someone doesn't think
255 is valid, that's their problem; it's not the problem of the careless
people who are going to be sending 255's anyway. Similar concerns for
all other data. Go through the spec sentence by sentence, and think
about all the hard limits on what those bytes can encode. That is the
real format, and that goes for all formats ever made.

Once again the above sounds ranty but it's just passion about the topic :)