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

install-spec

How to get and verify a thing; exactly one of the four methods.

registry

Install from an npm-protocol registry.

vendor

Install a vendor-hosted artifact.

observable

Install by observing a store endpoint, a curated list.

app-store

Install via a third-party native store.

pins

The store’s vet list, keyed by platform.

pin

One vetted artifact: version, digest and role.

artifact

The artifact-role vocabulary: what the payload is to its consumer.

install-ref

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

InstallSpec

install-spec#/definitions/install-spec

InstallRef

install-spec#/definitions/install-ref

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_Registry header already names the planned Source_Vendor flavor: "bare URL, no metadata, execute-not-extract" (the tx-Decentraland installer)

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

registry

registry

An npm-protocol registry. name and registry say how to fetch; pins, when store-vetted, how to verify.

vendor

vendor

A vendor-hosted artifact. Each pin carries a bare url to fetch and a digest to verify.

observable

observable

A store endpoint, a curated list, polled for content rather than fetched as a package.

app-store

app-store

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+self-contained

registry pull → extract → run in place

today’s "registry" — dvi’s current flow

registry+self-exe

registry pull → execute, it installs itself

npm/GitLab-hosted setup.exe / .pkg

registry+os-package

registry pull → hand to the OS manager

registry-served .msi / .deb

registry+image

OCI registry pull

docker

vendor+self-contained

bare URL → extract/copy in place

zip/tarball/AppImage download

vendor+self-exe

bare URL → execute, it installs itself

the planned Source_Vendor (tx-DCL, execute-not-extract)

vendor+os-package

bare URL → OS manager

.deb/.msi download link

git+build

clone → build locally

from-source

observable

subscribe to a store endpoint; nothing lands

today’s "observable" (curated lists) — poll is the only mechanism it could mean

os-package

the platform’s own repo + manager, as one act

apt / winget / brew

app-store

the store is both source and mechanism; you hold no artifact

Apple/Microsoft/Google stores

web

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

method

string

yes

The constant registry.

name

string

yes

The product’s friendly, official name (the ProductsAndBundles name), which equals the registry package name. Name outranks registry: registries are delegated storage. Also the agent’s default participant identity, unless referer overrides it.

registry

string

yes

The registry to fetch from.

referer

string

no

Optional participant-identity override. Absent, the identity is name.

pins

pins

no

The store’s vet list. Each pin declares its artifact role.

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

method

string

yes

The constant vendor.

name

string

yes

The product’s friendly, official name (the ProductsAndBundles name). Also the default participant identity, unless referer overrides it.

referer

string

no

Optional participant-identity override. Absent, the identity is name.

pins

pins

yes

The store’s vet list. Every vendor pin carries url.

run-at

string

no

When the installed thing is started. One of:

  • on-demand: when something asks for it.

  • user-initiated: when the user starts it.

  • logon: at user logon.

  • boot: at system boot.

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

method

string

yes

The constant observable.

cxn-pt

any

yes

Opaque connection point, a string or an object, validated against schema_ConnectionPoint; see Related schemas. An authored-empty {} is the secure default: the content authority is whoever served you this record, and the serving store fills in 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

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

method

string

yes

The constant app-store.

storefront

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:

  • apple: Apple’s app stores.

  • steam: Steam.

  • epic: the Epic Games Store.

app_id

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

win32, darwin, linux, …​

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>] and pins[*].

  • The highest version by semver wins. On a tie, an explicit os key beats *.

  • Registry install mode reads the chosen version’s suffix: -universal installs the whole package (a flat bin/), anything else extracts os_<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

version

string

yes

both

The exact version of the artifact.

sha2-384

string

yes

both

The whole-file digest, as shasum -a 384 hex.

artifact

artifact

yes

both

The role: what the payload is to its consumer.

url

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.

format

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:

  • tgz, zip

  • dmg, pkg

  • exe, msi

  • deb, rpm, appimage

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

self-contained

is the app.

Place it.

self-exe

installs the app.

Execute it; it then owns residency.

os-package

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

name

string

yes

The ProductsAndBundles name, which is the install-root node.

version

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"
    }
  }
}

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

observable.cxn-pt

schema_ConnectionPoint

A ConnectionPoint: a string, or an object with protocol, address and port.

registry.name, vendor.name, install-ref.name

schema_ProductsAndBundles

The product’s portable name. A product carries its spec in install-spec, and its platforms facet is derived from the spec’s pins keys.

install-spec

schema_Installer

The Installer protocol carries an install-spec under install-spec for install and outdated queries.