Description
I'm filing this as a result of discussion with @pipobscure in issue #204.
"default" intentionally avoids specifying how the default value is used. It may simply be documentation, for instance, with no run-time effect of any sort. This is important because we do not want to restrict how an application makes use of validation- it may or may not automatically make use of the default.
However, a well-known use case in hyper-schema is to omit values from requests and responses either to make it easier to construct the message or to reduce the weight of the message on the wire.
"messageDefault" behavior
"messageDefault" would be a value that MUST be valid against the containing schema. When a client or server receives a message that omits a field or element with a "messageDefault" set, it MUST treat the instance the same as if the "messageDefault" were present. Clients and servers MAY automatically write in the "messageDefault" value before validating or otherwise processing the instance.
Use with "targetSchema" and response profiles
"targetSchema" is advisory only. The schema given by the response's "profile" media type parameter or link, or the "describedBy" link, is the only authoritative schema. A "messageDefault" that appears in a "targetSchema" but not in the authoritative schema MUST be ignored.
This follows directly from
Clients MUST NOT use the value of this property to aid in the interpretation of the data received in response to following the link
Use with input: "schema" and (if it is accepted) "hrefSchema"
Both of these keywords define schemas that may be used to accept user input. "messageSchema" MUST NOT be used to pre-populate user input. It may only be used after the user takes action. If pre-population schema field is to be defined, it would be the responsibility of the UI Schema vocabulary (#67).
In the case of "schema", "messageDefault" is used on the server side when the server receives the message.
In the case of "hrefSchema" (#179), its role in hypermedia messaging is to determine the URI by filling out the URI Template. If present, "messageDefault" MUST be used if (and only if) no user input was supplied and no instance data is available.
An application MAY use "messageDefault" to document the effect of an empty input field, including in online help such as a tooltip.
"default" and "messageDefault"
A schema may set both "default" and "messageDefault". An application may take advantage of "default"'s unrestricted usage to accomplish some other goal, such as displaying help text or pre-populating an input field.
"messageDefault" MUST NOT be treated as a regular "default" when the schema is used in a context other than a request/response message. (this point is debatable, but I think it makes sense- I'm also thinking ahead to the possibility of a UI Schema defining an "inputDefault" or something similar. If we have several usage-specific defaults, it would be ambiguous which to use as the generic "default" so it is better to keep it separate).