.well-known/button

There can be two options for the .well-known/button endpoint. The simplest is serving an image file widely supported by clients, with a height of 31 pixels and width of 88 pixels. Images MAY be larger in size, but MUST maintain the aspect ratio, and SHOULD be legible when scaled down to a width of 88 and height of 31.

The second option is a JSON response. The endpoint MUST default to an image file, but clients can request the JSON format with either a query parameter .well-known/button?format=json or the Accepts: application/json HTTP header. The JSON is an array with objects following this schema (thanks to lunareclipse for making a proper schema):

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://gmem.ca/button-schema",
  "title": ".well-known 88x31 Button JSON Schema",
  "type": "array",
  "items": {
    "title": "An 88x31 button available from the website",
    "type": "object",
    "properties": {
      "id": {
        "title": "The ID of the button",
        "type": "string"
      },
      "uri": {
        "title": "The canonical uri of the image file",
        "type": "string",
        "format": "uri",
        "pattern": "^https://"
      },
      "alt": {
        "title": "Alt text for the image",
        "type": "string"
      },
      "link": {
        "title": "Where the image should link to if used on another website",
        "type": "string",
        "format": "uri"
      },
      "sha256": {
        "title": "SHA256 hash of the current version of the image file",
        "type": "string",
        "format": "regex",
        "pattern": "^[A-Fa-f0-9]{64}$"
      }
    },
    "required": [
      "id",
      "uri",
      "alt"
    ]
  }
}

The id field is for identificaton by the server and the client. The client can use this field however they like, but the server MUST provide one. The URI is the canonical HTTPS location of the badge, MUST use the HTTPS protocol, and MUST follow the same rules for a non-JSON endpoint. The alt text field MUST be filled for accessibility, describing the content of the button or the website being linked if the link field is present. An optional link URL may be provided, which can be used by a client to render a link element to an external resource. Servers MAY provide this field, and clients MUST use it when provided. A SHA256 hash in a hex format may be provided for client caching to avoid fetching the URI to check for changes, and can also be used for validation of the URIs contents.

A full example is as follows:

[
  {
	"id": "arch.dog",
	"uri": "https://arch.dog/arch.dog.png",
        "alt": "Button to Arch's website!",
	"link": "https://arch.dog",
	"sha256": "66a421c7e726e9de99eeb88c57b93b49278d64b2a4602a6f90f7d64baee154cf"
  }
]

If a JSON format is not available, the server MUST return the regular image file, along with the correct Content-Type HTTP header. The client MUST respect this and render the image directly.