Internet-Draft Well Known Button.json September 2026
Filmröllchen & LunarEclipse Expires 31 March 2027 [Page]
Workgroup:
Internet Engineering Task Force
Internet-Draft:
draft-filmroellchen-lunar-well-known-button-01
Published:
Intended Status:
Informational
Expires:
Authors:
Filmröllchen
LunarEclipse

The Well Known Button Information Specification

Abstract

This document specifies the well-known URI /.well-known/button.json, which describes a web site's "buttons". Buttons are usually 88x31 pixel images representing the web site with text, logos, artwork, and animations.

/.well-known/button.json files facilitate sharing buttons between web site owners and alleviate issues commonly encountered when doing so. By utilizing a standardized, machine-readable format, automated tools can also utilize the provided information.

About This Document

This note is to be removed before publishing as an RFC.

Status information for this document may be found at https://datatracker.ietf.org/doc/draft-filmroellchen-lunar-well-known-button/.

Source for this draft and an issue tracker can be found at https://codeberg.org/LunarEclipse/well-known-button.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on 31 March 2027.

▲

Table of Contents

1. Introduction

"Buttons", in the context of this specification, refer to a certain type of common image on the Web. Buttons are graphics, usually 88 pixels wide and 31 pixels high, featuring text, logos, artwork, as well as animations. The purpose of a button is to represent the web site or its owner(s)/author(s), often using minimal information to do so, owing to the low resolution available. For this representational purpose, buttons are usually intended to be included on other web sites, most commonly in a footer or other dedicated section. This way, web site owners may show their affiliation with, or appreciation of other's web sites.

Buttons originate from the early days of the Web as a form of banners, originally representing the site or technology used to host a particular home page. The 88x31 format, also named "Micro Button", originated with the free hosting provider GeoCities.com and their mandatory advertising banner. For a detailed historical account, see [Tekeye]. Buttons have seen a renewed surge in popularity in the 2020s with certain subcultures.

The goal of this specification is to provide a clearly defined standard for web site authors who wish to share web site buttons with other web site authors and end users, and lay out a format for a common endpoint that can be used to fetch and/or embed the buttons. To this end, this specification introduces a new well-known [RFC8615] URI utilizing a standard JSON format to specify one or more buttons.

The intended use cases are:

The specification aims to be easy to implement for web sites using shared hosting providers, which are unable to change HTTP response headers and cannot host extension-less files.

Accessibility is a primary concern of this specification. Images and fast animations are notoriously inaccessible to users with vision impairment, light-sensitivity, and other disabilities. This specification attempts to combat that by requiring image descriptions, and providing a standard mechanism for selecting between multiple versions of a button for accessibility purposes.

1.1. Requirements Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

1.2. Definitions

A server is any web server providing a /.well-known/button.json file.

A client is any program accessing the /.well-known/button.json of a server. Clients include other web servers, automated programs, as well as programs manually invoked on behalf of a user.

An animated image (as opposed to a static image) is an image which has multiple frames of nonzero and non-infinite length, where at least one of the frames is visually distinct from the others. Examples:

  • A GIF image with three frames, all containing different text in front of the same background, is animated.

  • A WEBP image with two very distinct frames is animated.

  • An AVIF image with several hundred frames and over two minutes in runtime, featuring a "gloss" effect that very slowly moves across the image, is animated.

  • A GIF image abusing a frame time of zero to show more than 256 colors at once is animated, as almost every modern program restricts the frame time to a minimum of 10ms.

  • An AVIF image with five frames, all of which are identical, is not animated.

  • An APNG image with two thousand identical frames is not animated.

  • A GIF image with a single frame is not animated.

2. button.json Files

The main element of this specification is the /.well-known/button.json file. This is a well-known [RFC8615] URI registered with IANA; see Section 5.

A server supporting this specification MUST serve a conforming file on the top-level path /.well-known/button.json. The file SHOULD be available via HTTPS [RFC9110]. Availabilities by other protocols are allowed, but the file is primarily intended for the Web.

If using HTTP, the file SHOULD be served using the Content-Type header set to application/json; charset=utf-8. The file MUST be valid JSON [RFC8259], and MUST be encoded using UTF-8 [RFC3629]. HTTP caching headers and content encoding MAY be used.

A normative description for requirements of various /.well-known/button.json entries follows. A normative JSON Schema [JSON-Schema] which defines the basic syntax rules is provided in Appendix A. and can be used to validate /.well-known/button.json files. Not all files conforming to the schema are necessarily correct implementations of this specifications.

The top-level $schema property MUST be present and link to the canonical location of the schema version used by the document. The server MAY provide a /.well-known/button.schema.json file containing a copy of the used schema.

The $schema value for this RFC is https://codeberg.org/LunarEclipse/well-known-button/raw/branch/main/drafts/draft-filmroellchen-lunar-well-known-button-01.schema.json.

Note to the RFC editor: During draft stage, the $schema value is https://codeberg.org/LunarEclipse/well-known-button/raw/branch/main/drafts/draft-filmroellchen-lunar-well-known-button-XX.schema.json, where XX is the draft version. After publication, the $schema property should be changed to https://codeberg.org/LunarEclipse/well-known-button/raw/branch/main/rfcXXXX.schema.json, where XXXX is the RFC number of this specification. This change must also apply to all examples and the JSON Schema below.

The top-level buttons property MUST be present and contain a list of objects, each of which specifies a single button.

The top-level default property is OPTIONAL and specifies which button is considered the default one when multiple are present. It MUST contain an id matching that of one of the buttons present in the file.

2.1. Button Objects

The button objects are the objects in the buttons list. Each one specifies an independent single button. The validity of button objects SHOULD be determined independently by clients; one invalid button object provided by the server does not affect the validity of another button object in the same file.

2.1.1. Required Properties

Clients MUST reject button objects which do not provide all of the id, uri, and alt properties.

2.1.1.1. id

The id property serves to identify the button uniquely across revisions. This property is REQUIRED.

Revisions of the same button MUST share the same id property, and consequently MUST NOT appear in the same button.json file. Multiple different buttons MUST NOT have the same id value.

The server chooses the id property arbitrarily. Clients MUST NOT make any assumptions about the content of the id property, and MUST treat it as an arbitrary [Unicode] string. Clients SHALL NOT assume IDs are unique across web sites.

2.1.1.2. uri

The uri property is the canonical location of the button, from which any client can access the button's image file. This property is REQUIRED. The uri property MUST contain a valid URI [RFC3986] using the https protocol name, and must subsequently be accessible using the HTTPS [RFC9110] Internet protocol.

Referenced image files SHOULD have a height of 31 pixels and width of 88 pixels. Images MAY be larger in size, but SHOULD maintain the aspect ratio, and SHOULD be legible when scaled down to a width of 88 pixels and height of 31 pixels.

Image files may be either static or animated; see Section 1.2 for a detailed definition including edge-case examples. The following image file formats are RECOMMENDED in order of preference:

  • SVG [SVG]: static vector graphics

  • AVIF [AVIF]: animated and static images

  • WEBP [RFC9649]: animated and static images

  • PNG [PNG]: static images

  • GIF [GIF]: animated and static images

Button images SHOULD NOT be lossily compressed. Of the recommended image formats, AVIF and WEBP are capable of lossy compression. They SHOULD be avoided for new buttons, as at the small resolutions typically used, the space savings offered by lossy compression are minimal while the quality loss can be significant.

2.1.1.3. alt

The alt property MUST be provided, describing the visual content of the button for vision-impaired users.

The language of the text contained within the alt property is specified by the lang property, if present.

2.1.2. Optional Properties

2.1.2.1. lang

The lang property is an OPTIONAL property specifying the language of this button’s description. lang contains an [RFC5646] language identifier tag. All fields containing regular text, namely alt, caption, and licenseText, are written using the language specified by the lang property, if present.

If lang is absent, the language of the aforementioned fields is unspecified. Clients SHOULD NOT assume any particular language to be used for interpreting these fields, and SHOULD NOT attempt to guess the language using natural language processing algorithms.

The lang property is also part of the properties that may be changed within a group of buttons. If two buttons have the same groupId, colorScheme, animations, contrast, and uri property, but distinct lang properties, clients SHOULD interpret these different button objects to refer to the same logical button, except with text fields provided in different languages. The buttons MUST still have distinct id properties, even though they may be considered logically identical. Servers MAY use similar IDs, or IDs suffixed with language identifiers, to denote the logical identity of the buttons. Clients can use the logically identical buttons to select the text fields based on a user’s language preference. Clients SHOULD prefer buttons with a lang attribute present to a logically identical button with no lang attribute.

2.1.2.4. sha256

The sha256 property is OPTIONAL. It facilitates caching and validation of the image file. This property MUST contain the SHA256 [RFC6234] content hash of the image file as a hexadecimal number (64 characters). Clients SHOULD assume that a button image has not changed if the sha256 property has not changed since the last time the client downloaded the button image, even if other properties have been changed, including the uri property.

2.1.2.5. caption

The OPTIONAL caption property provides a caption or title for the button. The contents of this property are distinct from the alt property, as they are intended to be shown to every user. RECOMMENDED methods of displaying the caption text include the HTML title attribute [html-title], as well as conventional figure caption text.

The language of the text contained within the caption property is specified by the lang property, if present.

2.1.2.6. imageRendering

The OPTIONAL imageRendering property provides guidance on how to render scaled images. In several circumstances, such as rendering buttons at increased size, or when using displays with high DPI, images need to be scaled to more than 88x31 physical device pixels. However, while some buttons are designed for nearest-neighbor scaling (preserving a pixelated look), some are designed for smooth scaling (as is commonplace for most graphics). Using this property, the author can specify which of the two scaling methods the button is intended for.

In general, any of the possible image-rendering [image-rendering] CSS properties MAY be used. In this case, web sites MAY use the imageRendering property verbatim as the CSS image-rendering property for the button in this case. (See Section 8.1 for the security implications of this approach.)

The following values are RECOMMENDED for use in imageRendering. Other values SHOULD be interpreted as per the image-rendering [image-rendering] CSS specification.

  • auto: Client decides which rendering method to use; equivalent to omitting this property.

  • pixelated: Nearest neighbor scaling to an integer multiple of the image dimensions.

  • smooth: Smooth scaling, such as bilinear filtering.

At time of publication, the CSS value smooth is not yet honored by all major browsers. However, the default image rendering method is almost always smooth scaling, therefore auto MAY be used in CSS instead.

If this property is not specified, clients MAY choose any rendering method, such as one in line with a page's style. Even if this property is specified, clients MAY choose other rendering methods for a variety of reasons. However, client authors and users MUST be aware of the subsequent degradation of authorial intent, since the image author might have designed the button around a very specific rendering method.

2.1.2.7. license

The OPTIONAL license property contains an SPDX license expression [SPDX-license-expressions] identifying the license that applies to the button image file and this button object describing it. See Legal considerations (Section 6) for a discussion of button licensing, including recommended license choices.

2.1.2.8. licenseText

The OPTIONAL licenseText property contains arbitrary text augmenting the license data in the license property. This property should be considered as legally binding as the license property. It is NOT RECOMMENDED to specify licenseText without license; several SPDX license expressions are available which reference nonstandard licenses, such as DocumentRef and LicenseRef.

RECOMMENDED use cases for licenseText are:

  • Adding authorship information, especially when the image author is not the web site author

  • Adding a copyright year

  • Adding a completely custom license in combination with a LicenseRef entry in the license property

The language of the text contained within the licenseText property is specified by the lang property, if present.

2.1.3. Accessibility Properties

By using the groupId property, a group of interchangeable and equivalent buttons can be defined. The client's specific choice of button among these can then be tailored to the user or the application, improving accessibility.

2.1.3.1. groupId

The OPTIONAL groupId property defines a group of button versions. Multiple buttons using the same groupId entry belong to one group. A client SHALL assume those buttons are interchangeable, and they MAY choose one of them depending on the user's requirements.

The server chooses the groupId property arbitrarily. Clients MUST NOT make any assumptions about the content of the id property, and MUST treat it as an arbitrary [Unicode] string. Clients SHALL NOT assume IDs are unique across web sites.

The properties colorScheme, animations, contrast, and lang allow providing different versions of a button to fit accessibility and/or styling needs. They SHOULD be present if the server shares different versions of a button with the same groupId. Within the same groupId, multiple buttons SHOULD NOT have identical values for these properties.

As described above, the lang (Section 2.1.2.1) property may be altered without altering any of the other accessibility properties or the uri property. This includes cases where other accessibility properties are absent. The two buttons are then considered logically identical, and the client SHOULD choose a button based on the user’s language preferences.

The following properties MAY also be provided if the groupId property is absent. In this case, the properties provide accessibility guidance without the possibility of client choice. The lang property SHOULD always be provided regardless of the presence of the groupId property.

2.1.3.2. colorScheme

The OPTIONAL colorScheme property specifies what color scheme the button version uses. It is to be interpreted as per [prefers-color-scheme] CSS media query.

It can take on the following values:

  • other: the default, equivalent to not specifying this property, clients SHOULD NOT make any assumptions about the color scheme

  • light: light theme, typically dark text on a light background

  • dark: dark theme, typically light text on a dark background

2.1.3.3. animations

The OPTIONAL animations property SHOULD be provided if the button is animated, even if the button is not in a group. It specifies the amount and severity of the animations present in the button. Clients MAY consider all animated buttons without this property to have the value high.

It can take on the following values:

  • none: the image is not animated at all

  • minimal: the image contains only very subtle animations

  • high: the image contains animations that are permanently active, distracting, or could trigger medical conditions such as light-sensitive epilepsy

Authors SHOULD use the high value for animated buttons if there is any doubt about the severity of the animations.

If there is no static alternative to an animated button, but a static image is desired by the client or the end-user, clients MAY use the CSS property image-animation [image-animation] to disable animations on an animated button.

2.1.3.4. contrast

The OPTIONAL contrast property MUST have one of the following values:

  • standard: the default, equivalent to not specifying this property.

  • more: a higher-contrast version of the button, whose text is STRONGLY RECOMMENDED to follow the WCAG 2.2 AA or AAA guidelines for color contrast in normal text [WCAG-contrast], i.e. 4.5:1 or 7:1.

  • less: a lower-contrast version of the button, whose text color contrast is below 3:1. This means that it does not follow the WCAG 2.2 color contrast guidelines at all, not even for large text or graphics.

If two buttons with substantially distinct color contrasts would fall into the same contrast category according to the above definitions, distinct contrast values SHOULD be used by applying the following rules:

  • If both buttons are at less contrast, the higher-contrast one SHOULD be instead marked as standard.

  • If both buttons are at more contrast, the lower-contrast one SHOULD be instead marked as standard.

  • If both buttons are at standard contrast, the lower-contrast one SHOULD be instead marked as less.

Since none of these rules are strictly required, implementations MAY deviate in order to utilize all three contrast values.

3. Examples

A typical example is as follows:

{
  "$schema": "https://codeberg.org/LunarEclipse/well-known-button/raw/branch/main/drafts/draft-filmroellchen-lunar-well-known-button-01.schema.json",
  "default": "my.web site",
  "buttons": [
    {
      "id": "my.web site",
      "uri": "https://my.website.example.org/my.website.png",
      "alt": "Button to my web site!",
      "link": "https://my.website.example.org",
      "sha256": "66a421c7e726e9de99eeb88c57b93b49278d64b2a4602a6f90f7d64baee154cf",
      "hotlink": true
    }
  ]
}

A minimal example:

{
  "$schema": "https://codeberg.org/LunarEclipse/well-known-button/raw/branch/main/drafts/draft-filmroellchen-lunar-well-known-button-01.schema.json",
  "buttons": [
    {
      "id": "some button id",
      "uri": "https://example.com/res/my-button.gif",
      "alt": "button saying example.com"
    }
  ]
}

And an exhaustive example:

{
  "$schema": "https://codeberg.org/LunarEclipse/well-known-button/raw/branch/main/drafts/draft-filmroellchen-lunar-well-known-button-01.schema.json",
  "default": "8b556a30-c5d9-4117-88a5-b779a3f2f567",
  "buttons": [
    {
      "id": "8b556a30-c5d9-4117-88a5-b779a3f2f567",
      "groupId": "mainbutton",
      "uri": "https://website.example.com/res/my-button.png",
      "alt": "button saying example.com with black text on a white background",
      "caption": "Example web site",
      "sha256": "e35a78bcb7f9b9cc0c3929d1763b96b6013071b0f9950886a20d2bcc0e943612",
      "link": "https://website.example.com/",
      "colorScheme": "light",
      "animations": "none",
      "contrast": "more",
      "license": "CC-BY-SA-4.0",
      "licenseText": "Copyright 2024 by the Example Author",
      "imageRendering": "pixelated",
      "hotlink": false
    },
    {
      "id": "64dbf02d-44e0-4aa9-ad45-c4959eadd3db",
      "groupId": "mainbutton",
      "uri": "https://website.example.com/res/my-button-dark.png",
      "alt": "button saying example.com with white text on a black background",
      "caption": "Example web site",
      "sha256": "4598d79c6c1877aa9121c8b0845fe4e8f031684fabb09caa10357dfe5d295986",
      "link": "https://website.example.com/",
      "colorScheme": "dark",
      "animations": "none",
      "contrast": "more",
      "license": "CC-BY-SA-4.0",
      "licenseText": "Copyright 2024 by the Example Author",
      "imageRendering": "auto",
      "hotlink": false
    },
    {
      "id": "57ad38e5-94ad-4b64-a6bc-583f41b7c3b5",
      "groupId": "mainbutton",
      "uri": "https://website.example.com/res/my-button-rainbow.gif",
      "alt": "button saying example.com with black text on an animated rainbow background",
      "caption": "Example web site",
      "sha256": "2fecb1bbd1fdb1f8fa634632f9726f9bce7f653fe94cde59b616f4032b70a758",
      "link": "https://website.example.com/",
      "colorScheme": "other",
      "animations": "high",
      "contrast": "standard",
      "license": "LicenseRef-Commercial",
      "licenseText": "Copyright 2024 by the Example Author, all rights reserved. You can include this button on your page but nothing else.",
      "imageRendering": "smooth",
      "hotlink": true
    },
    {
      "id": "ee5cc4b3-b88b-4b1c-ae1f-fb9a3de063c9",
      "uri": "https://website.example.com/res/blog-button.gif",
      "alt": "example.com blog button with some starts gently twinkling in the background",
      "caption": "Example web site",
      "sha256": "b2fe6da951362a7e3909390c5634fe4804cb845eddccad8dcea5819122f94be0",
      "link": "https://website.example.com/blog/",
      "animations": "minimal",
      "license": "CC-BY-SA-4.0",
      "licenseText": "Copyright 2024 by the Example Author",
      "hotlink": true
    }
  ]
}

3.1. HTML Examples

These examples show possible compliant HTML5 source code which may be generated based on .well-known/button.json data. They are neither normative, nor do they represent the only compliant HTML that may be generated from the data. The HTML is provided purely for the information of implementors.

Based on the typical example above, the following HTML may be generated:

<a href="https://my.website.example.org">
  <img
    class="button"
    src="https://my.website.example.org/my.website.png"
    alt="Button to my web site!"
    loading="lazy"
  />
</a>

Note that this button allows hotlinking, and the HTML makes use of this here. Additionally, the loading="lazy" option avoids loading the button on a web page unless the user scrolls over it, reducing page load times. Alternatively, the client may copy the image to their own web server, serve it on the path /buttons/my.website.png, and use the following HTML instead:

<a href="https://my.website.example.org">
  <img
    class="button"
    src="/buttons/my.website.png"
    alt="Button to my web site!"
    loading="lazy"
  />
</a>

As an extended example, the following HTML may be generated from the button with ID ee5cc4b3-b88b-4b1c-ae1f-fb9a3de063c9 in the exhaustive /.well-known/button.json example above. Once again the client chose not to hotlink the button despite "hotlink": true.

<a href="https://website.example.com/blog/" title="Example web site">
  <img
    class="button"
    src="/buttons/blog-button.gif"
    alt="example.com blog button with some starts gently twinkling in the background"
    loading="lazy"
  />
</a>

Since the button author specified a license and accompanying text, the client should include this somewhere on their web site, such as:

<p>The button for the <a href="https://website.example.com/blog/">
example.com blog</a> is licensed under
<a href="https://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA 4.0
</a>. Copyright 2024 by the Example Author.
</p>

4. Implementation Considerations

Button images SHOULD be compressed as strongly as possible. For example, typical images of size 88x31 can reach about 800-1000 bytes in size using the PNG format, but are frequently distributed with sizes between 10% and 200% larger than this. Using strong compression usually does not affect decoding time for the recommended image formats, but reduces bandwidth requirements on both server and client, especially when the image is hotlinked. With the image sizes used for buttons, it is computationally feasible on consumer hardware to compress images optimally within a reasonable amount of time (usually a few minutes at maximum, usually much less).

4.1. Text property length

The minimum or maximum length of the text properties in /.well-known/button.json is not restricted. In combination with the unrestricted number of button objects that may be present within one such file, the length of the JSON document, even if minified by removing superfluous whitespace, may be arbitrarily large and cause issues with a client’s memory usage.

Therefore, clients MUST support a property length of at least 65536 bytes (2^16 or 64 KiB) for each string property that is not otherwise restricted; namely the properties id (and therefore default as well), uri, alt, caption, link, license, licenseText, groupId, and imageRendering. For imageRendering specifically, a client MAY only support the three standard values smooth, auto, and pixelated; i.e. a maximum length of 9 bytes. Any property beyond the supported length MAY be rejected by a client.

Clients SHOULD be able to handle a large number of buttons within a document, but not necessarily by reading and evaluating every single button definition. As fallback mechanisms, reading only the first button or the one set by the default property is RECOMMENDED. Servers SHOULD position the default top-level property, the default button, and other important buttons towards the start of the document, allowing them to be processed without loading or processing the entire /.well-known/button.json.

4.3. Caching

In some cases, a server-provided /.well-known/button.json may have considerable size, or it may be generated on-demand with significant processing power. Especially in these cases, it is important that servers and clients follow standard HTTP caching practice as specified by [RFC9110] and [RFC9111]. Servers SHOULD provide appropriate caching headers, allowing the client to cache the response. Clients SHOULD use HTTP caching ([RFC9111]). In particular, the following features of HTTP caching are RECOMMENDED for use by servers and implementation by clients:

  • The If-Modified-Since request header [RFC9110] (Section 13.1.3) can be used by clients to inform the server about the last time an updated /.well-known/button.json was retrieved. In accordance with the standard, servers SHOULD respond with 304 (Not Modified) to indicate no change occurred to the /.well-known/button.json file.

  • In a similar manner, the Etag response header [RFC9110] (Section 8.8.3) can be used by servers to supply an entity tag for /.well-known/button.json independently of modification times. Managed web hosting providers frequently implement Etag by default, therefore clients SHOULD implement this header and its corresponding request headers If-Match, If-None-Match, or If-Range, as per Section 4.3.1 of [RFC9111].

  • The Cache-Control: immutable response header [RFC8246], in combination with the max-age property [RFC9111] (Section 5.2.2.1) can be used by servers to specify that the /.well-known/button.json is guaranteed to be valid for the specified amount of time, and that clients never need to send another request for the /.well-known/button.json within that time frame. This can significantly reduce the load on servers where button changes occur infrequently, and where update propagation delays due to valid but stale caches are acceptable.

Button image files themselves SHOULD use HTTP caching in the same manner.

5. IANA Considerations

IANA will register the well-known URI /.well-known/button.json in the well-known URIs registry [IANA-well-known] in conformance with the requirements for this registration in [RFC8615]. The following information is provided to facilitate the registration:

In case a JSON Schema registry is set up with IANA in the future, the button.json Schema (Appendix A), as defined in this specification and any of its updates and errata, shall be registered by IANA with this JSON Schema registry. In the likely case that this JSON Schema registry includes a canonical schema URL for registered schemas, the canonical schema URL in this specification should be changed to the one registered with IANA.

7. Privacy Considerations

7.1. Exposure to Scrapers and Spiders

Specifying the location of a button image in /.well-known/button.json exposes it to automated scrapers, including malicious ones. If a web server operator wishes to decrease the visibility of the buttons, robots.txt [RFC9309] can be used to discourage scrapers from accessing /.well-known/button.json and the button images, but since some scrapers do not respect robots.txt properly, the web server may additionally need to block certain user agents and IP addresses from accessing /.well-known/button.json and/or button images.

8. Security Considerations

8.1. imageRendering CSS Injection

The imageRendering property may be set to an arbitrary string by a malicious web site operator. Clients which use the property without additional checks as part of the button's CSS properties (whether in stylesheets or inline style in HTML), are subsequently vulnerable to CSS or HTML injection attacks. Therefore, clients MUST NOT use this property without validating it, and reject any unknown values.

9. References

9.1. Normative References

[JSON-Schema]
Wright, A., Andrews, H., Hutton, B., Dennis, G., and JSON Schema, "JSON Schema, Internet-Draft 01", , <https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-01>.
[image-rendering]
World Wide Web Consortium, "CSS Images Module Level 3 Editor's Draft: 5.2: The 'image-rendering' property", n.d., <https://drafts.csswg.org/css-images/#the-image-rendering>.
[SPDX-license-expressions]
The Linux Foundation, "SPDX Specification 3.0.1 Annex B: SPDX license expressions", , <https://spdx.github.io/spdx-spec/v3.0.1/annexes/spdx-license-expressions/>.
[Unicode]
Unicode, Inc., "The Unicode Standard, Version 17.0.0", n.d., <https://www.unicode.org/versions/Unicode17.0.0/>.
[prefers-color-scheme]
World Wide Web Consortium, "CSS Media Queries Level 5 Working Draft: 12.5: The 'prefers-color-scheme' feature", n.d., <https://www.w3.org/TR/mediaqueries-5/#descdef-media-prefers-color-scheme>.
[WCAG-contrast]
World Wide Web Consortium, "Web Content Accessibility Guidelines 2.2: 1.4.3 Contrast (Minimum)", , <https://www.w3.org/TR/WCAG22/#contrast-minimum>.
[IANA-well-known]
Internet Assigned Numbers Authority, "Well-Known URIs Registry", n.d., <https://www.iana.org/assignments/well-known-uris/well-known-uris.xhtml>.
[RFC8615]
Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, , <https://www.rfc-editor.org/rfc/rfc8615>.
[RFC2119]
Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/rfc/rfc2119>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/rfc8174>.
[RFC9110]
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Semantics", STD 97, RFC 9110, DOI 10.17487/RFC9110, , <https://www.rfc-editor.org/rfc/rfc9110>.
[RFC8259]
Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, , <https://www.rfc-editor.org/rfc/rfc8259>.
[RFC3629]
Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, , <https://www.rfc-editor.org/rfc/rfc3629>.
[RFC3986]
Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, , <https://www.rfc-editor.org/rfc/rfc3986>.
[RFC5646]
Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, , <https://www.rfc-editor.org/rfc/rfc5646>.
[RFC6234]
Eastlake 3rd, D. and T. Hansen, "US Secure Hash Algorithms (SHA and SHA-based HMAC and HKDF)", RFC 6234, DOI 10.17487/RFC6234, , <https://www.rfc-editor.org/rfc/rfc6234>.
[RFC9111]
Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Caching", STD 98, RFC 9111, DOI 10.17487/RFC9111, , <https://www.rfc-editor.org/rfc/rfc9111>.
[RFC8246]
McManus, P., "HTTP Immutable Responses", RFC 8246, DOI 10.17487/RFC8246, , <https://www.rfc-editor.org/rfc/rfc8246>.

9.2. Informative References

[Tekeye]
Fowler, D., "Remembering Powered By and 88×31", , <https://www.tekeye.uk/computer_history/powered-by>.
[SVG]
Bellamy-Royds, A., Brinza, B., Lilley, C., Schulze, D., Storey, D., Willigers, E., and World Wide Web Consortium, "Scalable Vector Graphics (SVG) 2", , <https://www.w3.org/TR/SVG2/>.
[AVIF]
Guyon, Y., Barnes, L., Chang, W.-T., Concolato, C., Kerr, P., Klements, A., and Alliance for Open Media, "AV1 Image File Format (AVIF)", , <https://aomediacodec.github.io/av1-avif/v1.2.0.html>.
[PNG]
Blume, C., Lemieux, P.-A., Lilley, C., Needham, C., Rosenthol, L., Seeger, C. A., Thompson, S., Truta, C., and World Wide Web Consortium, "Portable Network Graphics Specification (Third Edition)", , <https://www.w3.org/TR/png-3/>.
[GIF]
CompuServe Incorporated, "Graphics Interchange Format", , <https://www.w3.org/Graphics/GIF/spec-gif87.txt>.
[html-title]
WHATWG, "HTML: 3.2.6.1: The 'title' attribute", n.d., <https://html.spec.whatwg.org/multipage/dom.html#the-title-attribute>.
[CC]
Creative Commons, "Creative Commons Licenses", n.d., <https://creativecommons.org/cc-licenses/>.
[CC0]
Creative Commons, "CC0 1.0 Universal", n.d., <https://creativecommons.org/publicdomain/zero/1.0/>.
[Unlicense]
Bendiken, A., "The Unlicense", , <https://unlicense.org/>.
[image-animation]
World Wide Web Consortium, "CSS Image Animation Editor’s Draft: 2: The 'image-animation' property", n.d., <https://drafts.csswg.org/css-image-animation-1>.
[RFC9649]
Zern, J., Massimino, P., and J. Alakuijala, "WebP Image Format", RFC 9649, DOI 10.17487/RFC9649, , <https://www.rfc-editor.org/rfc/rfc9649>.
[RFC9309]
Koster, M., Illyes, G., Zeller, H., and L. Sassman, "Robots Exclusion Protocol", RFC 9309, DOI 10.17487/RFC9309, , <https://www.rfc-editor.org/rfc/rfc9309>.

Appendix A. JSON Schema for button.json

The following is the JSON Schema [JSON-Schema] file for /.well-known/button.json. This JSON Schema is normative; all /.well-known/button.json implementations MUST conform to this schema.

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://codeberg.org/LunarEclipse/well-known-button/raw/branch/main/drafts/draft-filmroellchen-lunar-well-known-button-01.schema.json",
  "title": ".well-known 88x31 Button JSON Schema",
  "type": "object",
  "properties": {
    "$schema": {
      "title": "The URI of the schema used by this document.",
      "type": "string",
      "format": "uri"
    },
    "default": {
      "title": "The id of the button to use as the default.",
      "type": "string"
    },
    "buttons": {
      "type": "array",
      "items": {
        "title": "An 88x31 button available from the web site",
        "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"
          },
          "lang": {
            "title": "Language of all text in this button’s specification",
            "type": "string"
          },
          "caption": {
            "title": "Image caption or title",
            "type": "string"
          },
          "link": {
            "title": "Where the image should link to if used on another web site",
            "type": "string",
            "format": "uri"
          },
          "hotlink": {
            "title": "Whether image should be hotlinked",
            "type": "boolean",
            "default": false
          },
          "sha256": {
            "title": "SHA256 hash of the current version of the image file",
            "type": "string",
            "format": "regex",
            "pattern": "^[A-Fa-f0-9]{64}$"
          },
          "license": {
            "title": "SPDX license expression specifying the license for the image file",
            "type": "string"
          },
          "licenseText": {
            "title": "Additional license information to augment the license property",
            "type": "string"
          },
          "groupId": {
            "title": "A group of interchangeable versions of a button with different accessibility properties",
            "type": "string"
          },
          "colorScheme": {
            "title": "What color scheme does this button version match",
            "type": "string",
            "enum": ["light", "dark", "other"],
            "default": "other"
          },
          "animations": {
            "title": "Whether this button version is animated, and to what degree",
            "type": "string",
            "enum": ["none", "minimal", "high"]
          },
          "contrast": {
            "title": "The contrast level of this button version",
            "type": "string",
            "enum": ["standard", "more", "less"],
            "default": "standard"
          },
          "imageRendering": {
            "title": "Image rendering algorithm",
            "description": "Which scaling algorithm to use for the image if it is not displayed at native resolution, recommended: 'smooth', 'auto' or 'pixelated'",
            "type": "string",
            "default": "auto"
          }
        },
        "required": ["id", "uri", "alt"]
      }
    }
  },
  "required": ["$schema", "buttons"]
}

Appendix B. Migrating from earlier versions of this specification

B.1. Migrating from draft 2024-05

At a basic level, this can be done easily with jq:

jq '{ "$schema": "https://codeberg.org/LunarEclipse/well-known-button/raw/branch/main/drafts/draft-filmroellchen-lunar-well-known-button-01.schema.json", "buttons": . }' $old_filename > $new_filename

You will no longer need special logic for your web server, instead the new path for the file is /.well-known/button.json.

You may add a copy of the schema version matching your file in /.well-known/button.schema.json.

You might want to add a default property, especially if you provide multiple buttons.

You should consider adding the extra accessibility properties where the default values aren't sufficient (especially animations).

B.2. Migrating from draft 2024-06

The current schema is backwards-compatible with the 2024-06 one, adding only optional properties.

You should consider adding the new properties where applicable, especially license.

Acknowledgements

This specification would not have been possible without the many excellent ideas from various beings, most of which are listed under Appendix "Contributors". The authors thank Arch Retriever in particular for the original ./well-known/button.json idea.

Contributors

Arch Retriever
URI: https://arch.dog

Arch came up with the idea and created the original version of this specification.

Reina

Reina contributed the idea of an alt text property.

Sugar

Sugar contributed ideas on how to make this specification more accessible to people using shared hosting services.

Seirdy

Seirdy contributed the idea of multiple versions of a button with different accessibility properties.

Soblow Opale Xaselgio
France
URI: https://xaselgio.net

Soblow contributed examples and correction to the 2024 second draft, as well as the hotlink attribute.

Natty
URI: https://natty.sh

Natty contributed the idea of a caption property distinct from the alt property.

Authors' Addresses

kleines Filmröllchen
Germany
URI: https://filmroellchen.eu
Lunar Eclipse
Poland
URI: https://lunareclipse.zone