Introduction
A web app manifest is a JSON file that tells a browser how to present a web site as an application: its name, its icons, the
page to open on launch, whether to hide the browser’s own interface, the colours to use, and shortcuts to key tasks. The W3C’s
Web Application Manifest specification defines it (the draft read for this site is the Working
Draft of 18 November 2026). A page points to it with <link rel="manifest" href="manifest.webmanifest">.
The specification says the registered file extension is .webmanifest and the media type is application/manifest+json;
developers may also use .json with that media type, which is why manifest.json is also common.
Structure
The file is one JSON object. The specification describes how a user agent processes it, member by member, and the processing is
forgiving: a member of the wrong type, or with a value that is not allowed, is ignored and the default is used. The defaults of the members
that have one: dir is auto, display is browser, start_url is the document’s URL,
and scope is the start URL with its file name, query and fragment removed.
{
"name": "Super Racer 3000",
"short_name": "Racer3K",
"start_url": "/racer/start.html",
"scope": "/racer/",
"display": "fullscreen",
"orientation": "landscape",
"theme_color": "red",
"background_color": "#fff",
"icons": [
{ "src": "icon/lowres.webp", "sizes": "64x64", "type": "image/webp" },
{ "src": "icon/hd_hi.png", "sizes": "128x128" }
],
"shortcuts": [
{ "name": "Play Later", "url": "/play-later" }
]
}
The members page lists every member, the image resources of icons and the shortcut items.
In the explorer
A file with the extension .webmanifest always opens here. A file named manifest.json opens here only when its content passes
a strict test: a JSON object with at least one member that only web app manifests have (start_url, display,
icons, theme_color, background_color, scope, short_name, orientation,
shortcuts or display_override), no manifest_version or dependencies (a browser extension or a
package manifest), and the right types for the members it knows. Every other manifest.json opens as it did before (a browser extension
manifest in its own viewer, the rest as JSON). The content test reads the first 4 MiB; a manifest.json larger than that is claimed by its name
when it starts with { (the viewer reads any size, lazily), without the strict test.
The tree names each member and says what the draft says it is; the tabs list the icons and the shortcuts, every JSON value, and the problems.
A problem is worded as what the user agent does (“ignores it and uses its default”), because that is what the specification describes. Members that
the draft does not define (description, categories, screenshots, display_override,
related_applications and others that real manifests carry) are labelled as not in the draft read, and are not called errors.
JSON syntax errors and repeated member names are reported as in the JSON viewer. Nothing is refused or fetched.
What the viewer applies from the draft (read as text, our words in the messages): a top level that is not an object is an empty manifest (1.17.1);
{} is a valid manifest, because every member is optional; a shortcut item is skipped when its name is missing, not a string or empty, when its
url is missing, not a string or does not parse, or when the url is outside the scope (3.7); an image resource fails as a whole, and the icon is skipped, when
src is not a string, when a sizes string does not parse or when a type string is not a MIME type (Image Resource, “processing an image
resource from JSON”), while an empty src string parses and a sizes or type that is not a string is only left out. The Icons and
Shortcuts tabs have a Result column (“used” or “skipped: why”); the Overview counts the icons of icons only and gives the icons of shortcut items on a row of their
own. The Problems tab numbers its rows from 1, like the other tables.
Not described
Known, not yet covered
- Reference: the members defined by other specifications and by browser vendors (
description,categories,screenshots,display_override,share_target,protocol_handlers,file_handlers,related_applications,launch_handlerand others) are named and labelled only: their rules are not described. - Reference: the life-cycle sections of the draft (installing, launching, updating, security-sensitive members) are not described.
- Viewer: colour values are checked for the shape of a CSS colour (
#rgb,#rgba,#rrggbb,#rrggbbaa, the 148 named colours,transparent, and the functional notations with the right number of components), not against the whole CSS Color grammar: values insidecalc()or nested functions are accepted by shape. Language tags are checked for the shape of BCP 47 / RFC 5646 (any subtag length the grammar allows, extensions, private use, the irregular tags), not against the IANA subtag registry.sizesis checked for shape (anyorWxHseparated by spaces); the HTML rule for the sizes attribute was not read, so a value such as0x0passes. These tests are our words, written from the grammars’ descriptions, not from the grammars’ text. - Viewer: the “start URL within scope” rule and the “shortcut url within scope” rule (3.7) are judged only when both values are absolute URLs or both start with
/: a file does not say where it was fetched from, so a relativeurlsuch asplay(which depends on the manifest URL) is not judged. The default scope is taken as the start URL without its last path segment (inferred from 1.6). - Viewer: image files are not fetched, so the real size and type of an icon are not compared with its
sizesandtype. - Viewer: a
manifest.jsonof more than 4 MiB is claimed by its name when it starts with{, without the strict content test, so a very large browser-extension manifest opens here too (the strict test, which keeps extension manifests out, reads only the first 4 MiB). - Viewer: the
*_localizedmembers and the text members’ processing (the “process a text member” algorithm) are labelled but not checked. - Viewer: a manifest that has members but neither
namenorshort_nameis still listed as a problem, as advice (the draft makes every member optional; installation uses the names, section 4.1);{}is not.
Unknown
- Viewer: the exact HTML rule for the
sizesattribute of a link element (for example whether0x0or a leading zero is valid): that text was not read.
Links
Reference
- Web Application Manifest – the W3C specification
- Image Resource – the specification of the image objects that icons use
- MDN: Web app manifest – a reference with browser support