This PR changes ensures that some schema files have the correct content type

[evert]

I did this simply by renaming files like /card to /card.json.
I also used the redirect_from github plugin so that people who are
already linking to the old url will redirect to the new url.

[Relequestual]

Brilliant. Thankyou so much. I haven't looked into jelky... hardly at all to be honest.

[Relequestual]

@awwright How do you go about testing Jekyll locally? (I ask you mainly because I really don't have the time to investigate)

[evert]

Hi @Relequestual ,

It's called Jekyll (as in Jekyll and Hide) and the easiest way to run it is something like:

sudo gem install github-pages
jekyll s

[awwright]

The existing URLs have to send a 200 and not a redirect, is this going to
do that?

On Oct 3, 2016 06:17, "Evert Pot" [email protected] wrote:

Hi @Relequestual https://github.com/Relequestual ,

It's called Jekyll (as in Jekyll and Hide) and the easiest way to run it
is something like:

sudo gem install github-pages
jekyll s

—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHub
#32 (comment),
or mute the thread
https://github.com/notifications/unsubscribe-auth/AAatDZ-YtlYD1r7C2Z70hxMCMQD18Irvks5qwQA4gaJpZM4KKYwI
.

[evert]

Yes, unfortunately. Jekyll is not a webserver, it just generates a bunch of HTML files. The only real redirect it has to it's disposal is a html-based redirect via <meta> headers.

I think ideally the urls wouldn't even change in this case, but just have their headers set correctly. But none of these things are options when you use Jekyll. This, to me, seemed like the "most sane" solution, but it's still not ideal.

[Relequestual]

@evert Never remember the name correctly. Thanks. =]

[Relequestual]

The existing URLs have to send a 200 and not a redirect, is this going to do that?
@awwright
Why is that @awwright ?

[awwright]

@Relequestual Well, theoretically, it shouldn't be a problem... but it's not ideal. In practice redirects have caused me a lot of problems (either I forgot to support them like I should or other people don't).

Honestly I don't know what's best here. If we're going to talk about what the files should be served as, again, it's application/schema+json, but surely application/json is better.

Someone tell GitHub they shouldn't be relying on file extensions? I don't think they intend their website tool for anything but HTML documentation.

[evert]

GitHub pages / Jekyll serves static files. They don't have a lot to go off other than file extensions.

[awwright]

@evert Yeah, it just seems GitHub is being a little weak though, since Apache has supported serving static files with whatever Content-Type you want since forever. Ideally, we would be able to do some sort of Content-Type Negotiation: http://httpd.apache.org/docs/2.4/content-negotiation.html

I have half a mind to see if I could whip something up on SourceForge.net, who offers full Apache.

[evert]

It's kind of a core tennet of Jekyll though. You can serve the product of the Jekyll process also from a local filesystem. If you need something slightly more advanced you're probably better off on a different host, yea.

[Relequestual]

-1 on SourceForge.net. They bundle adware in their downloads... doesn't feel like the sort of place we should go.

[handrews]

@awwright @Relequestual also -1 on sourceforge here. It was a great site once but now it's an adware-infested backwater.

[evert]

What about a free-tier amazon instance?

[awwright]

Well we wouldn't be hosting downloads on SourceForge, but AFAICT that was a one-time issue for some unofficial projects and with what they consider abandoned projects.

AWS doesn't offer a free tier for EC2 (except the 12 month one), though I wouldn't want to have to build a server anyways.

AWS Lambda allows a million requests a month, but that likely also includes website assets. Best case, that's one request every 2.6 seconds.

AWS S3 doesn't have a free tier, but allows you to set the media type (Content-Type) of files, and would likely be <$5/mo.

I can also offer my own server, but that seems too centralized.

[Relequestual]

I'm reluctant to host this elsewhere to try and get round the issue. I also do not want to run another server.

[adamvoss]

@evert Would a Gemfile and using bundler be preferable to making sure people sudo gem install github-pages?

[adamvoss]

I'm not sure if I should comment here or #31, which seems to be what this is trying to fix. Since content is spread over both, I will briefly summarize my understanding here, since I am not entirely sure what is blocking it.

• The web server that powers GitHub Pages uses the file extension to determine the MIME type.
• Currently there are some example schema that are included as text files with no file extension.
• With no file extension, the files are served as "application/octet-stream". This results in poor user experience for humans because web browsers will only offer to download the binary. Once it is downloaded, the OS may identify it as a text file.
• This PR adds a .json extension to the files causing them to be served as "application/json" (or similar) which means they will be open as a text file in the browser (or however else a user has configured their browser for that type), but changes the URL.
• Because GitHub Pages only serves provided, static content it is not possible to provide an HTTP redirect; however, HTML redirects are possible and are implemented in this PR (but will not be recognized by all clients).
• There is a preference the content be served as "application/schema+json" since that is most accurate.

---

While depending on preferences, some variations on this existing PR could be made, overall it seems like it would be an improvement. My thoughts on the concerns I remember reading:

MIME-type is not "application/schema+json"
Who the intended user/consumer of these resources are?

• If it is humans, then the specific MIME-type is less important than the behavior, and "application/octet-stream" provides a better experience.
• If it is computers, then is "application/json" worse than "application/octet-stream"? If not, you also benefit the human users by making the change

Has any consideration been given to a file extension for JSON Schema files? If they had a distinct file extension, that is way you could get the MIME-type correct on GitHub Pages.

HTTP Redirect not possible
Is 404-ing the existing resource a problem? We control all the links on the site, so we would only risk breaking external links.

• If yes, then options include (1) using HTML redirects (which are at least suitable for browsers), or (2) duplicating the resource and serving at both urls.
• If no, remove the redirect code

This seems unlikely to me (though I could easily be wrong), but if the use case is that these resources exist primarily for machines, and it is important to demonstrate the correct MIME-type, then you will probably need another host. If this is the case, it is really more of a web service than a web site resource, and it might make sense to separate if from the website. The website could live on a static host, and you could probably get by efficiently with AWS Lambda since all you need to do is send a predetermined http response.

[Relequestual]

@vossad01 I think you're right in your understanding.
We have thought about hosting just those files elsewhere, but then whou would pay the bills?
We STILL don't know who has control of the domain, so even if we COULD host elsewhere, we have no means to change the IP address for the domain.

I forget why, but someone previously mentioned that HTTP redirect wouldn't be sufficient.

@evert could you weigh in here? Was it just viewing in the browser that you found a problem with?

[adamvoss]

I was trying to give some traction to this issue because it appears that an approved pull request by a first-time contributor has been blocked indefinitely on something largely unrelated to their requested change.

This PR resolves #31 by @evert which discusses both the download behavior resulting from the invalid MIME-type as well as in-browser inspection behavior.

Here is the comment you referenced by @awwright indicating dissatisfaction with the HTTP redirect. However, you have alternative options of 404-ing instead or keeping the existing resource as-is at the current location.

[handrews]

@vossad01 I think fundamentally we're not going to put .json extensions (or any other extension) on the official URIs for meta-schemas. It should be possible for us to offer different representations (a likely example would be an application/schema+cbor representation, or even a YAML one) through content negotiation for the canonical URI, and tacking .json onto that URI completely defeats that purpose.

We are going to have to solve the hosting problem at some point, unless someone can figure out how to tell GitHub the media type.

[handrews]

If @Relequestual, @awwright and @Julian agree with me, it might be better to move the media type discussion over to an issue, and close this PR. @evert we really appreciate the work (and maybe the others will disagree with me and we'll work towards this), but I think we need to take a different approach. Which is complicated by the whole "the owner of the json-schema.org domain won't talk to us anymore" problem.

[evert]

No worries!

[Relequestual]

We don't even know WHO has control of the json-schema.org domain name... just someone has to pay the bills (iirc it can be anyone), and it points to github control. It's a bit of a problem really =/

[adamvoss]

The docs are clear that you will not be able to achieve the functionality @handrews specifies using GitHub Pages. I do not really fault GitHub pages for that.

Given this, I agree this should be closed. #31 should also be closed in favor of a new issue outlining the acceptable outcome, or at least #31 needs to be updated indicating the new direction.

[handrews]

Closing based on apparent general agreement, discussion summarized for further work at issue #31.