3.0.4: port the undisputed parts of #2140

[ralfhandl]

This is an attempt to revive/port

• Clarify server variables (Addresses #1675) #2140

It contains all undisputed changes:

• rework confusing description in example
• remove confusing reference to the Schema Object's treatment of default values

Part of

• Questions about Server Variable binding and defaults #1675

[mikekistler]

While the sentence that was delete here is a bit confusing, I think there is something lost if we don't call out the difference in the meaning of "default" here. Would something like this be okay?

Note this differs from a default value in the Schema Object's, which specify the value applied by the server when none is provided by the client.

[ralfhandl]

The preceding sentence says

SHALL be sent

That is a MUST, not sending a value is not an allowed option.

The Schema Object's default talks about what

would be assumed [...] if one is not provided

Referencing something that does not apply is confusing.

[mikekistler]

I think we are referencing something to explain that, while it looks very similar -- same property name default in a very similar context -- it is in fact different and does not apply. I think that will be helpful to users of the spec, no?

[ralfhandl]

@darrelmiller suggested to remove this sentence in #2140 (comment).

I agree because I find it confusing here.

[handrews]

I think it would be better to change the sentence to something like:

Note that this behavior is different from the Schema Object's default keyword, which documents the default behavior rather than inserting the value into the data.

[miqui]

Note that this behavior is different from the Schema Object's default keyword, which documents the default behavior rather than inserting the value into the data.

That sounds good to me. However I don't really have a problem with Ralf's PR as is.

[ralfhandl]

Note that keeping this sentence here is the option that was least favored by both @darrelmiller and the PR author @tedepstein, see his comment.

[handrews]

@ralfhandl I'm certainly not proposing keeping the current sentence, which I also find confusing. But people find default endlessly confusing. They are particularly likely to think that JSON Schema's default means that the value of default should be written into the instance, which is not how it works at all.

So the fact that we have a different default that does work that way is a very, very likely point of confusion. The text that was there before did not really help. However, I think the text that I proposed explains the real difference succinctly, and will keep people who read this default from thinking that JSON Schema's default works similarly. Which was always one of the endless recurring questions/complaints in the JSON Schema project, so it's a very practical and real concern, with years of experience answering this exact question to back it up.

I think my experience here is a bit deeper than was available during the previous conversation.

[ralfhandl]

@handrews Good point, have added your proposed sentence to the end of the table cell's text, and used "receiver's behavior" instead of "default behavior" to stress the difference.

[miqui]

Note that this behavior is different from the Schema Object's default keyword, which documents the default behavior rather than inserting the value into the data.

That sounds good to me. However I don't really have a problem with Ralf's PR as is.

[ralfhandl]

@mikekistler does the added explanation meet your expectations?