Rewrite/expand HTTP/profile/describedby sections

[awwright]

Addresses #9, #26

Rendered draft available at jsonschema-core.txt

[handrews]

Nice! Since you recommend that profile and describedBy have the same URI for simplicity, is it worth calling out any sort of reason why they would not be similar? If so, a one-liner might be something like:

It may be preferable for describedBy link to use a different URI if clients are likely to run on a network that cannot access the identifying profile URI.

I do not feel at all strongly about this- it's fine and possibly less confusing as-is.

[awwright]

Good point. Maybe something like... hmm, lemme think.

Maybe:

Since "profile" is opaque and doesn't necessarily need to point to a network location, a separate link relation is used for linking to a downloadable schema. However, for simplicity, schema authors should make these URIs point to the same resource when possible.

[handrews]

Yes, that works. It doesn't explain why someone might use something other than a network location (or use a non-accessible network location), but that's a potentially large topic and therefore probably outside of the scope of this page.

[awwright]

I used the following language:

The profile URI is opaque and SHOULD NOT automatically be dereferenced. If the implementation does not understand the semantics of the provided profile, the implementation can instead follow the "describedby" links, if any, which may provide information on how to handle the profile.
Since "profile" doesn't necessarily point to a network location, the "describedby" relation is used for linking to a downloadable schema.
However, for simplicity, schema authors should make these URIs point to the same resource when possible.