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

Paul McLanahan <> Mon, 10 October 2016 18:12 UTC

Return-Path: <>
Received: from localhost (localhost []) by (Postfix) with ESMTP id B8F79129773 for <>; Mon, 10 Oct 2016 11:12:56 -0700 (PDT)
X-Virus-Scanned: amavisd-new at
X-Spam-Flag: NO
X-Spam-Score: -2.701
X-Spam-Status: No, score=-2.701 tagged_above=-999 required=5 tests=[BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, RCVD_IN_DNSWL_LOW=-0.7, SPF_PASS=-0.001] autolearn=ham autolearn_force=no
Authentication-Results: (amavisd-new); dkim=pass (1024-bit key)
Received: from ([]) by localhost ( []) (amavisd-new, port 10024) with ESMTP id kT5PqmJnTNal for <>; Mon, 10 Oct 2016 11:12:54 -0700 (PDT)
Received: from ( [IPv6:2607:f8b0:4001:c0b::232]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by (Postfix) with ESMTPS id 5D721129765 for <>; Mon, 10 Oct 2016 11:12:54 -0700 (PDT)
Received: by with SMTP id 189so14056695ity.1 for <>; Mon, 10 Oct 2016 11:12:54 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;; s=google; h=date:from:to:cc:message-id:in-reply-to:references:subject :mime-version:content-transfer-encoding:content-disposition; bh=zb2hr0ukNeb04QXbLIaJSsoY/U1+UfMwnxjX0Zyn7DU=; b=fK7Jo9ZxDCvJEv077wyjtUPftAnrDUgZ/Dq2hKNlyXFOMMhLQbnVQ0s1YV5HuJxRKU EWwFiIndcYY/bweMsXcyuby0P5aW3UFK1394gNwbnGytNIEq83mUMEcoxNWEPNxYP6wl o7B4BRPjvT/rfM8O3wJ31PtcWa4K1NgPPi6TA=
X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed;; s=20130820; h=x-gm-message-state:date:from:to:cc:message-id:in-reply-to :references:subject:mime-version:content-transfer-encoding :content-disposition; bh=zb2hr0ukNeb04QXbLIaJSsoY/U1+UfMwnxjX0Zyn7DU=; b=j2DeirJJ1JtgdDMaxyopBUhzjf0GRNpFVUsPuKlMzlderib/vq690ZgBr1Nz7vaUOq ylpDNC4aT50DKOqP5E5E5+0niJUAYjZPUVcaHKtHvBgQzhlq9rf8o9ISRHspxBLu5eF9 HdxYzQSrYGQkbvzD8R00A6692I9dxNZ+vGo4FjN1DoGPpmeMZTLBejg+WS8u0dCgaqDw Ej29vxcuYjeCg4P8Mq6QWaG+NGYaqphLXE+KbRkrHlroocTDrf3Gi29b1Pbbqy5Xrmla RDrCRICxtPaVSgqk2RQEZICasAalB4H7qfOHJkE9QrRcAGg9HWF/LaTBuuCS8HqCMudj b+Yw==
X-Gm-Message-State: AA6/9RlUq0EqjRy3U7LMquOHR7LHYhbOk0m2cFvww6mqDpKBAVYVI1NhF/70tzOzeI4YkE9U
X-Received: by with SMTP id j78mr8260810ita.58.1476123173505; Mon, 10 Oct 2016 11:12:53 -0700 (PDT)
Received: from sterling.local.mail ( []) by with ESMTPSA id m128sm318375ioa.41.2016. (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Mon, 10 Oct 2016 11:12:52 -0700 (PDT)
Date: Mon, 10 Oct 2016 14:12:21 -0400
From: Paul McLanahan <>
To: "Roy T. Fielding" <>
Message-ID: <>
In-Reply-To: <>
References: <> <>
Subject: Re: Request for well-known URI: contribute.json
X-Mailer: Airmail (390)
MIME-Version: 1.0
Content-Type: text/plain; charset="utf-8"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: inline
Archived-At: <>
X-Mailman-Version: 2.1.17
Precedence: list
List-Id: Well-Known URI review list <>
List-Unsubscribe: <>, <>
List-Archive: <>
List-Post: <>
List-Help: <>
List-Subscribe: <>, <>
X-List-Received-Date: Mon, 10 Oct 2016 18:12:57 -0000

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

> 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.

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

> 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.

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.

> 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.

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.

> 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.

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.


Thanks very much for your feedback,

Paul McLanahan