Implement the Joshternet

Publish /.well-known/josh. RFC-JOSH-0002 is authoritative. RFC-JOSH-0001 covers the optional josh member.

What implementation requires today

An origin participates in the Joshternet by publishing a valid version 1 JSON declaration at exactly:

/.well-known/josh

There is no trailing slash.

For this origin:

https://example.invalid/

the declaration is published at:

https://example.invalid/.well-known/josh

The declaration applies only to the origin that serves it. It does not automatically cover other origins or subdomains.

For example, https://example.invalid/ and https://www.example.invalid/ must publish their own declarations if both origins intend to declare participation.

Choose a declaration

Participate without declaring Josh identity

The minimum valid declaration is:

{
  "version": 1
}

Publishing this declaration establishes participation with Undeclared Josh Identity.

It does not affirm or decline Josh identity. It must not be described as a Josh declaration, and identity must not be inferred from the site’s name or content.

Affirm Josh identity

A participant affirming Josh identity may publish:

{
  "version": 1,
  "josh": true
}

The Boolean value true represents Affirmed Josh Identity according to RFC-JOSH-0001.

Participate while declining Josh identity

A participating non-Josh may publish:

{
  "version": 1,
  "josh": false
}

The Boolean value false represents Declined Josh Identity while the declaration still establishes participation.

It does not opt the origin out of the Joshternet.

Omitting josh is different from setting it to false. An omitted member means Undeclared Josh Identity, not Declined identity, Affirmed identity, or non-participation.

Publish the declaration

The public resource is exactly /.well-known/josh. That path is defined by the protocol. It does not become /.well-known/josh.json.

Where practical, keep the declaration in source control as a normal JSON file named josh.json, so editors and validators recognize it. The site’s build then publishes that file at the extensionless public path. josh.json is an authoring detail. /.well-known/josh is the resource clients request.

A site can also place an ordinary static file named josh inside a .well-known directory at the public root. That file is the published resource itself.

It does not require an API, database, middleware, framework, or client-side JavaScript. Handwritten sites, static generators, blogs, and web applications can all publish the same resource.

Clients retrieve the declaration using HTTP GET.

A valid declaration is normally returned with:

200 OK

The server should return:

Content-Type: application/json

The declaration must be publicly retrievable without authentication or client-side script execution. Normal HTTP caching may be used.

Serving the declaration directly is preferred. Consumers may follow same-origin redirects. A cross-origin redirect does not count as the declaration for the original origin.

After deployment, replace the fictional domain below with your own origin and inspect the response:

curl -i https://example.invalid/.well-known/josh

Check the status, content type, and JSON body. You can also paste the file, or ask this site to read a live origin, on the declaration checker.

Platform recipes

These recipes are non-normative. RFC-JOSH-0002 remains authoritative. Tested site software recipes live under Platforms, so the file layout, build step, host headers, and deployment check for each platform stay together without crowding the Implement nav.

• Platforms — tested site-software recipes for publishing /.well-known/josh.
• Buttons embed the registry membership state on independent sites.
• Connections describes the build-time crawl that gathers Connections and Topics from Network sites.
• Explore describes presentation projections for What’s New, Topics, and Search.

A platform page is added after that recipe has been tested. The public resource stays /.well-known/josh on every one of them.

Participation and discovery are separate

Publishing a valid /.well-known/josh declaration establishes participation according to RFC-JOSH-0002. It does not notify JoshBot or any other discovery service, and it does not guarantee that an origin will appear in a registry.

Discovery systems are separate implementations built on top of the Joshternet specifications.

JoshBot independently verifies origins that it learns about. An origin must publish a valid declaration and pass verification before JoshBot can represent it as a participating origin in its public registry.

The reverse is also important: being discovered or crawled by JoshBot does not establish Joshternet participation or Josh identity.

Crawler permission is separate as well. A valid Joshternet declaration does not require an origin to permit JoshBot crawling, and allowing JoshBot to crawl a site does not create a Joshternet declaration.

Validate version 1

A valid version 1 declaration must:

• contain valid JSON;
• use a JSON object as the top-level value;
• contain no duplicate member names;
• include version;
• set version to the JSON integer 1;
• use a JSON Boolean for josh when that member is present.

The following declarations are invalid.

A string is not a valid version:

{
  "version": "1"
}

A string is not a valid josh value:

{
  "version": 1,
  "josh": "true"
}

A number is not a valid josh value:

{
  "version": 1,
  "josh": 1
}

null is not a valid josh value:

{
  "version": 1,
  "josh": null
}

Consumers must not coerce these values into valid ones.

Unknown members

Version 1 declarations may contain members not defined by RFC-JOSH-0002.

Consumers should ignore unknown members unless another supported Joshternet specification defines them. Unknown members must not alter the meaning of version, josh, or participation through publication.

The examples in this guide use only the members defined by RFC-JOSH-0002.

Stop declaring participation

An origin stops declaring participation by ceasing to publish a valid declaration.

Responses such as:

404 Not Found

or:

410 Gone

indicate that no declaration is currently published.

Temporary failures do not establish intentional withdrawal. DNS failures, TLS failures, timeouts, and server errors may prevent retrieval without showing that the operator intended to stop participating.

Implementation checklist

Before considering an origin implemented, verify that:

• the path is exactly /.well-known/josh, without a trailing slash;
• the response body is a valid JSON object;
• no duplicate JSON member names are present;
• version is present and is the integer 1;
• josh, when present, is a Boolean;
• HTTP GET normally returns 200 OK;
• the response should use Content-Type: application/json;
• the resource is public and requires no authentication;
• retrieving the declaration requires no client-side JavaScript;
• any redirect that is followed remains on the same origin;
• the declaration is published separately for every participating origin.

Authoritative text

Read RFC-JOSH-0002: /.well-known/josh for the authoritative protocol requirements.

Read RFC-JOSH-0001: Josh Identity for the authoritative definitions of Affirmed, Declined, and Undeclared Josh Identity.

The Joshternet specification repository is the canonical home of the current specifications.