{"id":51947832,"url":"https://github.com/bitwarden/map-the-web","last_synced_at":"2026-07-29T02:01:34.382Z","repository":{"id":362152478,"uuid":"1190857137","full_name":"bitwarden/map-the-web","owner":"bitwarden","description":"Map the Web offers curated guidance for interacting with websites lacking rich semantics or fully-adopted standards.","archived":false,"fork":false,"pushed_at":"2026-07-22T18:04:11.000Z","size":338,"stargazers_count":7,"open_issues_count":2,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-07-25T10:13:36.710Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bitwarden.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-24T17:27:08.000Z","updated_at":"2026-07-22T21:24:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bitwarden/map-the-web","commit_stats":null,"previous_names":["bitwarden/map-the-web"],"tags_count":15,"template":false,"template_full_name":"bitwarden/template","purl":"pkg:github/bitwarden/map-the-web","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitwarden%2Fmap-the-web","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitwarden%2Fmap-the-web/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitwarden%2Fmap-the-web/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitwarden%2Fmap-the-web/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bitwarden","download_url":"https://codeload.github.com/bitwarden/map-the-web/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bitwarden%2Fmap-the-web/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36013746,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-29T02:00:04.910Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-29T02:01:33.691Z","updated_at":"2026-07-29T02:01:34.369Z","avatar_url":"https://github.com/bitwarden.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Let's Map the Web!\n\nMap the Web offers curated guidance for interacting with websites lacking rich\nsemantics or fully-adopted standards.\n\n\u003e [!IMPORTANT]\n\u003e This project is in a non-stable, experimental state.\n\u003e\n\u003e Schemas, data shapes,\n\u003e release cadence, and tag conventions may change without notice and without\n\u003e backwards-compatibility guarantees. Individual Maps may be added, restructured,\n\u003e or removed between releases. Consumers should be prepared for breaking changes.\n\u003e See [Versioning](#versioning) for the current scheme.\n\n- [Let's Map the Web!](#lets-map-the-web)\n  - [Goals and Intent](#goals-and-intent)\n    - [Mapping Philosophies](#mapping-philosophies)\n  - [Limitations](#limitations)\n  - [Using Maps](#using-maps)\n    - [Versioning](#versioning)\n      - [Schema Versions](#schema-versions)\n      - [Release Tags](#release-tags)\n      - [Prerelease Maps](#prerelease-maps)\n      - [Backwards Compatibility](#backwards-compatibility)\n    - [Releases](#releases)\n  - [Authoring Maps](#authoring-maps)\n    - [Major Version Bumps](#major-version-bumps)\n  - [Glossary](#glossary)\n\n## Goals and Intent\n\nMap the Web offers guidance on website content via a collection of living\nwebsite \"Maps\". These Maps describe various categorical concerns of real\nwebsites. While semantics, standards, and specifications can help software\ndevelopers navigate data concerns on the web, such conventions are sometimes\nincomplete, not widely implemented, or even leave a particular concern\ncompletely unaddressed. The primary goal of this project is to map out live\nwebsites that lack the implementation details that would otherwise enable\nsoftware to interact with them as intended.\n\n### Mapping Philosophies\n\nWith the aforementioned goals and intent in mind, Maps should:\n\n- only describe a website or website page, not how a particular consumer of Maps\n  should behave\n- only describe websites where a given concern is not otherwise accessible\n- only capture shared web concerns; local network configurations are out of\n  scope\n- be as specific as possible while avoiding unrelated concerns\n- be removed from a given Map if a site becomes navigable by other standard\n  means for those concerns\n- avoid staleness and be kept up-to-date\n\nBecause this project strives to deliver accountable curated guidance, the above\nconcerns must ultimately and necessarily be vetted/validated by humans.\n\nMaps are not intended to replace standard functionalities of the web, only to\nserve as a stopgap pending broader consensus and adoption of accepted standards.\n\n## Limitations\n\nWhile this project aspires to map all discovered gaps of the web, this is\nlargely expected to be unachievable, given the size and ever-changing nature of\nthe web. Consequently Maps should not be consumed as an absolute guarantee;\nwebsites can and will change.\n\nMap-specific limitations can be found in their respective README documents.\n\n## Using Maps\n\nEach Map lives in its own subdirectory under `maps/`, named after its core\nconcern (e.g. `maps/forms/`). A Map directory contains the JSON data file\n(`forms.jsonc`), its versioned schema (e.g. `forms.v0.schema.json`), and a `README.md` documenting\nthe Map's structure and usage.\n\n### Versioning\n\nThis project has two distinct versioning schemes for independent concerns:\nschema versions and release tags.\n\n#### Schema Versions\n\nEach Map file includes a required top-level `schemaVersion` field that identifies\nwhich revision of its schema the file conforms to. Schema versions use\n[semantic versioning](https://semver.org/):\n\n- **Major**: Breaking changes to the data structure or semantics (e.g.\n  removing/renaming required properties, adding required properties)\n- **Minor**: Backwards-compatible additions (e.g. new optional properties, new\n  enum values)\n- **Patch**: Documentation or schema clarifications with no data-level impact\n\nConsumers who wish to validate their Map data should check the\n`schemaVersion` field before processing a Map and reject or warn on unrecognized\nmajor versions. Build filenames include the\nschema major version (e.g. `forms.v1.json`), so a breaking schema change can\nship alongside the previous version (`forms.v1.json` and `forms.v2.json` in the\nsame release), allowing legacy consumers to continue fetching the version they\nsupport.\n\nThe major/minor/patch rules above apply once a Map has reached a stable major\nversion (`1.0.0` or later). Maps still under initial development use a separate\nprerelease scheme; see [Prerelease Maps](#prerelease-maps).\n\nMap-specific versioning guidance can be found in their respective README\ndocuments.\n\n#### Release Tags\n\nRelease tags use a date-based format: `v\u003cYYYYMMDD\u003e.\u003crun\u003e` (e.g. `v20260324.1`).\nThe date indicates when the build was produced; the run number disambiguates\nmultiple releases on the same day. Release tags reflect changes to Map _data_\n(new or updated host entries) and are independent of schema versions.\n\n#### Prerelease Maps\n\nA Map is considered **prerelease** when its `schemaVersion` major component is\n`0` (e.g. `0.1.0`, `0.7.2`). This follows the [semantic versioning](https://semver.org/#spec-item-4)\nconvention that `0.y.z` versions are reserved for initial development, where\n\"anything MAY change at any time\" and \"the public API SHOULD NOT be considered\nstable\".\n\nPrerelease Maps carry no compatibility, stability, or longevity promises:\n\n- The schema, key sets, value semantics, and overall structure may change in\n  any way between releases. The major/minor/patch bump rules described in\n  [Schema Versions](#schema-versions) do not apply within `0.y.z`; version\n  bumps are at the Map author's discretion.\n- A prerelease Map may be removed from a release entirely without prior\n  deprecation, notice, or transition period.\n- The [Backwards Compatibility](#backwards-compatibility) commitment does not\n  apply to prerelease Maps.\n- Consumers should treat each release as effectively independent and re-verify\n  their integration when updating.\n\nBuild filenames follow the same major-version convention as stable Maps. A Map\nat `schemaVersion: \"0.3.0\"` builds to `\u003cmap name\u003e.v0.json` and ships alongside\nits schema as `\u003cmap name\u003e.v0.schema.json`.\n\nWhen a prerelease Map reaches stability, its `schemaVersion` bumps to `1.0.0`\nand subsequent releases produce `\u003cmap name\u003e.v1.json`. The corresponding\n`\u003cmap name\u003e.v0.json` artifacts may continue to ship for a transition window or\nmay be dropped from the very next release; consumers must not rely on `v0`\nartifacts remaining available once a `v1` exists.\n\n#### Backwards Compatibility\n\nFor Maps at a stable major version (`1.0.0` or later), this project commits\nto supporting the schema **one major version back** from the current major\nversion for a **minimum of six months** after the current major version first\nreleases. During this window, each release contains both\n`\u003cmap name\u003e.v\u003cN\u003e.json` and `\u003cmap name\u003e.v\u003cN-1\u003e.json` artifacts (and their\ncorresponding schemas), so consumers can upgrade on their own timeline.\n\nAfter the six-month window, support for `v\u003cN-1\u003e` may be extended or dropped\nfrom subsequent releases without warning. Consumers depending on `v\u003cN-1\u003e`\nshould plan to upgrade within that window, or pin to a specific release tag\nthat still includes the artifact.\n\nA stable Map's schema may be marked **deprecated** at any time to signal\nthat it has entered its end-of-life support window. Deprecation is authored\nby setting the standard\n[JSON Schema 2020-12 `\"deprecated\"`](https://json-schema.org/draft/2020-12/json-schema-validation#name-deprecated)\nkeyword at the root of the schema file; the release manifest mirrors this\nwith `\"deprecated\": true` on the matching version entry. The flag does not\nindicate how long the support window will be, nor does it imply that a\nnewer major necessarily exists; it tells consumers to expect the schema to\nbe removed in a future release once the window closes. Consumers are\nencouraged to read the manifest and surface a warning to their maintainers\nprompting a migration; consumers that run a JSON Schema validator that\nsurfaces annotations against the shipped schema will also see the\ndeprecation.\n\nThis commitment does not apply to [Prerelease Maps](#prerelease-maps),\nwhich are dropped in their entirety upon graduation to a stable major.\n\n### Releases\n\nMap data is published as optimized builds via\n[GitHub Releases](https://github.com/bitwarden/map-the-web/releases). Each\nrelease contains minified Map JSON files, their schemas, a build manifest, and\nSHA-256 checksums.\n\n```text\nLatest build (always points to the newest release):\nhttps://\u003cproject URL\u003e/releases/latest/download/\u003cmap name\u003e.v\u003cN\u003e.json\n\nPinned build (locked to a specific release tag):\nhttps://\u003cproject URL\u003e/releases/download/\u003ctag\u003e/\u003cmap name\u003e.v\u003cN\u003e.json\n```\n\n`\u003cN\u003e` is the schema major version (e.g. `0` for prerelease Maps, `1` for the\nfirst stable major).\n\nExample: \u003chttps://github.com/bitwarden/map-the-web/releases/latest/download/forms.v0.json\u003e\n\nEach release includes a `manifest.json` with build metadata (timestamp, git SHA,\nand per-map schema versions) that consumers can use to check staleness or verify\ncompatibility. A `manifest.schema.json` is shipped alongside so consumers can\nvalidate the manifest's shape against the same contract the build enforces.\n\nEach release also includes the corresponding schema file for each Map (e.g.\n`forms.v0.schema.json` alongside `forms.v0.json`). Consumers that validate Map\ndata should validate against the schema included in the same release, as minor\nversion bumps may introduce new fields or values that would not pass validation\nagainst a stale schema copy. Consumers that do not validate should be prepared\nto gracefully handle unrecognized fields or values introduced by minor or patch\nschema changes.\n\n## Authoring Maps\n\nProject-wide mapping principles are described under\n[Mapping Philosophies](#mapping-philosophies). Map-specific authoring\nguidance (e.g. how to choose selectors for the Forms Map) lives in each\nMap's own `README.md`. This section captures cross-Map authoring workflows\nthat affect the project's build and release contract.\n\n### Major Version Bumps\n\nWhen a Map's schema needs a breaking change (see [Schema Versions](#schema-versions)\nand the Map's own README for what qualifies as breaking for that Map), the\nmaintainer ships the new major alongside the previous one by following these\nsteps:\n\n1. **Create the new schema file.** Copy\n   `maps/\u003cname\u003e/\u003cname\u003e.v\u003cN\u003e.schema.json` to `\u003cname\u003e.v\u003cN+1\u003e.schema.json`. In\n   the new file:\n   - Update `$id` so its last path segment is the new filename.\n   - Update `properties.schemaVersion.const` to the new version (e.g. `\"2.0.0\"`).\n   - Update `title` and `description` if they embed version-specific language.\n2. **Apply the breaking changes** in the new schema only. The old schema\n   continues to ship unchanged so existing consumers aren't broken.\n3. **Update the source data file** (`maps/\u003cname\u003e/\u003cname\u003e.jsonc`) to set\n   `schemaVersion` to the new value and adjust the data shape to satisfy the\n   new schema.\n4. **Register a downward migration** in\n   [`scripts/build.mts`](scripts/build.mts). Add an entry under\n   `MIGRATIONS[\"\u003cname\u003e\"]` keyed by the previous major (`N`); the function\n   projects new-source-shape data into old-schema-shape data.\n5. **Mark the previous schema deprecated** by adding `\"deprecated\": true` at\n   the root of `\u003cname\u003e.v\u003cN\u003e.schema.json`. The flag flows through to the\n   release manifest and the auto-generated release-notes \"Deprecations\"\n   section. See [Backwards Compatibility](#backwards-compatibility) for the\n   support semantics.\n6. **Update the Map's own README** if the schema introduces or changes\n   fields, key sets, categories, or other documented behavior.\n7. **Verify with `npm run check \u0026\u0026 npm run build`.** A green build emits\n   both `\u003cname\u003e.v\u003cN\u003e.json` and `\u003cname\u003e.v\u003cN+1\u003e.json` (with their schemas)\n   and records `\"deprecated\": true` against the older entry in\n   `dist/manifest.json`.\n\nThe build enforces these author invariants:\n\n- The schema filename's major and `properties.schemaVersion.const` major must\n  agree.\n- The schema's `$id` must end with its filename.\n- The source's `schemaVersion` must match exactly one schema's `const`.\n- A migration must be registered for every target major below the source's.\n- A warning is emitted when a Map has more than one non-deprecated schema\n  (the typical healthy state is exactly one current schema; a draft schema\n  above source is the expected exception).\n\nPer-Map rules for what counts as a major change live in each Map's own\nREADME, since the criteria depend on the Map's shape and consumer\nexpectations.\n\n\u003e [!NOTE]\n\u003e Prerelease Maps (`v0`) don't follow this workflow; they are dropped in\n\u003e their entirety upon graduation to a stable `v1`. See\n\u003e [Prerelease Maps](#prerelease-maps).\n\n## Glossary\n\n- **Map**: A JSON structure describing a categorical concern of real websites.\n  Each Map focuses on a single concern (e.g. forms) and lives in a named\n  subdirectory under `maps/` alongside its documentation and schema.\n\n- **Consumer**: Any application or tool that reads and acts on a Map. The Map\n  describes what exists on a page; the consumer decides what to do with that\n  information.\n\n- **Author**: Any maintainer of source Maps that get built to release channels.\n\n- **Heuristic detection**: Automated inference of page element purposes based on\n  attributes, labels, or surrounding markup.\n\n- **Prerelease Map**: A Map whose `schemaVersion` major component is `0`. Its\n  shape, contents, and continued availability carry no compatibility or\n  longevity guarantees. See [Prerelease Maps](#prerelease-maps).\n\n- **Deprecated schema**: A Map schema major version that has entered its\n  end-of-life support window. Indicated by `\"deprecated\": true` at the\n  schema root and on the matching entry in the release manifest. Consumers\n  should plan migration before the schema is removed in a future release.\n  See [Backwards Compatibility](#backwards-compatibility).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitwarden%2Fmap-the-web","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbitwarden%2Fmap-the-web","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbitwarden%2Fmap-the-web/lists"}