JSON Schema Definition
Relevant source files
The following files were used as context for generating this wiki page:
The JSON Schema Definition in the Numan Registry project provides a formal specification for the index.json file, which serves as the signed registry index for the Numan Nushell package manager. The schema ensures that all published package metadata, including versioning, artifacts, and security hashes, adheres to a consistent structure required by Numan clients for synchronization and verification.
This definition is primarily captured in schemas/index-v1.json and is enforced during the CI/CD process via validation scripts. It defines the structure for four package types: plugins, modules, scripts, and completions, while also facilitating trust root management through successor key declarations.
Sources: README.md:1-10, schemas/index-v1.json:1-10
Schema Structure and Hierarchy
The registry index is an object-oriented JSON structure with a mandatory top-level schema_version of 1. The root object contains metadata about the update cycle and an array of package definitions.
Root Object Fields
| Field | Type | Required | Description |
|---|---|---|---|
schema_version | integer | Yes | Must be 1. |
updated_at | string | Yes | ISO 8601 timestamp of the last update. |
registry_revision | string | No | Opaque revision identifier. |
trust | object | No | Successor key declarations for rotation. |
packages | array | Yes | List of package objects. |
Sources: schemas/index-v1.json:6-30
The following diagram illustrates the high-level hierarchy of the Numan Registry Index:
The schema organizes data from general registry metadata down to specific versioned binary artifacts.
Sources: schemas/index-v1.json:7-130
Package Data Model
Each entry in the packages array represents a unique tool or library. The schema enforces strict typing for package IDs and metadata.
Package Identification
A package is uniquely identified by an id object consisting of an owner and a name.
- Owner: A non-empty string representing the maintainer.
- Name: A non-empty string representing the package name.
Sources: schemas/index-v1.json:52-64
Package Types
The schema supports four specific package types through an enumeration:
plugin: Executable Nushell extensions.module: Nushell code modules.script: Individual Nushell scripts.completion: Custom completions for Nushell.
Sources: schemas/index-v1.json:67-70, registry/index.html:430-440
Versioning and Artifacts
The versions array within a package contains the history of releases. Each version object details how to retrieve and verify the package content.
Version Constraints
version: The specific version string (e.g., "0.26.0").nu_version: A constraint string defining compatible Nushell versions.verified_with: An array of exactMAJOR.MINOR.PATCHstrings representing Nushell versions where the package has been proven.
Sources: schemas/index-v1.json:77-94, README.md:126-135
Artifact Definition
The artifact object defines the distribution format and integrity checks.
| Field | Type | Description |
|---|---|---|
kind | string | One of: binary, archive, source. |
url | string (URI) | Direct download link for the artifact. |
sha256 | string | 64-character hex SHA-256 digest. |
targets | object | Mapping of platform triples to specific URLs and hashes (for binaries). |
entry | string | The entry point file within an archive (e.g., mod.nu). |
Sources: schemas/index-v1.json:95-120, scripts/gen_candidate.py:90-115
Binary Target Mapping
For binary artifacts, the targets object uses platform triples (e.g., x86_64-pc-windows-msvc) as keys. Each target must specify a url, sha256, and executable_path.
The target system allows a single version entry to support multiple operating systems and architectures.
Sources: schemas/index-v1.json:104-114, scripts/gen_candidate.py:30-45
Trust and Security
The schema includes a trust object used for key management and rotation. This allows the registry to declare new public keys within a signed index.
Key Rotation Schema
The trust.keys array contains:
key_id: A unique identifier for the key (e.g.,official-2026-07-01).public_key_b64: The Base64 encoded Ed25519 public key.
Sources: schemas/index-v1.json:30-50, README.md:104-110
Integrity Requirements
The schema enforces specific regex patterns for security-critical fields:
- SHA-256:
^[a-fA-F0-9]{64}$ - SemVer (verified_with):
^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)$
Sources: schemas/index-v1.json:92-93, schemas/index-v1.json:102
Lifecycle and Validation Flow
The JSON schema is utilized throughout the package intake and publication lifecycle.
The schema acts as the source of truth for all tools in the chain, ensuring that data generated by Python scripts matches the expectations of the Rust-based Numan client.
Sources: scripts/validate_candidate.py:15-30, AGENTS.md:20-30
Implementation Example
The following snippet demonstrates a schema-compliant version entry for a binary plugin, illustrating the relationship between nu_version, verified_with, and platform targets.
{
"version": "0.26.0",
"nu_version": ">=0.114.0 <0.115.0",
"verified_with": ["0.114.1"],
"artifact": {
"kind": "binary",
"targets": {
"x86_64-pc-windows-msvc": {
"url": "https://example.com/plugin.zip",
"sha256": "2f672c467e21c40769ca451b6d2ec9f18f0b388a92dd4361803cadf773acfd0b",
"executable_path": "plugin.exe"
}
}
}
}
Sources: registry/index.json:195-218, schemas/index-v1.json:77-125
The JSON Schema Definition provides a robust foundation for the Numan Registry, balancing flexible package types (plugins, modules, scripts) with strict security requirements (Ed25519 signatures, SHA-256 digests). By centralizing these rules in schemas/index-v1.json, the project maintains compatibility between the Python-based maintainer toolchain and the production Rust-based Nushell client.