]>

DE kleines+ietf@filmroellchen.eu https://filmroellchen.eu

PL luna@lunareclipse.zone https://lunareclipse.zone

Internet Engineering Task Force HTTP .well-known Image 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. Status information for this document may be found at . Source for this draft and an issue tracker can be found at .

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 . 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 URI utilizing a standard JSON format to specify one or more buttons. The intended use cases are: to share buttons in a standardized way to avoid issues with crediting the original button author(s) to avoid issues with button authors' consent to including buttons on other pages to facilitate automation around inclusion of buttons, including but not limited to: button updates with caching helping web site owners discover available buttons auto-selecting the most suitable button variant for theming and accessibility 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.

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 when, and only when, they appear in all capitals, as shown here.

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 webservers, 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. A GIF image with ten frames, all of which only contain imperceptible color differences in a few pixels, is not animated. An APNG image with two thousand identical frames is not animated. A GIF image with a single frame is not animated.

button.json Files The main element of this specification is the /.well-known/button.json file. This is a well-known URI registered with IANA; see . 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 , and MAY be served via HTTP. The file SHOULD be served using the Content-Type header set to application/json; charset=utf-8. The file MUST be valid JSON , and MUST be encoded using UTF-8 . 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 which defines the basic syntax rules is provided in . 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-00.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.

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.

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

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 string. Clients SHALL NOT assume IDs are unique across web sites.

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 using the https protocol name, and must subsequently be accessible using the HTTPS Internet protocol. Referenced image files SHOULD have 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 pixels and height of 31 pixels. Image files may be either static or animated; see for a detailed definition including edge-case examples. The following image file formats are RECOMMENDED in order of preference: AVIF : animated and static images WEBP : animated and static images PNG : static images GIF : animated and static images Button images MUST NOT be lossily compressed. Of the recommended image formats, AVIF and WEBP are capable of lossy compression and care must be taken to avoid it.

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

Optional Properties

link Buttons displayed on a webpage SHOULD be contained in a hyperlink element such as <a>, linking back to the button author's web page. The link property facilitates this. It is an OPTIONAL property containing a URI . The button's surrounding hyperlink element MUST point to the URI specified in the link property of the button, if available. Otherwise, it SHOULD point to the base path from where the /.well-known/button.json was fetched. For example, if a client fetches https://example.org/.well-known/button.json, and one of the contained buttons does not feature a link property, the client should embed this button in a hyperlink pointing to https://example.org/.

hotlink The OPTIONAL hotlink boolean flag specifies whether the button image should be hotlinked, i.e. included directly from the source uri instead of copying to and then hosting from the client's web server. Many authors prefer their images not to be hotlinked, as it creates additional load on the server. This is the default (false). However, some authors prefer their images to be hotlinked for a variety of reasons, such as serving dynamically generated buttons. These authors can set hotlink to true for the relevant buttons, in order to indicate to clients to hotlink the button. Clients SHOULD NOT hotlink button images without the hotlink property set to true. Servers MAY impose restrictions on clients which they suspect to be in violation of this requirement.

sha256 The sha256 property is OPTIONAL. It facilitates caching and validation of the image file. This property MUST contain the SHA256 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.

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, as well as conventional figure caption text.

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

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

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

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.

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 string. Clients SHALL NOT assume IDs are unique across web sites. The following properties, colorScheme, animations, and contrast, 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. 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.

colorScheme The OPTIONAL colorScheme property specifies what color scheme the button version uses. It is to be interpreted as per 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

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.

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

Examples A typical example is as follows:

A minimal example:

And an exhaustive example:

Implementation Considerations This section has not yet been written, and the authors appreciate any input for it.

IANA Considerations IANA will register the well-known URI /.well-known/button.json in the well-known URIs registry in conformance with the requirements for this registration in . The following information is provided to facilitate the registration: URI suffix: button.json Change controller: IETF Specification document(s): This RFC Status: permanent In case a JSON Schema registry is set up with IANA in the future, the button.json Schema, as defined in this specification and any of its updates and errata, shall be registered by IANA with this JSON Schema registry.

Legal Considerations Buttons are usually copyrightable artworks. As such, unauthorized copying and inclusion of a button is a legal offense in most jurisdictions. This specification does not supersede the legal frameworks for copyright, licenses and permissions, but it attempts to aid all involved parties in avoiding legal issues. Publication of a /.well-known/button.json file, as per this specification, implies a permission to download (copy) the linked-to buttons, and include them on other pages, provided that a button's link (as per this specification) is persisted. These are the minimal permissions required to make the data in /.well-known/button.json useful to third parties. This does not waive copyright and is not comparable to stronger copyleft licenses. It is also not as legally unambiguous as the license properties, so the use of these properties is strongly RECOMMENDED. The license and licenseText properties allow the button author to provide a copyright license. In case the author is not provided in either of those properties, it can be assumed to be the same as the author of the web site's content, or the web site's owner. It is RECOMMENDED that clients use SPDX tooling and human-in-the-loop verification of both license and licenseText to verify that the client's use of the button is allowed by the license. The following licenses are RECOMMENDED for use in /.well-known/button.json: Any of the current Creative Commons licenses, including CC BY, CC BY-SA, and CC BY-ND. The no-derivative licenses including the latter are closest to the default permissions implied with publication of a /.well-known/button.json file. A public domain license, such as or . A full list of standard licenses tracked by SPDX is available at https://spdx.org/licenses/.

Privacy Considerations 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 can be used to discourage scrapers from accessing /.well-known/button.json, 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.

Security Considerations

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.

Denial-of-Service Concerns Due To Hotlinking Hotlinking buttons imposes an additional load on the server, as it has to serve the button to every visitor of a client's web page, not just its own page(s). Therefore, usage of the "hotlink": true setting should be carefully evaluated, as even well-intentioned clients may cause increased load on the server if their pages receive many views. Malicious or careless clients may ignore the hotlink attribute and always hotlink the button image. This scenario is no different from ordinary HTTP Denial-of-Service attacks and should be addressed similarly.

This memo defines a path prefix for "well-known locations", "/.well-known/", in selected Uniform Resource Identifier (URI) schemes. In doing so, it obsoletes RFC 5785 and updates the URI schemes defined in RFC 7230 to reserve that space. It also updates RFC 7595 to track URI schemes that support well-known URIs in their registry. Federal Information Processing Standard, FIPS A Uniform Resource Identifier (URI) is a compact sequence of characters that identifies an abstract or physical resource. This specification defines the generic URI syntax and a process for resolving URI references that might be in relative form, along with guidelines and security considerations for the use of URIs on the Internet. The URI syntax defines a grammar that is a superset of all valid URIs, allowing an implementation to parse the common components of a URI reference without knowing the scheme-specific requirements of every possible identifier. This specification does not define a generative grammar for URIs; that task is performed by the individual specifications of each URI scheme. [STANDARDS-TRACK] The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This document removes inconsistencies with other specifications of JSON, repairs specification errors, and offers experience-based interoperability guidance. ISO/IEC 10646-1 defines a large character set called the Universal Character Set (UCS) which encompasses most of the world's writing systems. The originally proposed encodings of the UCS, however, were not compatible with many current applications and protocols, and this has led to the development of UTF-8, the object of this memo. UTF-8 has the characteristic of preserving the full US-ASCII range, providing compatibility with file systems, parsers and other software that rely on US-ASCII values but are transparent to other values. This memo obsoletes and replaces RFC 2279. JSON Schema World Wide Web Consortium The Linux Foundation Unicode, Inc. World Wide Web Consortium World Wide Web Consortium Internet Assigned Numbers Authority In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This document specifies and extends the "Robots Exclusion Protocol" method originally defined by Martijn Koster in 1994 for service owners to control how content served by their services may be accessed, if at all, by automatic clients known as crawlers. Specifically, it adds definition language for the protocol, instructions for handling errors, and instructions for caching. Alliance for Open Media This document defines the WebP image format and registers a media type supporting its use. World Wide Web Consortium CompuServe Incorporated WHATWG Creative Commons Creative Commons

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

Migrating from earlier versions of this specification

Migrating from draft 2024-05 At a basic level, this can be done easily with jq:

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

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 . The authors thank in particular for the original ./well-known/button.json idea.

Contributors

https://arch.dog

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

Reina contributed the idea of an alt text property.

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

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

FR soblowdragon@gmail.com https://xaselgio.net

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

https://natty.sh

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