Updated Proposed change to the model attribute

[dschulten]

The model, template and sending attributes have a potential to contradict each other. Trying to sort out the interdependencies between these three, I want to propose this change. Even if this proposal is not accepted, I think the relationship between these three attributes needs to be explicitly clarified and I hope my (quite radical) proposal helps us to see which contradictions can happen :)

If I am not mistaken, the only UriTemplate which expresses a form-urlencoded POST body is a level 1 template in the form name={value}&name={value}. At least I see no higher level template which expands to a form-urlencoded request body. A model of {givenName, familyName, hatSize} does not expand to a form-urlencoded body but to "Mark, Foster, Medium". {?givenName, familyName, hatSize} expands to something with a leading '?' and {&givenName, familyName, hatSize} to something with a leading '&'.

But if the model would always have to write out a full form-urlencoded body with variables anyway, we do not gain much by the model attribute as a mini-template. What is really only needed are the field names which are expected by the server in a PUT or POST. So I would like to propose this change.

Another point for this is the mime type of a request which is built from the model attribute (here: form-urlencoded by default). If the model does not expand to form-urlencoded, the data item would have to say so in the sending attribute. To deviate from form-urlencoded would only work with something similarly simple like text/plain, more complex requests cannot really be templated by the model attribute but require a template body anyway. So why have a mini-template in model and a full-blown template at the same time?

So I would like to propose to restrict the model to be the field name list for form-urlencoded only. The template constraints can describe valid values for the field names, the template body is for advanced request types.

[mamund]

pretty sure this is what appears in the proposed templates doc, right?

all URIs are RFC6570 templates [1] model is for simple bodies (your L1)[2] templates is for complex write bodies [3]

what do you have above that is different?

[1] https://rawgit.com/mamund/media-types/template-proposal/proposals/uber-templates-mca.html#_change_the_tt_url_tt_property [2] https://rawgit.com/mamund/media-types/template-proposal/proposals/uber-templates-mca.html#_change_the_tt_model_tt_property [3] https://rawgit.com/mamund/media-types/template-proposal/proposals/uber-templates-mca.html#_add_the_tt_template_tt_element

[dschulten]

not sure if you saw the actuall pull request. My proposal is to change model not to be a uritemplate but a simple list of field names which should appear in a form-urlencoded request. If the request is not form-urlencoded, a template should say what exactly is expected. Reason: model is too weak to be used as template for most formats other than form-urlencoded. For form-urlencoded it is not necessary to write out a body template in model, rather the field names seem sufficient. Is the difference more clear now?

[dschulten]

...assuming that the fieldname is also the variable name as in personid={personid}&city={city}. For cases where the server would expect something like p={personid}&c={city}, one could still use a template instead of a model

[mamund]

IMO, it is overkill to REQUIRE the use of <template> for cases that are easily handled by RFC6570 form-style templates such as: p={personid} -> p=123 or c={list) -> c=red,green,blue or c={list*} -> c=red,c=green,c=blue

I also think it it wise to allow path-style segment and parameter expansion via the model for "simple" bodies. This could allow more fine-grained constructions w/o the need to parse a <template>.

What would be good reasons to NOT allow the above?

[dschulten]

Mike, First of all, I learn a lot from your approach to be very careful with restrictions. My impression in this case is, the mimetype of the request expected by the server becomes unclear. If I am not mistaken, only the first example would expand into a valid form-urlencoded body. The others are not of a known mimetype. To be consistent, the server would have to say something like text/plain in sending if models define a non-form-urlencoded model.

Or, to put it differently, if model is a uritemplate, it easily competes with the mimetype defined by sending. There are certainly many ways to solve this. My proposal is a bit radical by redefining model in such a way that it is not possible to define something legal in model which contradicts the sending mimetype.

Best regards, Dietrich

---- Mike Amundsen schrieb ----

IMO, it is overkill to REQUIRE the use of for cases that are easily handled by RFC6570 form-style templates such as: p={personid} -> p=123 or c={list) -> c=red,green,blue or c={list*} -> c=red,c=green,c=blue

I also think it it wise to allow path-style segment and parameter expansion via the model for "simple" bodies. This could allow more fine-grained constructions w/o the need to parse a .

What would be good reasons to NOT allow the above?

— Reply to this email directly or view it on GitHub.

[mamund]

again, we're on the same page, just working out how to get to the end.

TBH, specs can only encourage or discourage behavior. we're on the Internet and expecting to last for a long time. ppl are ppl. they do what they need to do. we all ignore specs at times. what we need to do is write them to be helpful to reasonable ppl and not be overly constraining in case future cases warrant.

now on to the specifics... "If I am not mistaken, only the first example would expand into a valid form-urlencoded body" actually all the examples are valid form-urlencoded bodies and directly from the 6570 spec. the last two might be only L3, tho.

"if model is a uritemplate, it easily competes with the mimetype defined by sending." -- not sure i follow that, but let me say that we can offer guidance on how UBER document authors can create proper docs and how consumers can deal with incoming docs -- including vague or invalid ones. some of this can be in the form of MUST/SHOULD (normative) and some in the form of "it is a good idea to...." (informative). I think we need a mix here.

"redefining model in such a way that it is not possible to define something legal in model which contradicts" -- yeah, that's not really possible (see my first point above). "redefining model in such a way that is is not easy..." could happen. or "redefining model in such as that clients can easily ignore invalid...." is also quite possible.

it boils down to this:

• what are you trying to prevent?
• what are you trying to encourage?

mamund +1.859.757.1449 skype: mca.amundsen http://amundsen.com/blog/ http://twitter.com/mamund https://github.com/mamund http://linkedin.com/in/mamund

On Thu, May 8, 2014 at 12:03 PM, Dietrich Schulten <[email protected]

wrote:

Mike, First of all, I learn a lot from your approach to be very careful with restrictions. My impression in this case is, the mimetype of the request expected by the server becomes unclear. If I am not mistaken, only the first example would expand into a valid form-urlencoded body. The others are not of a known mimetype. To be consistent, the server would have to say something like text/plain in sending if models define a non-form-urlencoded model.

Or, to put it differently, if model is a uritemplate, it easily competes with the mimetype defined by sending. There are certainly many ways to solve this. My proposal is a bit radical by redefining model in such a way that it is not possible to define something legal in model which contradicts the sending mimetype.

Best regards, Dietrich

---- Mike Amundsen schrieb ----

IMO, it is overkill to REQUIRE the use of for cases that are easily handled by RFC6570 form-style templates such as: p={personid} -> p=123 or c={list) -> c=red,green,blue or c={list*} -> c=red,c=green,c=blue

I also think it it wise to allow path-style segment and parameter expansion via the model for "simple" bodies. This could allow more fine-grained constructions w/o the need to parse a .

What would be good reasons to NOT allow the above?

— Reply to this email directly or view it on GitHub.

— Reply to this email directly or view it on GitHubhttps://github.com/mamund/media-types/pull/38#issuecomment-42568609 .