---
title: "Package Integrity — verifiable digests in a version · semver.xyz"
description: "Package Integrity is a Semantic Versions extension that carries a content-addressable digest inside a source-qualified version, e.g. npm:react@18.2.0+sha512.<value>."
url: "https://semver.xyz/extensions/integrity/"
lang: "en"
---

Extension · Package Integrity

# Pin software to its exact bytes.

_Package Integrity_ carries a content-addressable digest **inside** a source-qualified version. Because Semantic Versions restores build precedence, an integrity-bearing build is a real, orderable version — not an inert annotation.

integrity specifier

```
npm:react@18.2.0+sha512.d0a1e5c3…9f2b
```

`npm:react@18.2.0` is the package you already install. `+sha512.…` is the only new part, a build-metadata-safe transcoding of the artifact's hash.

[Compute an integrity](https://www.semver.xyz/extensions/integrity#compute) [Read the format](https://www.semver.xyz/extensions/integrity#format)

Why build metadata

## SRI can't live in a version. This can.

[Subresource Integrity](https://www.w3.org/TR/SRI/) strings look like `sha512-<base64>`. They can't sit in a version because Base64 uses `+`, `/` and `=`, none of which are valid build-metadata characters (`[0-9A-Za-z-]`). Package Integrity defines a lossless, grammar-safe transcoding (canonical **hex**, or compact **Base62**) so the digest travels inside the version string itself.

Live

## Compute a source-qualified integrity.

Pull a package's published integrity from any npm-compatible registry and transcode it into a Package Integrity specifier, then optionally re-download the artifact and verify the bytes in your browser with the Web Crypto API.

Contents

[Format](https://www.semver.xyz/extensions/integrity#f-format) [Precedence](https://www.semver.xyz/extensions/integrity#f-precedence) [Verification](https://www.semver.xyz/extensions/integrity#f-verify) [vs. Dependency Locks](https://www.semver.xyz/extensions/integrity#f-locks) [Grammar](https://www.semver.xyz/extensions/integrity#f-grammar)

## Format

A Package Integrity build is one or more integrity digests appended as build metadata:

`<version>+<algorithm>.<digest> ( .<algorithm>.<digest> )*`

- `<algorithm>`: one of `sha256`, `sha384`, `sha512`. The set is extensible; consumers **MUST** ignore digests whose algorithm they don't recognise and **MUST NOT** treat that as a failure by itself.
- `<digest>`: the raw hash encoded as lowercase **hex** (canonical, `[0-9a-f]+`) or compact **Base62** (`[0-9A-Za-z]+`). Both are valid build identifiers.
- Algorithm and digest are two dot-separated build identifiers, so the pair tokenises trivially.
- Multiple digests **MAY** be present and **SHOULD** be ordered weakest-to-strongest.

Canonical hex lengths: `sha256` → 64, `sha384` → 96, `sha512` → 128 characters.

## Precedence

Package Integrity relies on Semantic Versions [precedence](https://www.semver.xyz/spec.md#precedence): build identifiers are compared, so a digest-bearing version is ordered and distinguishable rather than collapsed away. Integrity is **advisory to precedence** but **authoritative to trust**: the digest doesn't change what a version means, but a mismatch **MUST** cause the artifact to be rejected.

## Verification

1. Resolve `name@version` from the named source (`npm:` → the registry).
2. Obtain the artifact (for npm, the version's tarball).
3. Compute the digest of the artifact bytes with `<algorithm>`.
4. Transcode and compare to `<digest>`. It satisfies the identity iff every listed algorithm the consumer supports matches, and at least one supported algorithm was present.
5. A mismatch **MUST** be a fatal integrity error.

The transcoding is lossless: npm's `sha512-<base64>` is the same bytes as `sha512.<hex>` here.

## vs. Dependency Locks

Package Integrity is the single-artifact, inline form for one identity, and it is the second of the three extensions: it takes the artifact a [Build Variant](https://www.semver.xyz/extensions/variants.md) names and pins its exact bytes (`1.0.0+linux.x64.musl.sha512.…`). [Dependency Locks](https://www.semver.xyz/extensions/dependency-locks.md) then build on both — a lock pins an entire resolved subgraph in which _each node_ is written in exactly this form, so the digest notation you learn here is the notation a decoded lock uses. Reach for an inline digest where a full lock is unnecessary.

## Grammar (BNF)

Building on [VERSION.bnf](https://www.semver.xyz/spec/VERSION.bnf)'s `<build>`:

[Download INTEGRITY.bnf](https://www.semver.xyz/spec/INTEGRITY.bnf)

```
Copy<integrity build> ::= <integrity> ( "." <integrity> )*
<integrity>       ::= <algorithm> "." <digest>
<algorithm>       ::= "sha256" | "sha384" | "sha512"
<digest>          ::= <hex digest> | <base62 digest>
<hex digest>      ::= <hex> <hex>+
<base62 digest>   ::= <base62 char> <base62 char>+
<hex>             ::= "0" … "9" | "a" … "f"
<base62 char>     ::= "0" … "9" | "A" … "Z" | "a" … "z"
```
