npm · Schema
npm Package Document
A full npm package document (packument) representing all metadata for a package in the npm registry, including every published version, distribution tags, maintainers, and repository information.
PackagesJavaScriptNode.jsPackage ManagementRegistrySecurity
Properties
| Name | Type | Description |
|---|---|---|
| _id | string | The package name, used as the CouchDB document identifier. |
| _rev | string | The CouchDB document revision identifier. |
| name | string | The name of the package. Must follow npm naming rules: lowercase, no spaces, may contain hyphens and dots. |
| description | string | A short description of the package, used in search results. |
| dist-tags | object | A mapping of distribution tag names to version strings. The 'latest' tag is always present and points to the most recently published non-prerelease version. |
| versions | object | A mapping of semver version strings to version-specific metadata objects. |
| time | object | A mapping of version strings to ISO 8601 timestamps indicating when each version was published. Includes special keys 'created' and 'modified'. |
| maintainers | array | List of current package maintainers with publish access. |
| author | object | |
| repository | object | |
| readme | string | The README content for the package, typically from the latest version. |
| readmeFilename | string | The filename of the README file. |
| homepage | string | The URL of the package homepage. |
| keywords | array | Keywords associated with the package for search discovery. |
| bugs | object | Issue tracker information for reporting bugs. |
| license | string | The SPDX license identifier for the package. |
| users | object | A mapping of npm usernames to boolean values indicating users who have starred this package. |
JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://npmjs.com/schemas/npm/package.json",
"title": "npm Package Document",
"description": "A full npm package document (packument) representing all metadata for a package in the npm registry, including every published version, distribution tags, maintainers, and repository information.",
"type": "object",
"required": ["name", "dist-tags", "versions"],
"properties": {
"_id": {
"type": "string",
"description": "The package name, used as the CouchDB document identifier."
},
"_rev": {
"type": "string",
"description": "The CouchDB document revision identifier."
},
"name": {
"type": "string",
"description": "The name of the package. Must follow npm naming rules: lowercase, no spaces, may contain hyphens and dots.",
"pattern": "^(@[a-z0-9-~][a-z0-9-._~]*/)?[a-z0-9-~][a-z0-9-._~]*$",
"maxLength": 214
},
"description": {
"type": "string",
"description": "A short description of the package, used in search results."
},
"dist-tags": {
"type": "object",
"description": "A mapping of distribution tag names to version strings. The 'latest' tag is always present and points to the most recently published non-prerelease version.",
"required": ["latest"],
"properties": {
"latest": {
"type": "string",
"description": "The latest stable version of the package."
}
},
"additionalProperties": {
"type": "string"
}
},
"versions": {
"type": "object",
"description": "A mapping of semver version strings to version-specific metadata objects.",
"additionalProperties": {
"$ref": "#/$defs/PackageVersion"
}
},
"time": {
"type": "object",
"description": "A mapping of version strings to ISO 8601 timestamps indicating when each version was published. Includes special keys 'created' and 'modified'.",
"properties": {
"created": {
"type": "string",
"format": "date-time",
"description": "When the package was first created in the registry."
},
"modified": {
"type": "string",
"format": "date-time",
"description": "When the package was last modified."
}
},
"additionalProperties": {
"type": "string",
"format": "date-time"
}
},
"maintainers": {
"type": "array",
"description": "List of current package maintainers with publish access.",
"items": {
"$ref": "#/$defs/Person"
}
},
"author": {
"$ref": "#/$defs/Person"
},
"repository": {
"$ref": "#/$defs/Repository"
},
"readme": {
"type": "string",
"description": "The README content for the package, typically from the latest version."
},
"readmeFilename": {
"type": "string",
"description": "The filename of the README file."
},
"homepage": {
"type": "string",
"format": "uri",
"description": "The URL of the package homepage."
},
"keywords": {
"type": "array",
"description": "Keywords associated with the package for search discovery.",
"items": {
"type": "string"
}
},
"bugs": {
"type": "object",
"description": "Issue tracker information for reporting bugs.",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "URL of the issue tracker."
},
"email": {
"type": "string",
"format": "email",
"description": "Email address for bug reports."
}
}
},
"license": {
"type": "string",
"description": "The SPDX license identifier for the package."
},
"users": {
"type": "object",
"description": "A mapping of npm usernames to boolean values indicating users who have starred this package.",
"additionalProperties": {
"type": "boolean"
}
}
},
"$defs": {
"PackageVersion": {
"type": "object",
"description": "Metadata for a specific published version of a package.",
"required": ["name", "version", "dist"],
"properties": {
"name": {
"type": "string",
"description": "The name of the package."
},
"version": {
"type": "string",
"description": "The semver version string.",
"pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+(-[a-zA-Z0-9.]+)?(\\+[a-zA-Z0-9.]+)?$"
},
"description": {
"type": "string",
"description": "A short description of the package."
},
"main": {
"type": "string",
"description": "The entry point module for the package."
},
"module": {
"type": "string",
"description": "The ES module entry point."
},
"types": {
"type": "string",
"description": "The TypeScript type declarations entry point."
},
"exports": {
"description": "Package exports map for conditional module resolution.",
"oneOf": [
{ "type": "string" },
{ "type": "object" }
]
},
"scripts": {
"type": "object",
"description": "A mapping of script names to shell commands.",
"additionalProperties": {
"type": "string"
}
},
"dependencies": {
"type": "object",
"description": "Runtime dependencies as a mapping of package names to semver ranges.",
"additionalProperties": {
"type": "string"
}
},
"devDependencies": {
"type": "object",
"description": "Development dependencies as a mapping of package names to semver ranges.",
"additionalProperties": {
"type": "string"
}
},
"peerDependencies": {
"type": "object",
"description": "Peer dependencies as a mapping of package names to semver ranges.",
"additionalProperties": {
"type": "string"
}
},
"optionalDependencies": {
"type": "object",
"description": "Optional dependencies as a mapping of package names to semver ranges.",
"additionalProperties": {
"type": "string"
}
},
"engines": {
"type": "object",
"description": "Runtime environment requirements as a mapping of engine names to semver ranges.",
"additionalProperties": {
"type": "string"
}
},
"bin": {
"description": "Executable files to install into PATH.",
"oneOf": [
{ "type": "string" },
{
"type": "object",
"additionalProperties": {
"type": "string"
}
}
]
},
"author": {
"$ref": "#/$defs/Person"
},
"maintainers": {
"type": "array",
"description": "List of maintainers for this version.",
"items": {
"$ref": "#/$defs/Person"
}
},
"contributors": {
"type": "array",
"description": "List of contributors.",
"items": {
"$ref": "#/$defs/Person"
}
},
"repository": {
"$ref": "#/$defs/Repository"
},
"license": {
"type": "string",
"description": "The SPDX license identifier."
},
"keywords": {
"type": "array",
"description": "Keywords associated with this version.",
"items": {
"type": "string"
}
},
"dist": {
"$ref": "#/$defs/Distribution"
},
"deprecated": {
"type": "string",
"description": "Deprecation message if this version is deprecated."
},
"_npmVersion": {
"type": "string",
"description": "The version of npm used to publish this package version."
},
"_nodeVersion": {
"type": "string",
"description": "The version of Node.js used to publish this package version."
},
"_npmUser": {
"$ref": "#/$defs/Person"
},
"_hasShrinkwrap": {
"type": "boolean",
"description": "Whether this version includes a shrinkwrap file."
}
}
},
"Person": {
"type": "object",
"description": "A person object representing a user, author, maintainer, or contributor.",
"properties": {
"name": {
"type": "string",
"description": "The display name of the person."
},
"email": {
"type": "string",
"format": "email",
"description": "The email address of the person."
},
"url": {
"type": "string",
"format": "uri",
"description": "The personal URL or website of the person."
}
}
},
"Repository": {
"type": "object",
"description": "Source code repository information.",
"properties": {
"type": {
"type": "string",
"description": "The version control system type, typically 'git'."
},
"url": {
"type": "string",
"description": "The URL of the source code repository."
},
"directory": {
"type": "string",
"description": "The directory within the repository where the package lives, for monorepos."
}
}
},
"Distribution": {
"type": "object",
"description": "Distribution metadata for a published version, including integrity hashes and tarball location.",
"required": ["shasum", "tarball"],
"properties": {
"shasum": {
"type": "string",
"description": "The SHA-1 checksum of the tarball.",
"pattern": "^[a-f0-9]{40}$"
},
"tarball": {
"type": "string",
"format": "uri",
"description": "The URL where the tarball can be downloaded."
},
"integrity": {
"type": "string",
"description": "The Subresource Integrity (SRI) hash of the tarball, typically using SHA-512.",
"pattern": "^sha512-"
},
"fileCount": {
"type": "integer",
"description": "The number of files in the tarball.",
"minimum": 1
},
"unpackedSize": {
"type": "integer",
"description": "The total unpacked size of the tarball in bytes.",
"minimum": 0
},
"npm-signature": {
"type": "string",
"description": "The npm registry signature for the package version."
},
"signatures": {
"type": "array",
"description": "Cryptographic signatures for the package version.",
"items": {
"type": "object",
"required": ["keyid", "sig"],
"properties": {
"keyid": {
"type": "string",
"description": "The identifier of the signing key."
},
"sig": {
"type": "string",
"description": "The signature value."
}
}
}
},
"attestations": {
"type": "object",
"description": "Sigstore provenance attestations for the package version.",
"properties": {
"url": {
"type": "string",
"format": "uri",
"description": "URL to fetch the full attestation bundle."
},
"provenance": {
"type": "object",
"description": "Provenance attestation summary.",
"properties": {
"predicateType": {
"type": "string",
"format": "uri",
"description": "The SLSA predicate type URI."
}
}
}
}
}
}
}
}
}