Consider a distinct media type ("MIME type")

[cwirving]

While I realize that it is probably too late to change the decision, the fact that JSON Feed does not have a distinct media type from all other JSON content is a problem for code that distinguishes HTTP responses by their Content-Type header value.

The current situation is akin to saying that Atom and RSS are of type 'application/xml' -- that's not terribly helpful (hence the 'application/rss+xml' and 'application/atom+xml' media types used in practice).

Of course, there may be a good reason why not to use a distinct media type for JSON Feed -- if so, I would suggest that it should be included as part of the specification document for rationale.

[donohoe]

This is just my one viewpoint, I've never ever worked with a CMS or system where it made any serious look at the content-type in headers to make decisions.

Don't get me wrong, I agree that to would be nice to have (and probably not too late to add). I'd also be interested in knowing more on where this matters.

[fazalmajid]

The spec should also recommend a filename extension to use, like .atom. I would suggest .jfeed

[manton]

The spec does recommend feed.json. I think that's consistent with RSS using .xml instead of .rss, as an example. Content-Type is a separate issue, though... I tend to think application/json has the best chance for easy compatibility with existing clients and servers.

[fazalmajid]

@manton You're right about the feed.json (how would this cover sites with multiple feeds, e.g. comments vs. article full contents, and so on?).

In the 938 feeds I have subscribed to, about 16% use .rss instead of .xml, though.

[cwirving]

A concrete example where not having a distinct content type leads to problems is: RESTful APIs where the list of available resources is expressed in standard feed format -- e.g., the Atom Publishing Protocol or early versions of the ODATA standard. The typical fix for the ugliness of the standard (Atom) feed format is to serve an alternate JSON-based representation if the client supports/asks for it. In fact, this is exactly what the ODATA folks did, using some weird format of their own but also with the 'application/json' content type. I guess that nobody is ever going to create another JSON-based feed format, then? Oh, wait...

I understand that 'application/json' is the only thing that has universal recognition right now, but this is a pretty dismal world. If everybody does this, there are only JSON documents, not JSON-based formats. By the same logic, there are only Zip archives -- not Word or Excel documents...

It won't break the web to ignore media types (and there are plenty of people who do this today), I would just argue that it is a step backwards. Still, I recognize that introducing something new is hard.

[remmah]

I find myself nodding to fazalmajid and cwirving's concerns. If the intention is for JSONFeed to become a part of the open, standards-based Web, then I think it should be spec'd with the intention of becoming an actual standard. JSONFeed as a standard would imply things like having a content type, maybe a filename extension or even an RFC eventually.

I guess what I'm saying is, now's the best time to keep JSONFeed from becoming another Markdown, a format that — despite becoming a de facto part of the Web — is hampered by never having been completely spec'd or standardized.

[darobin]

A media type would only be useful if the spec were strict that JSON feed processors must ignore media types other than the prescribed one, and then implementations applied this strictly (by ignoring application/json content). The latter part is realistically not going to happen. No one is going to write a serious, successful JSON feed processor that goes "hey, I'm pretty sure this is a JSON feed but I'm gonna reject it because its media type is wrong, lol!"

And the second one implementation accepts application/json, or one major publisher outputs application/json, then everyone's going to have to support it. Then you'll just end up with an additional media type for nothing.

Participation in the community of web standards isn't about doing things according to some theoretical notions of what's right: the things have to actually seriously stand a chance of working, otherwise it's just more cruft in an already pretty cruft stack!

[odrotbohm]

I think the most crucial point is that clients have no way to express that they can actually understand the feed semantics. If a client sends a request with Accept: application/json it basically expresses it can deal with JSON, any kind of JSON. Which basically gives no information about the processing model (i.e. the semantics of the fields as defined in the spec) whatsoever.

By offering a dedicated media type, a client can it express that it understands that particular format, the server can provide data in that format and the client can then forward the processing to something that understands the format (potentially a third party component). Without that dedicated mediatype, you've got a lot of implicit assumptions between the two.

[dret]

+42 to @olivergierke: media types are about conveying that entities understand a specific format. understanding JSON does not mean a whole lot. requesting JSON does not say a whole lot. nobody keeps entities from treating JSON as JSONfeed if they think it is safe/reasonable to do so. but if you don't assign a media type, you do not allow entities to treat JSONfeed as a web concept, which would make it harder to work with on the web and in API-land.

[dret]

if you guys need any help in that department, let me know. writing the spec language for registering a media type is not hard; you need a bit of IETF/IANA magic, but nothing very complicated.

[darobin]

The only usage I can think of for the client and server needing to discuss what they understand (and thereby acquire some coupling that they could live without) is for content negotiation.

Even forgetting everything that's problematic with content negotiation (and that's forgetting a lot) I really don't see why most clients or servers would want to bother with it. You need a compelling use case for implementers to do work, something more than "it would be nice if" or "it has semantics".

I know how long these discussions can be and since I know that as both a publisher and consumer of JSON feeds I will be free to ignore the media type (and unless someone provides a non-contrived use case for it, will do so) I don't want to spend the energy. But can we learn a bit from history, just this once? To this day, as far as I know, RSS clients still have to accept text/html, text/plain, or application/octet-stream because that's what the world looks like to them. And I don't think anyone has successfully content-negotiated RSS and Atom because all it takes is a broken client that's common enough (of which there are plenty) to force publishers back to separate URLs. Is there a magical property of JSON Feed that will somehow make those problems disappear when we add a third option?

[dret]

On 2017-05-19 16:57, Robin Berjon wrote:

I know how long these discussions can be and since I know that as both a publisher and consumer of JSON feeds I will be free to ignore the media type (and unless someone provides a non-contrived use case for it, will do so) I don't want to spend the energy. But can we learn a bit from history, just this once? To this day, as far as I know, RSS clients /still/ have to accept |text/html|, |text/plain|, or |application/octet-stream| because that's what the world looks like to them. And I don't think anyone has successfully content-negotiated RSS and Atom because all it takes is a broken client that's common enough (of which there are plenty) to force publishers back to separate URLs. Is there a magical property of JSON Feed that will somehow make those problems disappear when we add a /third/ option?

i don't think anybody implied defining a media type would be magical. it simply adds a term that can be used if implementations care about the fact that they can clearly label what they consume or expose. the fact that we will never use in a perfect world where everybody does that doesn't change any of that.

all i can say is that in API land, it's useful to have this kind of label so that it becomes clear what your APIs do, on the API level. saying that you use XML or JSON doesn't say a lot. saying that you use Atom or JSONfeed says a lot more. it's not just for machines (the conneg you were referring to) but also something that makes APIs a bit more self-describing, and thus easier to understand and use.

and frankly, declaring a media type is not a lot of work. if you want to do it you come up with a name, add a helpful and linkable section to your spec that explains the format for people looking for info, and add an IANA considerations section.

[fazalmajid]

Declaring a media type can also help browsers take special action like launching a feed reader vs. showing the raw JSON. RSS and ATOM have the <rss> or <feed> elements to identify those XML documents as feeds, JSONFeed does not have a magic number or special key to distinguish it from random JSON.

[darobin]

I understand the amount of work involved in defining a media type, I've done it a few times. It usually isn't that much, but it can balloon up quickly if IANA assigns a reviewer who doesn't know what they're talking about, as happened to me when updating text/html. But in any case that is small compared to the time that will be spent by people who will think they need to update their server configurations, who will implement it in their clients only to realise they need to back out of it, who will have long discussions about whether the feed validator should enforce it, the many people puzzled about why they're getting validation errors for content that works with clients (see the StackOverflow questions about media types and harmless HTML validation errors).

As I said, I don't want to drag this into a long discussion. All I'm saying is:

1. There is ample historical evidence that this doesn't work and no evidence that we are in a different situation here.
2. Supporting something for small, ad hoc situations does not seem wise in a standard.
3. Doing it for theoretical reasons violates the priority of constituencies
4. There is a non-negligible cost beyond the production of the document.

I don't wish this to turn into an endless thread and so I will stop arguing it. I believe the case has been made; I will let the PTB make their call as they wish based on the provided information :)

[sonicdoe]

RSS and ATOM have the <rss> or <feed> elements to identify those XML documents as feeds, JSONFeed does not have a magic number or special key to distinguish it from random JSON.

For what it’s worth, JSON Feed does have a special key to distinguish it from any other JSON: It has a required top-level property version which links to the version of the format the feed uses (e.g. https://jsonfeed.org/version/1).

[odrotbohm]

As ubiquitous as something like version is, I think it's pretty optimistic to rely on that as a discriminator. ALPS has it, too. And I guess a gazillion of other JSON based formats, too.

The point of a media type is that it allows to use well established concepts like content negotiation to take place on the request processing side of things (including weighting different request types) and the client being able to decide about the processing model without having to inspect the payload and apply a lot of guessing and hand waving. The latter also implies that the client has to have in depth knowledge about the format way before actually processing the message. Which is something a good web client avoids.

You're basically introducing a half-baked version of content negotiation that's not implemented by anyone but a client tied to JSON Feed.

[odrotbohm]

Let me give you a concrete example: let's say a client understands both JSONFeed and Collection/JSON (basically some already quite established variant of JSON Feed) and RSS. Let's say the server can produce Collection/JSON, RSS and some other arbitrary JSON, but not JSONFeed.

If the client now sends: Accept: application/json, application/vnd.collection+json, application/rss+xml, the server would conclude to send the other arbitrary JSON, as it's not obvious the client wants JSONFeed, the client would fail to process the response, could resend a request without requesting application/json etc. If the client was able to send Accept: application/feed+json, …, that'd rule out the arbitrary format the client can produce and it would return Collection/JSON immediately and the client would still work.

The core point being: if the client sends application/json as Accept header. The server is free to send you anything JSON, i.e. the client is never guaranteed to get the format it expects. Even if it sent you JSON Feed yesterday, it's not guaranteed to do so tomorrow, because all it opted in to was to produce "some JSON".

[danielcompton]

Content-Type is a separate issue, though... I tend to think application/json has the best chance for easy compatibility with existing clients and servers.

From the client side, I don't know of any clients that this would affect. They all either:

• Don't care about content-type and so won't notice
• Care about content-type and handle it properly

On the server side I can see setting a content type being a bit more of an issue depending on the software the user is using. Blog plugins should be able to handle it properly. Giving short instructions on how to configure nginx, Apache, and Caddy to set the content-type properly on the feed file would probably handle the majority of the remaining cases.

I did a quick look at how I would make a Hugo/Netlify static site return a custom mime-type for a JSON feed and I couldn't see anything obvious.

[manton]

Keeping #32 open to track application/feed+json. Thanks everyone.