Remove "method", URI input with "hrefVars"

[handrews]

This implements a first step from the rather complex issue #108.

In the most recent draft, "method" simply controlled whether link
input was placed in the URI (for a value of "get") or in the request
body (for a valued of "post"). While correlating with HTML, this
was both confusing due to "get" and "post" not necessarily indicating
the HTTP methods of the same name, and limiting in that users/clients
could not submit data through both the URI and the request body
at the same time.

This introduces "hrefVars" and "baseVars", which provide schemas for
user input matching the "href" and "base" URI Template variables,
respectively. It removes "method" and makes "schema" and "encType"
unambiguously apply to the request body in all cases.

Clients should choose when to use the request body submission based
on the rules of the protocol given by the URI scheme and the semantics
indicated by the link relation.

Additionally, the complex and apparently rarely if ever used
preprocessing rules have been removed, and both the resulting and
pre-existing limitations have been documented. They will be the
subject of work for future drafts.

The meta-schemas have been updated accordingly, and the LDO schema has
been brought over from the web site repo and updated. Improper
use of "$ref" has been fixed with "allOf".

[handrews]

This is another PR that I have put up to facilitate comments as we now seem to be driving towards a rapid v6 release. It implements @awwright 's idea of a first step towards solving issues documented in #108, while sidestepping more complex issues such as relative JSON pointers. It is an alternative to the more controversial first step in #129, which would be deferred to v7 (if it is accepted at all).

Note that this assumes that PR #150 (uritemplate and jsonpointer formats) will be accepted and merged.

[handrews]

This also addresses #96, although only in the sense of removing the confusing behavior rather than fully replacing the v4 "method" usage.

[awwright]

The one blocker here is that "base" doesn't accept end-user input for variables - it's always deterministic. So "baseVars" will never support user input, and we can probably avoid introducing the keyword entirely for this iteration.

Also I think it's pretty clear the intention of URI Templates was to allow "." to identify a property in a map (people who want to identify a literal . can use the hex-escaped %2E). The behavior is fine as defined, but I would like to be prepared to consider building it out later.

[handrews]

@awwright thanks for looking over this so quickly!

I will take "baseVars" out, that seems totally reasonable.

I also agree with considering dot-separated names later, I just wanted to make absolutely sure that people didn't rush into that quite yet. Let me know if you want me to tweak the wording there, but this is an area I'd want to keep discussing while we review and publish v6. Hopefully we can work that out and quickly follow v6 up with a v7 that has a full URI Templating solution.

[awwright]

One more issue, I'm trying to figure out what impact this has:

Template variables from "href" which do not appear as properties can
be considered to be present with an empty schema.

Schema authors can prevent user input for a template variable by
setting its schema to false in "hrefVars". Implementations MUST NOT
attempt to validate values resolved from instance data with
"hrefVars".

I'd think if you don't want to prompt a user about a value, you just don't include it as a property in "hrefVars". Any variable not explicitly listed (as a user field) in "hrefVars" is going to be data from the instance in some fashion.

[handrews]

I'd think if you don't want to prompt a user about a value, you just don't include it as a property in "hrefVars". Any variable not explicitly listed (as a user field) in "hrefVars" is going to be data from the instance in some fashion.

That's not consistent with the overall validation approach. In general, if something is missing it is unconstrained. To constrain it, you add keywords and set them to a value that specifies the constraint.

[awwright]

@handrews Link templates aren't doing validation, though. We're defining user fields, not constraining ones that already exist.

[handrews]

@awwright we are defining the validation rules for the user fields. That is why they are associated with schemas. And in general, the same principles should apply throughout the specifications. I don't see any reason to flip it here just because this proposal, which involves validation, is not in the validation spec.

[handrews]

@awwright @Relequestual I've come up with #179 which is both more powerful and more consistent/obvious than this approach. It just uses a regular schema applied to the template variables as properties of a JSON object, and does not require special rules. Just regular use of a validation schema.

[handrews]

I'm going to close this one in favor of #179 which is a much better solution. This PR is referenced from that one so if anyone wants to consider this option they can, and we'll re-open it as necessary. But I would like the attention to be on #179.