Support for non-HTML human.json discovery #12

nfnitloop commented 2026年03月11日 22:30:47 +01:00

If the goal is for human.json to "[form] a directed graph of human-verified sites, crawlable by anyone" it might be nice to decouple it from HTML.

Right now, if you vouch for a URL, a crawler has to:

• fetch that URL
• Look for a <link rel="human-json" ...> in the header
• Fetch that
• repeat

But, not all of the web is HTML. (ex: curl https://www.nfnitloop.com/blog/2025/06/project-gemini/) And not everyone will want to add a <link> to (all of?) their HTML files.

There are changes you could make to reduce the reliance on HTML:

1. Define a well-known URI: https://en.wikipedia.org/wiki/Well-known_URI (ex: https://www.neatnik.net/.well-known/human.json)

This works when a person can claim the entirety of a domain as both theirs and human-made. But fails for a site that has multiple users. (Unless the JSON is updated to allow linking to multiple users on the current domain?)

2. Allow a "vouch" to include a link directly to the human.json, so it can be crawled without having to fetch an intermediate HTML page.

If the goal is for human.json to "[form] a directed graph of human-verified sites, crawlable by anyone" it might be nice to decouple it from HTML. Right now, if you vouch for a URL, a crawler has to: * fetch that URL * Look for a `<link rel="human-json" ...>` in the header * Fetch that * repeat But, not all of the web is HTML. (ex: `curl https://www.nfnitloop.com/blog/2025/06/project-gemini/`) And not everyone will want to add a `<link>` to (all of?) their HTML files. There are changes you could make to reduce the reliance on HTML: 1. Define a well-known URI: https://en.wikipedia.org/wiki/Well-known_URI (ex: https://www.neatnik.net/.well-known/human.json) This works when a person can claim the entirety of a domain as both theirs and human-made. But fails for a site that has multiple users. (Unless the JSON is updated to allow linking to multiple users on the current domain?) 2. Allow a "vouch" to include a link directly to the human.json, so it can be crawled without having to fetch an intermediate HTML page.

robida commented 2026年03月12日 02:42:24 +01:00

Thanks for the comment, @nfnitloop!

The first implementation I did for human.json actually used .well-known instead of <link rel="human-json">, but I decided against it after reading this post. The <link> approach allows people to put the file anywhere they want, which is useful for web hosts that restrict the location of files. It also makes the protocol work with tilde websites, like you said. To use .well-known we'd have to change the JSON to be either more complex or generated by a dynamic endpoint so that something like WebFinger would work:

https://example.com/.well-known/human.json?resource=acct:alice

One thing that I missed about discovery is that we could allow the location to be defined in a Link header instead, as is common practice in similar protocol — that seems like an obvious omission now. It would solve the problem of having to add <link> elements to very HTML file, but would not be possible for people who don't control the headers on their websites. Still, I think it's a nice alternative. I also completely missed Gemini! And I'm a big fan — I have a capsule at gemini://robida.net/, and I used to have gemini://taoetc.org/ many years ago. Another obvious omission of my part.

It seems to be that if allow people to vouch directly to a human.json file we could solve both these problems (other protocols and expensive discovery):

{
 "version": "0.x.y",
 "url": "https://robida.net",
 "vouches": [
 {
 "url": "https://alice.example.com/human.json",
 "vouched_at": "2026年03月09日"
 },
 {
 "url": "gemini://bob.example.com/human.json",
 "vouched_at": "2026年03月08日"
 },
 {
 "url": "https://example.com/~charlie",
 "vouched_at": "2026年03月08日"
 }
 ]
}

Where Charlie doesn't have a human.json, so we link to their homepage instead. But this adds some complications, since the url can now either be a direct link to a human.json file or a URL directory. And when things move around — Charlie adds a human.json file, Alice moves her files to /static/, then the original file is broken.

I need to think a bit more about this. 😄

Thanks for the comment, @nfnitloop! The first implementation I did for `human.json` actually used `.well-known` instead of `<link rel="human-json">`, but I decided against it after reading [this post](https://beesbuzz.biz/code/6987-Why-I-dislike-.well-known). The `<link>` approach allows people to put the file anywhere they want, which is useful for web hosts that restrict the location of files. It also makes the protocol work with tilde websites, like you said. To use `.well-known` we'd have to change the JSON to be either more complex or generated by a dynamic endpoint so that something like WebFinger would work: https://example.com/.well-known/human.json?resource=acct:alice One thing that I missed about discovery is that we could allow the location to be defined in a `Link` header instead, as is common practice in similar protocol — that seems like an obvious omission now. It would solve the problem of having to add `<link>` elements to very HTML file, but would not be possible for people who don't control the headers on their websites. Still, I think it's a nice alternative. I also completely missed Gemini! And I'm a big fan — I have a capsule at gemini://robida.net/, and I used to have gemini://taoetc.org/ many years ago. Another obvious omission of my part. It seems to be that if allow people to vouch directly to a `human.json` file we could solve both these problems (other protocols and expensive discovery): ```json { "version": "0.x.y", "url": "https://robida.net", "vouches": [ { "url": "https://alice.example.com/human.json", "vouched_at": "2026年03月09日" }, { "url": "gemini://bob.example.com/human.json", "vouched_at": "2026年03月08日" }, { "url": "https://example.com/~charlie", "vouched_at": "2026年03月08日" } ] } ``` Where Charlie doesn't have a `human.json`, so we link to their homepage instead. But this adds some complications, since the `url` can now either be a direct link to a `human.json` file or a URL directory. And when things move around — Charlie adds a `human.json` file, Alice moves her files to `/static/`, then the original file is broken. I need to think a bit more about this. 😄

nfnitloop commented 2026年03月12日 03:03:38 +01:00

The <link> approach allows people to put the file anywhere they want, which is useful for web hosts that restrict the location of files.

It also allows web browser( extension)s to detect the presence of a human.json without having to make another request, which is nice. So, I didn't open this ticket to propose doing away with <link>, it's useful! ... it would just be nice if it weren't the only way to discover a human.json. :)

But this adds some complications, since the url can now either be a direct link to a human.json file or a URL directory.

Oh, definitely. I wouldn't recommend overloading/redefining the "url" field. What about adding an extra, optional "json" or "human.json" field?

So you could have:

{
 "version": "0.x.y",
 "url": "https://robida.net",
 "vouches": [
 {
 "url": "https://alice.example.com/",
 "json": "https://alice.example.com/human.json",
 "vouched_at": "2026年03月09日"
 },
 {
 "url": "gemini://bob.example.com/",
 // Bob likes .well-known:
 "json": "https://bob.example.com/.well-known/human.json",
 "vouched_at": "2026年03月08日"
 },
 {
 "url": "https://example.com/~charlie",
 // Charlie doesn't have a human.json yet, but he could put it here in the future:
 // "json": "https://example.com/~charlie/human.json"
 "vouched_at": "2026年03月08日"
 }
 ]
}

> The `<link>` approach allows people to put the file anywhere they want, which is useful for web hosts that restrict the location of files. It also allows web browser( extension)s to detect the presence of a human.json without having to make another request, which is nice. So, I didn't open this ticket to propose doing away with `<link>`, it's useful! ... it would just be nice if it weren't the *only* way to discover a human.json. :) > But this adds some complications, since the url can now either be a direct link to a human.json file or a URL directory. Oh, definitely. I wouldn't recommend overloading/redefining the "url" field. What about adding an extra, optional `"json"` or `"human.json"` field? So you could have: ```json { "version": "0.x.y", "url": "https://robida.net", "vouches": [ { "url": "https://alice.example.com/", "json": "https://alice.example.com/human.json", "vouched_at": "2026年03月09日" }, { "url": "gemini://bob.example.com/", // Bob likes .well-known: "json": "https://bob.example.com/.well-known/human.json", "vouched_at": "2026年03月08日" }, { "url": "https://example.com/~charlie", // Charlie doesn't have a human.json yet, but he could put it here in the future: // "json": "https://example.com/~charlie/human.json" "vouched_at": "2026年03月08日" } ] } ```

pinguin commented 2026年03月19日 14:42:39 +01:00

I think it would be great to have it discoverable via some other way, I thought maybe a DNS record (some txt which points to where the files is or something) or, as mentioned before, a .well-known url. The original method currently noted in the README should still exist of course, but being able to have a DNS record or a well known url could make it easier for some people.

I think it would be great to have it discoverable via some other way, I thought maybe a DNS record (some txt which points to where the files is or something) or, as mentioned before, a `.well-known` url. The original method currently noted in the README should still exist of course, but being able to have a DNS record or a well known url could make it easier for some people.

Dan-Q commented 2026年04月18日 19:10:47 +02:00

The Link: HTTP header is designed for exactly this purpose: expressing <link>s but for URLs that are potentially non-HTML documents. Raised issue #55 to add "Link: is valid too" to the standard, which would fix this and provide other benefits too.

The `Link:` HTTP header is designed for exactly this purpose: expressing `<link>`s but for URLs that are potentially non-HTML documents. Raised issue #55 to add "Link: is valid too" to the standard, which would fix this and provide other benefits too.

shinmera commented 2026年05月23日 20:36:29 +02:00

The Link header still enforces the use of HTTP. A URI DNS record would also permit other protocols such as Gemini to enter the graph.

The Link header still enforces the use of HTTP. A [URI DNS](https://en.wikipedia.org/wiki/URI_record) record would also permit other protocols such as Gemini to enter the graph.