Registry Index Structure
Relevant source files
The following files were used as context for generating this wiki page:
The Numan Registry Index is a curated, signed JSON document that serves as the central catalog for the Numan Nushell package manager. It contains metadata, version history, and cryptographic digests for various package types, including plugins, modules, scripts, and completions. The index is designed to be machine-readable by the Numan CLI while providing a human-facing landing page via GitHub Pages.
The structure is governed by a strict JSON schema (index-v1.json) and requires a detached Ed25519 signature to ensure the integrity of the published artifacts. Numan clients sync the index.json file and verify it against a trusted public key before performing any installations or activations.
Sources: README.md:3-10, schemas/index-v1.json:1-10
Core Data Schema
The registry index is an object requiring three primary top-level fields: schema_version, updated_at, and packages. The schema version is currently pinned to 1.
Top-Level Fields
| Field | Type | Description |
|---|---|---|
schema_version | integer | Must be 1. Defines the structural version of the index. |
updated_at | string (date-time) | ISO 8601 timestamp of the last index update. |
registry_revision | string | An opaque identifier for the registry revision (e.g., seed-2026-07-02). |
trust | object | Optional field for successor key declarations. |
packages | array | A list of package objects available in the registry. |
Sources: schemas/index-v1.json:7-25, registry/index.json:2-5
Trust and Key Management
The trust object allows the registry to declare successor keys. This facilitates key rotation by including new public keys within a signed index that is already trusted by the client.
The diagram shows the relationship between the top-level trust object and the individual key declarations used for rotation.
Sources: schemas/index-v1.json:26-47
Package Object Structure
Each entry in the packages array represents a unique software project identified by a combination of an owner and a name.
Package Metadata
Packages are categorized into four distinct types: plugin, module, script, and completion.
| Field | Type | Constraints | Description |
|---|---|---|---|
id | object | required | Contains owner and name strings. |
description | string | required | Human-readable summary of the package. |
repo | string (uri) | required | URL to the upstream source code repository. |
type | string | enum | One of: plugin, module, script, completion. |
tags | array | required | List of strings for categorization and search. |
versions | array | required | List of version-specific data objects. |
Sources: schemas/index-v1.json:49-76, registry/index.json:7-16
Version and Artifact Structure
The versions array contains the actual delivery data for a package. Each version entry includes Nushell compatibility constraints and artifact location data.
Version Fields
| Field | Type | Description |
|---|---|---|
version | string | The specific version string (e.g., 1.2.0). |
nu_version | string | A SemVer constraint string for compatible Nushell versions. |
verified_with | array | List of exact Nushell versions that have passed lifecycle-prove tests. |
artifact | object | Data describing how to download and verify the bytes. |
activation | object | Instructions for Numan to enable the package in the environment. |
source | object | Optional Git provenance data (rev, cargo_name). |
Sources: schemas/index-v1.json:80-160, registry/index.json:82-108
Artifact Variants
The registry supports different artifact kinds. The kind field determines how the CLI processes the download.
- Binary: Primarily for plugins. Includes a
targetsmap where keys are target triples (e.g.,x86_64-pc-windows-msvc) and values includeurl,sha256, andexecutable_path. - Archive: Used for modules and scripts. Provides a single
url,sha256, and an optionalentrypoint file. - Source: (Deferred) Intended for source builds, currently rejected by intake scripts to maintain hash-verifiability.
This flowchart illustrates the logic Numan uses to resolve an artifact based on its kind and the user's platform.
Sources: schemas/index-v1.json:104-135, scripts/add-package.py:127-160
Validation and Integrity
The index's integrity is maintained through a detached signature and strict canonicalization.
Signing Process
The registry/index.json.sig file is a JSON envelope containing the signature for the index.
- Key ID: Identifies the trust root (e.g.,
official-2026-07-01). - Algorithm: Currently uses
ed25519. - Signature: A base64-encoded Ed25519 signature over the canonical JSON bytes of
registry/index.json.
Sources: README.md:73-85, scripts/validate.py
Canonicalization and Parsing
To ensure signature stability, the JSON must be canonical (sorted keys, no whitespace). The project maintains a Rust-based parser check to ensure parity between the Python CI tooling and the Numan production binary.
Activation Logic
For packages requiring setup (modules and plugins), an activation block provides the necessary context.
- kind: The type of activation (e.g.,
nu-module). - import: For modules, determines if specific components or
allshould be imported.
Sources: schemas/index-v1.json:151-159, registry/index.json:62-65
Conclusion
The Registry Index Structure provides a robust framework for Nushell package management. By combining strict schema validation, platform-specific target mapping, and Ed25519 signatures, it ensures that Numan clients can safely discover and install verified software. The multi-version support and lifecycle evidence tracking allow for a stable ecosystem across varying Nushell releases.