Subject: Request for well-known URI: contribute.json

From: Paul McLanahan <[email-masked]>
Date: Thu, 6 Oct 2016 23:01:15 -0400

Hello all,

Some colleagues and I at Mozilla have developed a JSON schema for
indicating that an open-source website or project welcomes contribution in
some way. We have been using it for a while now but would like to formally
register a .well-known URI for it. Currently the documentation recommends a
URI of "/contribute.json", but we'd obviously like to move that to
"/.well-known/contribute.json" and support both.

Thank you for your consideration.

--
URI suffix: contribute.json

Change controller:
        Mozilla
        https://www.contributejson.org/
        https://github.com/mozilla/contribute.json/

Specification document(s):
        https://www.contributejson.org/schema
--

Paul McLanahan
Sr. Web Developer
Mozilla

---

From: "Roy T. Fielding" <[email-masked]>
Date: Mon, 10 Oct 2016 10:42:32 -0700

On Oct 6, 2016, at 8:01 PM, Paul McLanahan <[email-masked]> wrote:
> 
> Hello all,
> 
> Some colleagues and I at Mozilla have developed a JSON schema for indicating that an open-source website or project welcomes contribution in some way. We have been using it for a while now but would like to formally register a .well-known URI for it. Currently the documentation recommends a URI of "/contribute.json", but we'd obviously like to move that to "/.well-known/contribute.json" and support both.
> 

FWIW, reserving a universal location for this purpose doesn't make any sense.
It is common for a single hostname to provide many different open source projects.
Even an Apache project will often have multiple product-specific pointers to
contributions within the same project-specific hostname.

The well-known URIs are intended for protocols that do not want to access part
of a site's normal resources.  In particular, when the only thing a client knows about
a site is a URI that it does not want to access before knowing something more about
the site or its communication options.

In this case, the client already knows the home page of an open source project.
There is no reason for that client not to GET the homepage. The data in this resource
is commonly found in (or near) the homepage. So, the only thing you are providing
is a structured record in a common format.  You can do that within the homepage
using a standard JSON object, a standard profile of HTML elements, or even an
embedded link with a standard relationship.

When that data is in the homepage, there is no need for a separate request, and
the data itself is less likely to become stale over time.  It also allows a
single host to have more than one distinct open source project.

Cheers,

Roy T. Fielding                     <http://roy.gbiv.com/>

---

From: Paul McLanahan <[email-masked]>
Date: Mon, 10 Oct 2016 14:12:21 -0400

-----Original Message-----
From: Roy T. Fielding <[email-masked]>
Reply: Roy T. Fielding <[email-masked]>
Date: October 10, 2016 at 1:42:34 PM
To: Paul McLanahan <[email-masked]>
Cc: [email-masked] <[email-masked]>
Subject:  Re: Request for well-known URI: contribute.json

> contributions within the same project-specific hostname.

We're working on adding sub-project contribute.json discovery to the schema[0].

> the site or its communication options.

The clients of the contribute.json files will be mostly that. It will be scripts that aggregate contribution information or other web crawlers. It should be used in much the same way search bots discover and use robots.txt.

> embedded link with a standard relationship.

It's difficult, impractical, or wasteful to parse HTML in some situations. Having an easily parsable JSON document in a known location really helps to gather this information, especially from JS in a purely client-side application.

> single host to have more than one distinct open source project.

As I said above, the expectation is that most clients won't have already requested the home page. Some obviously will (e.g. a browser extension), but moving the data into the HTML makes the other clients much more difficult to write and maintain.

[0] https://github.com/mozilla/contribute.json/issues/71#issuecomment-251841553

Thanks very much for your feedback,

Paul McLanahan
Mozilla