Content types: optional tree prefixes and parameters, split req/res content negotiation

[farshidtz]

• Allow content type with without td/ld tree prefixes (related to Feedback on latest Editor's Draft #299). This effectively allows using application/json instead of application/td+json and application/ld+json.
• Clarify content negotiation: split request/response assertions. Original assertion was hard to follow and missed Content-Encoding.
• Add assertion to explicitly mention the default JSON content type for self-description (related to Feedback on latest Editor's Draft #299). We already had application/td+json/application/ld+json as mandatory Content Type, so this isn't a technically a new requirement, but rather to clarify the spec.
• Allow parameters such as charset in content types (closes Return charset parameter in content-type #315). This doesn't explicitly mention parameters or the charset, but instead makes the assertions less strict to allow such additions. As mentioned in Return charset parameter in content-type #315 (comment), all application/json content types are already UTF-8 by specification. This PR makes it possible to explicitly specify that the charset is UTF-8 or something else.

---

Preview | Diff

[mmccool]

I see you updated the rules for this in TD Server for HTTP. If we also accept PR #334, which supports use of CoAP for TD Servers, we need equivalent updates for CoAP's Content-Format.

[mmccool]

I think we need a little more discussion, especially around the wording of the assertion with "contains" for application/json. I think it is technically correct, but a little confusing.

[mmccool]

I agree that breaking these into multiple assertions is a good idea.

[mmccool]

The use of "contain" is a bit strange here. I can understand it if I interpret the content-types and defining sets, and td+json is a subset of json, but perhaps there is a better word than "contain" to make this clearer.

[mmccool]

Should we instead be more explicit and say "MAY" and "SHOULD" for the various options?

[farshidtz]

Content-Type can be for e.g. application/td+json; charset=utf-8 and include any other parameters. The assertion mandates containing the type and leaves it open for adding parameters.

Note that "contain" was already there and this PR isn't adding that.

[relu91]

Looks good, regarding #315! thanks. About the content-type set to application/json I would probably need some clarification today. I thought Ben's feedback was about allowing clients to request application/json in the Accept header not giving the possibility to arbitrary return application/json or application/td+json.

IMHO this assertion should already cover the WebThings gateway requirements:

An HTTP-based TD Server providing a TD MAY provide alternative representations through server-driven content negotiation, that is by honoring the request's Accept and Accept-Encoding headers and responding with the supported TD serialization and equivalent Content-Type and Content-Encoding headers

Isn't?

[farshidtz]

About the content-type set to application/json I would probably need some clarification today. I thought Ben's feedback was about allowing clients to request application/json in the Accept header not giving the possibility to arbitrary return application/json or application/td+json.

IMHO this assertion should already cover the WebThings gateway requirements:

An HTTP-based TD Server providing a TD MAY provide alternative representations through server-driven content negotiation, that is by honoring the request's Accept and Accept-Encoding headers and responding with the supported TD serialization and equivalent Content-Type and Content-Encoding headers

Isn't?

This PR is addressing another feedback from Ben:

I note that the response for this operation uses the application/ld+json content-type rather than application/td+json because the resource it returns is not a valid Thing Description, it's a list of Thing Descriptions. Could application/json be acceptable here too, as is used in the Search API?

[mmccool]

propose merging, follow up with fixes in #341