Guidance on content negotiation

[handrews]

...and a few other minor wording improvements around HTTP usage.

@vasilakisfil I mostly added this in reaction to your comments about reactive negotiation in your talk. I'm not sure this is a great explanation of what I'm trying to convey, but it is a starting point at least.

[vasilakisfil]

small typo on laguages

[vasilakisfil]

While this PR looks pretty good by itself, I am bit confused in the overall image, like:

1. where these schemas will live
2. how the client will retrieve them / how the client will serve them

I am a bit confused on that part (I was before I joined the discussion) and the spec didn't help me clarify this. Relevant: #427 (comment)

[handrews]

@vasilakisfil

1. where these schemas will live
2. how the client will retrieve them / how the client will serve them

That's intentionally unspecified, although maybe there is a way to make it more clear as to why and provide a bit of guidance.

Some systems will package and distribute schemas and not expect them to be fetched over the network (for instance, I worked on hardware appliance once that typically lived behind firewalls and would not have been able to download schemas). Other systems may expect them to be downloaded at runtime as they are encountered.

This is one reason for having both the "profile" (formerly)/"schema" (currently) link relation and the "describedBy" link relation, as one (profile/schema) is intended to identify the schema, and the other (describedBy) to provide network access to it if such a thing is possible. Although I personally still feel that's confusing and "describedBy" is pretty vague. But I don't have a better alternative right now.

[handrews]

@vasilakisfil I've added a note about linking hyper-schemas, does this seem reasonable to merge now? I also fixed the typo- thanks for catching that.

[vasilakisfil]

looks good to me!