InstallSpec
Fields
This section documents version 6 of the schema (_v is the constant "6"). Each definition has its own table listing the field name, its JSON type, whether it is required, and what it means. Where a field only accepts a fixed set of values, the values are listed and explained under that field.
Object model
An install-spec says how to get a thing and how to verify it. It is a discriminated union on method: registry, vendor, observable or app-store. The two methods that fetch an artifact, registry and vendor, carry pins: the store’s vet list, keyed by platform, where each pin is one vetted artifact with its exact version, its digest and its artifact role. The companion install-ref names what is installed, as opposed to how to get it.
The schema states the shape. The selection rules and invariants quoted on this page are enforced by the arbiter, the one component that resolves a spec into an install.
| Definition | Purpose |
|---|---|
|
How to get and verify a thing; exactly one of the four methods. |
|
Install from an npm-protocol registry. |
|
Install a vendor-hosted artifact. |
|
Install by observing a store endpoint, a curated list. |
|
Install via a third-party native store. |
|
The store’s vet list, keyed by platform. |
|
One vetted artifact: version, digest and role. |
|
The artifact-role vocabulary: what the payload is to its consumer. |
|
A reference to an installed package. |
The definitions live under the schema id install-spec. The schema also publishes two standalone entry points, for validators that embed one schema per header:
$id (under https://root-interface.se/protocols/Definitions/) |
Resolves to |
|---|---|
|
|
|
|
Install families in the wild
A survey of the install families that exist in the wild. The vocabulary of method and artifact is drawn from it; the install types it yields are listed under Install types.
| Family | Examples | The essence |
|---|---|---|
Package registry |
npm/GitLab npm, PyPI, crates.io, NuGet |
versioned metadata + artifact pull; client resolves and unpacks |
Self-executing installer |
Windows setup.exe (NSIS/Inno/InstallShield), macOS .pkg, Java installers |
you download an executable and hand it control — it installs itself |
OS package |
deb/apt, rpm/dnf, MSI/MSIX, winget, Homebrew |
delegate to the platform’s package manager; system-managed, dependency-resolved |
Self-contained / portable |
plain zip/tarball, AppImage, macOS .app drag-install, static binaries |
extract/copy is the install; run in place, delete to uninstall — dvi’s own model |
Sandboxed universal |
Flatpak, Snap |
self-contained + runtime + sandbox, store-fed |
App store |
Apple/Microsoft/Google stores, Steam |
platform-mediated, licensing/DRM, no artifact in your hands |
Container image |
docker/OCI pull |
image is the artifact; install = pull, run = container |
Direct URL ("vendor") |
a bare download link, curl | sh scripts |
no registry, no metadata — fetch and act; the |
Source build |
git + make/cmake |
fetch source, build locally |
Web / no-install |
PWA, plain URL |
the product is an address; "install" is a bookmark/manifest at most |
install-spec
A discriminated union of install methods. Each method is a self-contained variant, discriminated by its required method constant, and an install-spec object must match exactly one of them.
| method | Variant | Source |
|---|---|---|
|
An npm-protocol registry. |
|
|
A vendor-hosted artifact. Each pin carries a bare |
|
|
A store endpoint, a curated list, polled for content rather than fetched as a package. |
|
|
A third-party native store that owns distribution and integrity. |
Install types
An install type is really two axes that most systems conflate: where the artifact comes from, the source, and what landing it takes, the mechanism. The schema keeps them apart: method is the source axis, and a pin’s artifact role is the mechanism axis. An install type is therefore the method value joined to the artifact value with a `, the compound collapsing to a single word wherever the second half carries no information, mirroring how the protocol vocabulary has both `ws` and `+ipsme+tcp+l4end.
The types a spec can express in version 6 are the registry and vendor rows with the three artifact roles, plus observable and app-store. The rows with no method or artifact today (registry+image, git+build, os-package as a source, web) are vocabulary only.
| Type | What it is | Real-world shape |
|---|---|---|
|
registry pull → extract → run in place |
today’s "registry" — dvi’s current flow |
|
registry pull → execute, it installs itself |
npm/GitLab-hosted setup.exe / .pkg |
|
registry pull → hand to the OS manager |
registry-served .msi / .deb |
|
OCI registry pull |
docker |
|
bare URL → extract/copy in place |
zip/tarball/AppImage download |
|
bare URL → execute, it installs itself |
the planned |
|
bare URL → OS manager |
.deb/.msi download link |
|
clone → build locally |
from-source |
|
subscribe to a store endpoint; nothing lands |
today’s "observable" (curated lists) — poll is the only mechanism it could mean |
|
the platform’s own repo + manager, as one act |
apt / winget / brew |
|
the store is both source and mechanism; you hold no artifact |
Apple/Microsoft/Google stores |
|
the product is an address; no install |
PWA / web product |
registry
Install from an npm-protocol registry. name and registry say how to fetch; pins, when the store has vetted the package, say how to verify, and each pin declares its artifact role. The envelope needs no statement: it is protocol-fixed, a tarball, and per-platform content is the tarball’s own os_<os> affair.
Without pins the install takes the publisher-channel path: resolve this platform’s dist-tag, take the newest build, and warn-and-proceed on integrity. With no pin there is nowhere to write a role, so the arbiter invariant holds structurally: an unpinned install is self-contained only. A role that executes or delegates the payload is only spellable on a vetted pin.
There is no auth entry: credentials never travel in a catalog.
| Field | Type | Required | Description |
|---|---|---|---|
|
string |
yes |
The constant |
|
string |
yes |
The product’s friendly, official name (the ProductsAndBundles |
|
string |
yes |
The registry to fetch from. |
|
string |
no |
Optional participant-identity override. Absent, the identity is |
|
no |
The store’s vet list. Each pin declares its |
vendor
Install a vendor-hosted artifact. Each pin carries the bare url to fetch, the sha2-384 to verify, and the required artifact role. Verification is fail-closed: a bare vendor URL has no registry integrity metadata, so trust is established on first use through the pinned digest.
vendor is the source discriminator; the role is declared per pin, never derived from the URL, because vendor naming is untrusted and a signed or CDN URL may carry no extension at all. Unlike registry, the role varies per platform: a win32 setup-exe pin and a darwin dmg pin can sit under one spec, self-exe there and self-contained here.
A self-exe installer places files and owns residency: there is no <root>/<pkg>/<version> layout, and presence and uninstall probe the OS’s own markers. Authenticode and codesign identity verification is planned, sourced from the developer identity.
| Field | Type | Required | Description |
|---|---|---|---|
|
string |
yes |
The constant |
|
string |
yes |
The product’s friendly, official name (the ProductsAndBundles |
|
string |
no |
Optional participant-identity override. Absent, the identity is |
|
yes |
The store’s vet list. Every vendor pin carries |
|
|
string |
no |
When the installed thing is started. One of:
|
observable
Install by observing a store endpoint, a curated list: poll the cxn-pt for content rather than fetching a package. observable is the source discriminator; there is no artifact, so there is no mechanic to state (polling is transport, not a mechanic). The spec is complete as { method, cxn-pt }: which list is the record’s own identity, and the cadence is store-driven. There is no digest, since lists are trustless curation: the product records that the refs resolve to are what verify.
| Field | Type | Required | Description |
|---|---|---|---|
|
string |
yes |
The constant |
|
any |
yes |
Opaque connection point, a string or an object, validated against |
app-store
Install via a third-party native store. The storefront owns distribution and integrity, so there is no registry, no pins and no digest. The spec is complete as { method, storefront, app_id }.
| Field | Type | Required | Description |
|---|---|---|---|
|
string |
yes |
The constant |
|
string |
yes |
Which native store owns this, as a lowercase slug; a per-store installer matches on it. The enum is the set of supported stores, so a new store means a new installer and a schema bump. One of:
|
|
string |
yes |
The storefront’s own product id, opaque outside that store’s installer: an Apple app or bundle id, a Steam appid, or an Epic catalog id. |
pins
The store’s vet list, keyed by platform. Keys are process.platform tags (win32, darwin, linux) plus the wildcard * for all platforms. The keys are open, not enumerated, and the ProductsAndBundles platforms facet is derived from them. Each value is that platform’s append-ordered list of pins, the tail being current. The object must have at least one key, and each list at least one pin.
| Key | Value | Meaning |
|---|---|---|
|
array of pin |
That platform’s pins, append-ordered: the tail is the current one. |
|
array of pin |
Pins that apply to all platforms. |
Selection, in the one arbiter:
-
The candidates are the union of
pins[<os>]andpins[*]. -
The highest version by semver wins. On a tie, an explicit os key beats
*. -
Registry install mode reads the chosen version’s suffix:
-universalinstalls the whole package (a flatbin/), anything else extractsos_<os>/bin. Vendor has no suffix mode; each pin declares its own role.
Invariants, which fail loud:
-
The same version across keys must share one
sha2-384. -
No duplicate version within a key.
-
No covering key (neither
<os>nor*) is a refusal, never a silent fallback.
pin
One vetted artifact, the complete vet atom: the exact version, the whole-file sha2-384, and the required artifact role. The role lives in the pin, always: one home for both methods. Where it happens not to vary (a registry package’s pins all saying the same thing) that is repetition plus tripwire, the same pattern as the same-version-same-digest invariant. The digest rides with the store’s record, not with the bytes' storage, so a compromised host cannot rewrite both.
url and format are vendor-only facts. They are arbiter invariants, not schema: a vendor pin must carry url (fail loud), and a registry pin carries neither, since its URL derives from the packument and its envelope is protocol-fixed, a tarball. The role-by-format action matrix, the refusals, and the declared-format versus verified-bytes cross-check (file magic, after the sha2-384 gate) are likewise the arbiter’s. Code-signing identity verification is deferred to the developer identity, not carried per pin.
| Field | Type | Required | Method | Description |
|---|---|---|---|---|
|
string |
yes |
both |
The exact version of the artifact. |
|
string |
yes |
both |
The whole-file digest, as |
|
yes |
both |
The role: what the payload is to its consumer. |
|
|
string |
no |
vendor only |
The bare fetch locator. Its naming and extension carry no semantics and are never interpreted (a signed or CDN URL may have no extension at all). Percent-encode at fetch. Not required by the schema, but the arbiter requires it on a vendor pin. |
|
string |
no |
vendor only |
Optional envelope declaration. An open string on purpose: the arbiter owns the vocabulary, so a new format is not a schema change. Present, the arbiter cross-checks it against the verified bytes' magic, a tripwire where store record and content disagreeing is a refusal. Absent, the arbiter reads the magic alone. Known values:
|
artifact
The artifact-role vocabulary: what the payload is to its consumer, never how it is packaged. Packaging is the envelope’s affair, declared by a pin’s format for vendor or fixed as a tarball for registry. A closed set: a new role (for example oci-image, for a vendor-hosted saved container image) enters together with the first artifact that needs it, not before.
| Value | The payload … | Install means |
|---|---|---|
|
is the app. |
Place it. |
|
installs the app. |
Execute it; it then owns residency. |
|
is a package for the platform’s package manager. |
Delegate to that manager. |
install-ref
A reference to an installed package. A spec says how to get it; a ref says what is there.
| Field | Type | Required | Description |
|---|---|---|---|
|
string |
yes |
The ProductsAndBundles |
|
string |
no |
An exact installed version. Absent, the ref means all installed versions of the name. |
Schema
{
"$id": "https://root-interface.se/protocols/Definitions/InstallSpec",
"$schema": "https://json-schema.org/draft/2019-09/schema",
"schemas": {
"https://root-interface.se/protocols/Definitions/install-spec": {
"$id": "https://root-interface.se/protocols/Definitions/install-spec",
"$schema": "https://json-schema.org/draft/2019-09/schema",
"definitions": {
"_v": {
"const": "6"
},
"artifact": {
"$comment": "the artifact-ROLE vocabulary: what the payload IS to its consumer, never how it is packaged (packaging is the envelope's affair -- the vendor url's extension, or registry's fixed tarball). `self-contained` = the payload IS the app (install = place it); `self-exe` = the payload installs the app (install = execute it, then it owns residency); `os-package` = the payload is a package for the platform's manager (install = delegate). Closed set; a new role (e.g. `oci-image` for a vendor-hosted saved container image) enters together with the first artifact that needs it, not before.",
"enum": [ "self-contained", "self-exe", "os-package" ]
},
"pin": {
"$comment": "one vetted artifact -- the complete vet atom: exact `version` + `sha2-384` (whole-file `shasum -a 384` hex) + the REQUIRED `artifact` role. The role lives in the pin, ALWAYS -- one home for both methods; where it happens not to vary (a registry package's pins all saying the same thing) that is repetition-plus-tripwire, the same pattern as the same-version-same-digest invariant. The digest rides with the store's record, not the bytes' storage, so a compromised host can't rewrite both. `url` and `format` are vendor-only facts -- ARBITER invariants, not schema: a vendor pin must carry `url` (fail loud); a registry pin carries neither (its url derives from the packument, its envelope is protocol-fixed -- a tarball). The role x format action matrix, the refusals, and the declared-format-vs-verified-bytes cross-check (file magic, after the sha2-384 gate) are likewise the arbiter's. Code-signing identity verification is deferred to the developer identity, not carried per-pin.",
"type": "object",
"required": [ "version", "sha2-384", "artifact" ],
"properties": {
"version": { "type": "string" },
"sha2-384": { "type": "string" },
"artifact": { "$ref": "#/definitions/artifact" },
"url": {
"$comment": "vendor only: the bare fetch locator -- its naming/extension carries NO semantics and is never interpreted (a signed/CDN url may have no extension at all); percent-encode at fetch.",
"type": "string"
},
"format": {
"$comment": "vendor only, optional envelope declaration (known: tgz, zip, dmg, exe, msi, pkg, deb, rpm, appimage). An open string ON PURPOSE: the arbiter owns the vocabulary, so a new format is not a schema change. Present -> the arbiter cross-checks it against the verified bytes' magic (a tripwire: store record and content disagreeing = refusal); absent -> the arbiter reads the magic alone.",
"type": "string"
}
}
},
"pins": {
"$comment": "the store's vet list, keyed by platform: keys are process.platform tags (win32/darwin/linux) + wildcard `*` (all platforms); keys are open (not enumerated) and `platforms` is derived from them. Each value is that platform's append-ordered list (tail = current). Selection (in the one arbiter): candidates = pins[<os>] UNION pins[`*`], highest by semver, an explicit os key beats `*` on a tie. Registry install-mode reads the chosen version's suffix: `-universal` = install whole (flat bin/), else extract os_<os>/bin; vendor has no suffix mode (each pin declares its own role). Invariants (fail loud): same version across keys must share one sha2-384; no duplicate version within a key; no covering key (no <os> and no `*`) = refusal, never a silent fallback.",
"type": "object",
"minProperties": 1,
"additionalProperties": {
"type": "array",
"minItems": 1,
"items": { "$ref": "#/definitions/pin" }
}
},
"registry": {
"$comment": "install from an npm-protocol registry: `name` + `registry` say how to fetch, `pins` (when store-vetted) how to verify -- each pin declares its `artifact` role (the envelope needs no statement: protocol-fixed, a tarball; per-platform content is the tarball's own os_<os> affair). Without `pins`: the publisher-channel path (resolve this platform's dist-tag, newest build, integrity warn-and-proceed) -- with no pin there is nowhere to write a role, so the ARBITER invariant holds structurally: unpinned = `self-contained` only; a role that EXECUTES or DELEGATES the payload is only spellable on a vetted pin. No auth entry: credentials never travel in a catalog.",
"type": "object",
"required": [ "method", "name", "registry" ],
"properties": {
"method": { "const": "registry" },
"name": {
"$comment": "the product's friendly/official name (PnB `name`) = the registry package name (name outranks registry -- registries are delegated storage); also the agent's default participant identity unless `referer` overrides.",
"type": "string"
},
"registry": { "type": "string" },
"referer": {
"$comment": "optional participant-identity override; absent -> `name`.",
"type": "string"
},
"pins": { "$ref": "#/definitions/pins" }
}
},
"vendor": {
"$comment": "install a vendor-hosted artifact: pins carry the bare `url` (fetch) + `sha2-384` (verify, fail-closed -- a bare vendor url has no registry SRI; trust-on-first-use) + the REQUIRED `artifact` role. `vendor` is the SOURCE discriminator; the role is DECLARED per pin (never derived from the url -- vendor naming is untrusted, and a signed/CDN url may carry no extension at all), because unlike registry it varies per platform (a win32 setup-exe pin + a darwin dmg pin under one spec, e.g. self-exe there, self-contained here). A self-exe installer places files and owns residency -- no `<root>/<pkg>/<version>` layout; presence/uninstall probe the OS's own markers. Authenticode/codesign identity verification is planned, sourced from the developer identity.",
"type": "object",
"required": [ "method", "name", "pins" ],
"properties": {
"method": { "const": "vendor" },
"name": {
"$comment": "the product's friendly/official name (PnB `name`); also the default participant identity unless `referer` overrides.",
"type": "string"
},
"referer": {
"$comment": "optional participant-identity override; absent -> `name`.",
"type": "string"
},
"pins": { "$ref": "#/definitions/pins" },
"run-at": {
"enum": [ "on-demand", "user-initiated", "logon", "boot" ]
}
}
},
"observable": {
"$comment": "install by observing a store endpoint (a curated list): poll the `cxn-pt` for content rather than fetching a package. `observable` is the SOURCE discriminator; there is no artifact, so no mechanic to state (polling is transport, not a mechanic). Complete as { method, cxn-pt } -- which list is the record's own identity, cadence is store-driven; no digest (lists are trustless curation, the product records the refs resolve to are what verify).",
"type": "object",
"required": [ "method", "cxn-pt" ],
"properties": {
"method": { "const": "observable" },
"cxn-pt": { "$comment": "opaque connection-point (string or object; validated via schema_ConnectionPoint). Authored-empty `{}` is the secure default -- 'the content authority is whoever served you this record'; the serving store fills its own endpoint at serve time (self-securing once store-signing exists). A filled-in cxn-pt is transport delegation only; content still verifies at the product level." }
}
},
"app-store": {
"$comment": "install via a third-party native store (Apple/Steam/Epic): the storefront owns distribution AND integrity, so no registry/pins/digest here. Complete as { method, storefront, app_id }: `storefront` names which store (the discriminator a per-store installer matches), `app_id` is that store's product id.",
"type": "object",
"required": [ "method", "storefront", "app_id" ],
"properties": {
"method": { "const": "app-store" },
"storefront": {
"$comment": "which native store owns this -- lowercase slug. The enum IS the set of supported stores (a new one = a new installer + a schema bump).",
"enum": [ "apple", "steam", "epic" ]
},
"app_id": {
"$comment": "the storefront's own product id, opaque outside that store's installer (Apple app/bundle id; Steam appid; Epic catalog id).",
"type": "string"
}
}
},
"install-spec": {
"oneOf": [
{ "$ref": "#/definitions/registry" },
{ "$ref": "#/definitions/vendor" },
{ "$ref": "#/definitions/observable" },
{ "$ref": "#/definitions/app-store" }
]
},
"install-ref": {
"$comment": "a reference to an INSTALLED package (spec = how to get it; ref = what's there): `name` (PnB `name` = the install-root node) + optional exact `version`. Absent version = all installed versions of the name.",
"type": "object",
"required": [ "name" ],
"properties": {
"name": { "type": "string" },
"version": { "type": "string" }
}
}
}
},
"https://root-interface.se/protocols/Definitions/InstallSpec": {
"$id": "https://root-interface.se/protocols/Definitions/InstallSpec",
"$schema": "https://json-schema.org/draft/2019-09/schema",
"$ref": "install-spec#/definitions/install-spec"
},
"https://root-interface.se/protocols/Definitions/InstallRef": {
"$id": "https://root-interface.se/protocols/Definitions/InstallRef",
"$schema": "https://json-schema.org/draft/2019-09/schema",
"$ref": "install-spec#/definitions/install-ref"
}
}
}
Related schemas
One field is left opaque in this schema because iface-gen embeds one schema per header. Consumers validate it against its own schema. The name fields tie a spec to its catalog record.
| Field | Schema | Shape |
|---|---|---|
|
A ConnectionPoint: a string, or an object with |
|
|
The product’s portable |
|
|
The Installer protocol carries an install-spec under |