Skip to content

Explain schema media type param and Accept #695

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Jan 25, 2019
Merged

Explain schema media type param and Accept #695

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bbd3be9
Explain schema media type param and Accept
handrews Dec 17, 2018
114b8c6
Better wording for Accept usage.
handrews Dec 31, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 31 additions & 1 deletion jsonschema-core.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2912,7 +2912,8 @@ Content-Type: application/json;
</figure>

<t>
Multiple schemas are whitespace separated:
Multiple schemas are whitespace separated, and indicate that the
instance conforms to all of the listed schemas:
</t>

<figure>
Expand All @@ -2924,6 +2925,35 @@ Content-Type: application/json;
</artwork>
</figure>

<t>
Media type parameters are also used in HTTP's Accept request header:
</t>

<figure>
<artwork>
<![CDATA[
Accept: application/json;
schema="http://example.com/qiang http://example.com/li",
application/json;
schema="http://example.com/kumar"
]]>
</artwork>
</figure>

<t>
As with Content-Type, multiple schema parameters in the same string
requests an instance that conforms to all of the listed schemas.
</t>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good, this appears to be consistent with how e.g. profile is used.


<t>
Unlike Content-Type, Accept can contain multiple values to
indicate that the client can accept several media types.
In the above example, note that the two media types differ
only by their schema parameter values. This requests an
application/json representation that conforms to at least one
of the identified schemas.
</t>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I misread this the first time through, I thought this was saying a media type could have a property specified multiple times like application/json;schema="http://example.com/a";schema="http://example.com/b" but I don't know what that would even mean. I suspect it's invalid.

This is all technically correct, so I don't have an objection as such, but I'd be clearer to me without this paragraph. I think the example above is sufficient to get the point across.

I can't find if there's a good way to distinguish the "type slash subtype" media type, versus the media type of a document (including its media type parameters).

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@awwright thanks, I'll take a look at the wording. I think I was trying to cover a question from the issue that was filed (this came from an outside request filed a number of months ago), but maybe it can be trimmed or reworded.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@awwright thanks for catching this, it really was confusing when I went back and read it. I think I have clarified it by just highlighting the example. Please let me know if this works for you.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@handrews thanks for making these changes - one minor suggested tweak. Instead of "conforms to at least one of the identified schemas", it might be clearer to say "conforms to both the first and second schema or conforms to the third".


<t>
<cref>
This paragraph assumes that we can register a "schema" link relation.
Expand Down