MAP file format: source map keys and mappings

Source maps are standardised by Ecma International as ECMA-426, the Source Map Format Specification, which continues the earlier “Source Map Revision 3” proposal; the version number in every map is still 3. A source map is a JSON document. This page follows ECMA-426.

Keys

Key	Type	Required	Meaning
`version`	number	yes	Always the integer `3`; other values may cause the map to be rejected.
`file`	string	no	The name of the generated file. Whether it is a URL, a path or a base name is left to the generator.
`sourceRoot`	string	no	A prefix for every entry of `sources` (below).
`sources`	array	yes	The original files: each a string holding a (possibly relative) URL, or `null` when the source’s name is not known.
`sourcesContent`	array of string or `null`	no	The original source text, in the same order as `sources`; `null` entries are fetched by name instead.
`names`	array of strings	no	Symbol names that the mappings refer to by index.
`mappings`	string	yes	The encoded mapping data (below).
`ignoreList`	array of integers	no	Indexes into `sources` of third-party code (such as frameworks or bundler output) that debuggers may hide. Some browsers also read the older `x_google_ignoreList` when `ignoreList` is absent.

Readers must ignore keys they do not recognise. An index map has sections instead of sources and mappings.

Resolving sources

If sourceRoot is present, it is put in front of each non-null source, with a / between them unless it already ends with one.
The result is parsed as a URL relative to the source map’s own URL.
A null source has no URL; its text can only come from sourcesContent.

Mappings

mappings describes the generated file line by line. A semicolon (;) ends each generated line, and commas (,) separate the segments within a line. Each segment is a run of Base64 VLQ numbers and has 1, 4 or 5 fields:

Field	Meaning	Relative to
1	Column in the generated line, counting from 0.	The previous segment on the same line; the first segment of each line holds the value itself (the count restarts on every line).
2	Index into `sources`.	The previous value of this field anywhere in the map (not reset per line).
3	Line in the original source, counting from 0.	The previous value of this field (not reset).
4	Column in the original source, counting from 0.	The previous value of this field (not reset).
5	Index into `names`.	The previous value of this field (not reset).

Fields	Meaning
1	Generated code that comes from no original source.
4	Generated code mapped to a source position, without a name.
5	Mapped to a source position and a name.

Base64 VLQ

Each number is written with the Base64 alphabet of RFC 4648. Each character carries 6 bits:

Characters	Values
`A`–`Z`	0–25
`a`–`z`	26–51
`0`–`9`	52–61
`+`	62
`/`	63

Bit 5 (value 32) is the continuation bit: set on every character except the last of a number. So A–Z and a–f (0–31) end a number, and g–z, 0–9, + and / (32–63) continue it.
The low 5 bits of each character are data, least significant group first.
The lowest data bit of the first character is the sign: 1 means negative. The remaining bits are the magnitude.
Values must stay below 2³¹ in magnitude (2³² for unsigned fields); the sign bit counts towards the limit, the continuation bits do not.
The encoding of “negative zero” is not zero: the standard’s decoding algorithm gives −2³¹ for it.

Examples

Text	Characters	Bits	Value
`A`	0 = `000000`	data 00000: sign 0, magnitude 0	0
`C`	2 = `000010`	data 00010: sign 0, magnitude 1	1
`D`	3 = `000011`	data 00011: sign 1, magnitude 1	−1
`V`	21 = `010101`	data 10101: sign 1, magnitude 1010 = 10	−10
`iB`	34 = `100010` (continues, data 00010); 1 = `000001` (last, data 00001)	00001 00010 = 34: sign 0, magnitude 17	17

To encode n: take |n| × 2, plus 1 if n is negative; then write it 5 bits at a time, lowest first, adding 32 to every group but the last, and look each 6-bit value up in the alphabet.

Worked example

{
  "version": 3,
  "file": "app.js",
  "sources": ["src/app.ts"],
  "names": ["greet", "name"],
  "mappings": "AAAA,SAASA,MAAMC"
}

A map with one generated line holding three segments.

Segment	Decoded fields	Absolute values
`AAAA`	0, 0, 0, 0	Generated column 0 → `src/app.ts`, line 0, column 0.
`SAASA`	9, 0, 0, 9, 0 (`S` = 18, data 10010: sign 0, magnitude 9)	Generated column 9 → line 0, column 9, name `greet`.
`MAAMC`	6, 0, 0, 6, 1 (`M` = 12, data 01100: sign 0, magnitude 6)	Generated column 15 → line 0, column 15, name `name`.

Index maps

An index map joins several maps, for example when files are concatenated:

Key	Meaning
`version`	`3`.
`file`	Optional, as in an ordinary map.
`sections`	Required; its presence marks the map as an index map. An array of section objects.

Section key	Meaning
`offset`	An object with integer `line` and `column`: where in the generated file this section starts. Invalid values may be reported and are treated as 0.
`map`	A complete source map for the section. It inherits nothing from the index map.

Sections must be sorted by their start positions and must not overlap; readers may check only that the offsets are in order.

Linking generated code to its map

Method	Form
HTTP header	`SourceMap: url`. It takes precedence over a comment. The older `X-SourceMap` header is deprecated.
JavaScript comment	`//# sourceMappingURL=url`. Generators write only `//#`; readers also accept the older `//@`.
CSS comment	The same annotation inside a `/* … */` comment, CSS having no line comments.
WebAssembly	A custom section named `sourceMappingURL` holding the URL; at most one.

All methods used for one file must agree. A relative URL is resolved against the generated file’s URL, which a //# sourceURL= comment can set.

Sources

Ecma International, ECMA-426, Source Map Format Specification (1st edition; the current draft on tc39.es read 2026-11-12): the source map format and its keys, resolving sources, mappings, Base64 VLQ (with the examples iB and V), index maps, and linking generated code. RFC 4648 for the Base64 alphabet. The other VLQ examples and the decoded segments are worked by hand from those rules.

.MAP File Format – Keys and mappings