ProductsAndBundles

Fields

This section documents version 4 of the schema (_v is the constant "4"). 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

A catalog is a products-and-bundles array. Each item is a product-or-bundle: it validates as exactly one of product or bundle. Both share two sub-objects, display (how a thing is presented) and price-block (how it is sold). A bundle lists its contents as ref-pnb references.

Definition Purpose

products-and-bundles

The catalog: an array of product-or-bundle items.

product-or-bundle

One catalog item; exactly one of product or bundle.

product

An installable (or donate-only) thing, or a curated list, published by a developer.

bundle

A collection of references. Comes in two kinds, bundle and manifest.

ref-pnb

A reference to a product or bundle by its portable name, plus where to fetch it.

display

The presentation face: a discriminated union of card styles.

price-block

The commerce face: currency, price, discount and donate.

The schema also publishes four standalone entry points, for validators that embed one schema per header:

$id (under https://root-interface.se/protocols/Definitions/) Resolves to

Product

#/definitions/product

Bundle

#/definitions/bundle

RefPnB

#/definitions/ref-pnb

products-and-bundles

#/definitions/products-and-bundles

product

The minimum identity of anything the federation can reference: who (developer) says what (type, id, title) and how to get and verify it (install-spec). On top of the identity sit the facets (uniform fields that filter, search and sort operate on, whatever the card style), the display section and the price-block section.

Identity fields are immutable for the product’s lifetime: changing type, id, name, title, developer or install-spec makes it a different product.

Field Type Required Description

type

string

yes

The kind discriminator. Part of the identity, so it never changes. One of:

  • product: an ordinary catalog product.

  • curated-list: a curated list. Its observable+poll install signature points at the list contents, a bundle of the manifest kind served in the CuratedList envelope. The list’s commerce and presentation live on this product.

id

string

yes

The store-minted record key. Store-specific: it is never a cross-store identity.

name

string

no

The friendly, official identity: a scoped package-style name such as @scope/name. Portable across stores: two stores listing the same name list the same product. When an artifact exists (see install-spec), name equals the registry package name; the same name at two registries is disambiguated by the install signature, never by the name. Non-installables (bundles, donate-only things) get scoped names too. Curated-list references point by name. Immutable: renaming makes a different product.

title

string

yes

The display title.

description

string

no

Facet. The card’s descriptive line, and the text that full-text search operates on. Present regardless of card style: a rendered card carries it even though its face is the HTML.

developer

string

yes

Who the product is from. Today an unverified display claim. It becomes verifiable once bound to a developer signing key (key-as-identity, no CA; the curator’s list signature vouches for the name-to-key binding).

publisher

string

no

Authorship: the publishing party.

date_release

string

no

Facet. The release date, normalized to an ISO 8601 calendar date YYYY-MM-DD (pattern ^\d{4}-\d{2}-\d{2}$). Computable, not prose: sort-by-newest orders on it, and the NEW badge is derived from it (released within the renderer’s recency window). There is no authored "new" flag. Free-text values such as Q1 2023 do not validate.

platforms

array of string

yes

Facet. What the thing runs on, as shown by the platform icons. The schema does not enumerate the values; the icons today are Windows, macOS, Ubuntu and browser. Named "platforms", not "oses", because a browser is not an OS. Not architectures either: x64 versus arm64 is the precision of the install signature’s pins. The claim is coarse, the proof is exact.

tags

array of string

no

Facet. Free-form labels, rendered as the card’s chip row and searched and filtered uniformly.

display

display

no

The presentation face.

price-block

price-block

yes

The commerce face.

install-spec

any

yes

Opaque install specification (an InstallSpec). Validated against schema_InstallSpec, not constrained here; see Related schemas.

bundle

One object, two kinds. The properties are declared once; a kind only fixes the type constant and forbids the fields that do not apply to it.

  • bundle is the catalog kind: a collection with a face of its own (display, price-block, oses, date_release), listed and retrievable as content.

  • manifest is a curated list’s contents: identity, a heading face and the refs. It is served inside the CuratedList poll envelope { ttl_msec, manifest } and never appears in results. Its commerce and presentation live on the curated-list product whose install signature points at it. A list is updated, not released, so date_release does not apply.

A kind-inconsistent record, for example a manifest carrying a price-block, fails validation. Which kind a given slot expects remains the consumer’s one-line type check (loose bindings, strict consumers).

Field Type Required Kind Description

type

string

yes

both

The kind discriminator. One of:

  • bundle: the catalog kind.

  • manifest: the curated-list contents kind.

id

string

yes

both

The store-minted record key.

title

string

no

both

The display title (the heading face of a manifest).

description

string

no

both

Descriptive text.

developer

string

no

both

Who the bundle is from.

publisher

string

no

both

Authorship. For the manifest kind this is the old list author, unified to the product-family word.

date_release

string

no

bundle only

The release date.

date_updated

string

no

both

The date the contents were last updated.

oses

array of string

no

bundle only

The operating systems the bundle targets.

display

display

no

bundle only

The presentation face.

price-block

price-block

no

bundle only

The commerce face.

refs

array of ref-pnb

yes

both

The contents, as references by name plus connection points. One reference grade serves both kinds. The v3 inline-product and bare { ref: id } item forms are gone; an inline item migrates to a real catalog record plus a ref.

ref-pnb

A reference to a product or bundle: its portable name plus the connection points where to fetch it. This is the shape of a curated-list entry.

Field Type Required Description

name

string

yes

The friendly name of the referenced product or bundle (the portable identity). Not the store-specific id.

cxn-pts

array

yes

Where to fetch it. Each item is a ConnectionPoint: either a string, or an object with protocol, address and port. Validated against schema_ConnectionPoint, not constrained here; see Related schemas.

display

The presentation face of a thing: a discriminated union of card styles. Each style is a self-contained variant, discriminated by its required type constant, and a display object must match exactly one of them.

type Variant Card

single-row

display-single-row

The single-row card (today’s Row look): text-only presentation.

ImgBanner230

display-imgbanner230

The image-banner card (the old ImgBanner230 template): authored cover or banner art.

rendered

display-rendered

The free-form card: the store renders authored HTML.

Adding a card style means adding a display-<style> definition and a oneOf arm; nothing else changes.

display-single-row

Text only. The variant carries no fields beyond its discriminator.

Field Type Required Description

type

string

yes

The constant single-row.

display-imgbanner230

Field Type Required Description

type

string

yes

The constant ImgBanner230.

img

string

yes

The banner or cover image the card renders: the authorable cover-art slot.

display-rendered

Field Type Required Description

type

string

yes

The constant rendered.

html

string

yes

The authored HTML the store renders as the card’s face. This is v3’s display.html slot, now a real contract instead of a dead field.

price-block

The commerce face of a thing. The commerce stance is always a declaration, never an omission: price is required, and the special value -1 declares "not commerce".

Field Type Required Description

currency

string

yes

The denomination of the block’s amounts, as an ISO 4217 code including the X-codes for non-national units: USD, EUR, SEK, XBT/BTC, and so on. Display-grade: amounts stay JSON numbers. If the bag ever settles for real, that step moves to integer minor units.

price

number

yes

The constant regular price, in currency. A sale never rewrites it; discounted-price slashes it instead. One of:

  • -1: not commerce. The only legal negative value.

  • 0: free, through the bag.

  • greater than 0: the price. Doubles as the suggested amount when donate is true.

discounted-price

number

no

The current sale price, in currency, while the discount runs. price stays the constant regular price and is rendered struck-through beside it. The badge percentage is derived, never authored: round((1 - discounted-price / price) * 100).

donate

boolean

no

Pay-what-you-want. Overrides price entirely: a donate thing is never "free", it always takes the dialog/bag path.

How price and donate combine

price donate Meaning

-1

false or absent

Not commerce: a plain Install.

-1

true

Donate, with no suggested amount.

0

false or absent

Free, through the bag.

greater than 0

false or absent

Sold at price, or at discounted-price while a discount runs.

greater than 0

true

Donate, with price as the suggested amount.

Rendering precedence

The block is read in the order donate, then discounted-price, then price. A missing block, or a missing price, renders as Free. When neither donate nor a discount applies, the badge slot is left to the NEW badge, which is derived from date_release.

Schema

{
  "$id": "https://root-interface.se/protocols/Definitions/ProductsAndBundles",
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "schemas": {
    "https://root-interface.se/protocols/Definitions/ProductsAndBundles": {
      "$id": "https://root-interface.se/protocols/Definitions/ProductsAndBundles",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "definitions": {
        "_v": { "const": "4" },
        "display-single-row": {
          "$comment": "the single-row card (today's Row look): text-only presentation",
          "type": "object",
          "required": [ "type" ],
          "properties": {
            "type": { "const": "single-row" }
          }
        },
        "display-rendered": {
          "$comment": "the free-form card: the store renders authored HTML (v3's `display.html` slot, now a real contract instead of a dead field)",
          "type": "object",
          "required": [ "type", "html" ],
          "properties": {
            "type": { "const": "rendered" },
            "html": { "type": "string" }
          }
        },
        "display-imgbanner230": {
          "$comment": "the image-banner card (the old ImgBanner230 template): authored cover/banner art",
          "type": "object",
          "required": [ "type", "img" ],
          "properties": {
            "type": { "const": "ImgBanner230" },
            "img": { "$comment": "the banner/cover image the card renders (the authorable cover-art slot)", "type": "string" }
          }
        },
        "display": {
          "$comment": "the presentation face of a thing -- v3's `display` reborn as a DISCRIMINATED union: each card style is its own self-contained variant, discriminated by the required `type` const (the old Product_switch dispatch pattern). Adding a card style = add a display-<style> definition + a oneOf arm here; nothing else changes. (v3's `html` lives on as the display-rendered variant; `categories` and theme-as-free-string do not carry over.)",
          "oneOf": [
            { "$ref": "#/definitions/display-single-row" },
            { "$ref": "#/definitions/display-imgbanner230" },
            { "$ref": "#/definitions/display-rendered" }
          ]
        },
        "price-block": {
          "$comment": "the commerce face of a thing. Precedence when rendered: donate > discounted > price; a missing block (or missing price) = Free, and neither donate nor discounted = the NEW badge.",
          "type": "object",
          "required": [ "currency", "price" ],
          "properties": {
            "currency": { "$comment": "the denomination of the block's amounts, as an ISO 4217 code incl. the X-codes for non-national units (USD, EUR, SEK, XBT/BTC, ...). Display-grade: amounts stay JSON numbers; if the bag ever settles for real, that step moves to integer minor-units", "type": "string" },
            "price": {
              "$comment": "in `currency`; the CONSTANT regular price (a sale never rewrites it -- `discounted-price` slashes it instead). REQUIRED -- the commerce stance is always a DECLARATION, never an omission: -1 (the ONLY legal negative) = not commerce (donate false -> plain INSTALL; donate true -> no suggested amount); 0 = Free through the bag; > 0 = the price (doubling as the suggestion when donate is true)",
              "type": "number",
              "oneOf": [ { "const": -1 }, { "minimum": 0 } ]
            },
            "discounted-price": { "$comment": "in `currency`; the CURRENT (sale) price while the discount runs -- `price` stays the CONSTANT regular price and is rendered struck-through beside it. The badge percentage is DERIVED: round((1 - discounted-price/price) * 100), never authored (OAOO)", "type": "number" },
            "donate": { "$comment": "pay-what-you-want: overrides price entirely (a donate thing is never 'free' -- it always takes the dialog/bag path)", "type": "boolean" }
          }
        },
        "product": {
          "$comment": "v4 (grown from the 'thing' identity work): the minimum 'ID' of anything the federation can reference -- WHO (developer) says WHAT (type, id, title) and HOW to get/verify it (install-spec) -- plus the FACETS (uniform, what filter/search/sort operate on), the display (presentation) and price-block (commerce) sections. Identity fields are IMMUTABLE for the product's lifetime -- changing one makes it a DIFFERENT product. `developer` is today an unverified display claim; it becomes verifiable when bound to a developer signing key (key-as-identity -- no CA; the curator's list signature vouches for the name<->key binding). v3's flat price/was/discount, oses, origin and the old display shape are GONE -- catalog data migrates.",
          "type": "object",
          "required": [ "type", "id", "title", "developer", "platforms", "price-block", "install-spec" ],
          "properties": {
            "type": { "$comment": "the kind discriminator -- part of the ID (a product's kind never changes); bundle narrows its own const against these", "enum": [ "product", "curated-list" ] },
            "id": { "type": "string" },
            "name": { "$comment": "the product's FRIENDLY/official identity: a scoped pkg-style name ('@scope/name'). PORTABLE across stores (two stores listing the same `name` list the same product), unlike `id` -- the store-minted record key, which stays store-specific and is never a cross-store identity. When an artifact exists (install-spec), `name` EQUALS the registry pkg name; the registry is delegated storage, so the same name at two registries is disambiguated by the sig, never by the name. Non-installables (bundles, donate-only) get scoped names too. Identity -> immutable: renaming makes a DIFFERENT product. Curated-list refs point by it.", "type": "string" },
            "title": { "type": "string" },
            "description": { "$comment": "FACET: the card's descriptive line, and what full-text search operates on -- present regardless of card style (a `rendered` card carries it even though its face is the html)", "type": "string" },
            "developer": { "type": "string" },
            "publisher": { "type": "string" },
            "date_release": {
              "$comment": "FACET, NORMALIZED to an ISO 8601 calendar date (YYYY-MM-DD) so it is COMPUTABLE, not prose: sort-by-newest orders on it, and the NEW badge is DERIVED from it (released within the renderer's recency window) -- never an authored 'new' flag (OAOO: staleness-proof by construction). v3's free-text values ('Q1 2023') do not conform and migrate to real dates.",
              "type": "string",
              "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
            },
            "platforms": { 
              "$comment": "FACET (filter/search operate here, uniform on every thing regardless of card style): what the thing runs on, as shown by the platform icons (Windows | macOS | Ubuntu | browser | ...) -- 'platforms' not 'oses' (a browser is not an OS), and not architectures (x64/arm64 is the install sig pins' precision: the claim is coarse, the proof is exact)", 
              "type": "array", 
              "items": { "type": "string" } 
            },
            "tags": { "$comment": "FACET: free-form labels, rendered as the card's chip row and searched/filtered uniformly",
              "type": "array",
              "items": { "type": "string" }
            },
            "display": { "$ref": "#/definitions/display" },
            "price-block": { "$ref": "#/definitions/price-block" },
            "install-spec": { "$comment": "opaque install specification (an InstallSpec -- validated via schema_InstallSpec, not cross-ref'd/constrained here since iface-gen embeds one schema per header)" }
          }
        },
        "ref-pnb": {
          "$comment": "a reference to a product-or-bundle: its friendly `name` (the portable identity -- NOT the store-specific `id`) + the cxn-pts WHERE to fetch it (the shape of a curated-list entry)",
          "type": "object",
          "required": [ "name", "cxn-pts" ],
          "properties": {
            "name": { "type": "string" },
            "cxn-pts": {
              "$comment": "opaque connection-points (each a ConnectionPoint -- string OR object; validated via schema_ConnectionPoint, not cross-ref'd here since iface-gen embeds one schema per header)",
              "type": "array"
            }
          }
        },
        "bundle": {
          "$comment": "ONE object, TWO kinds -- the properties are declared ONCE below; the oneOf arms are pure CONSTRAINT lines (a discriminator const + the kind's required set + `false`-forbids for non-applicable fields). `bundle` = the catalog kind, with a face of its own (display / price-block / oses / date_release) and retrievable as content; `manifest` = a curated list's CONTENTS -- identity + a heading face + refs, served inside CuratedList's { ttl_msec, manifest } envelope and NEVER in results (commerce and presentation live on the curated-list PRODUCT whose observable+poll sig points at it). A kind-INCONSISTENT record (e.g. a priced manifest) fails validation here; which kind a given SLOT expects stays the consumer's one-line type check (loose bindings, strict consumers).",
          "type": "object",
          "required": [ "type", "id", "refs" ],
          "properties": {
            "id": { "type": "string" },
            "title": { "type": "string" },
            "description": { "type": "string" },
            "developer": { "type": "string" },
            "publisher": {
              "$comment": "authorship; for the manifest kind this is the old list `author`, unified to the product-family word",
              "type": "string"
            },
            "date_release": { "type": "string" },
            "date_updated": { "type": "string" },
            "oses": { "type": "array", "items": { "type": "string" } },
            "display": { "$ref": "#/definitions/display" },
            "price-block": { "$ref": "#/definitions/price-block" },
            "refs": {
              "$comment": "the contents as RefPnBs (name + cxn-pts) -- one reference grade for both kinds; the v3 inline-product and bare {ref: id} item forms are GONE (an inline item migrates to a real catalog record + a ref)",
              "type": "array",
              "items": { "$ref": "#/definitions/ref-pnb" }
            }
          },
          "oneOf": [
            {
              "$comment": "the catalog kind",
              "properties": { "type": { "const": "bundle" } }
            },
            {
              "$comment": "the manifest kind: the catalog face MUST BE ABSENT (`false` = boolean subschema rejecting any value) -- a list is updated, not released, and its commerce/presentation live on its curated-list product",
              "properties": {
                "type": { "const": "manifest" },
                "price-block": false,
                "display": false,
                "oses": false,
                "date_release": false
              }
            }
          ]
        },
        "product-or-bundle": {
          "oneOf": [
            { "$ref": "#/definitions/product" },
            { "$ref": "#/definitions/bundle" }
          ]
        },
        "products-and-bundles": {
          "type": "array",
          "items": { "$ref": "#/definitions/product-or-bundle" }
        }
      }
    },
    "https://root-interface.se/protocols/Definitions/Product": {
      "$id": "https://root-interface.se/protocols/Definitions/Product",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$ref": "ProductsAndBundles#/definitions/product"
    },
    "https://root-interface.se/protocols/Definitions/Bundle": {
      "$id": "https://root-interface.se/protocols/Definitions/Bundle",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$ref": "ProductsAndBundles#/definitions/bundle"
    },
    "https://root-interface.se/protocols/Definitions/RefPnB": {
      "$id": "https://root-interface.se/protocols/Definitions/RefPnB",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$ref": "ProductsAndBundles#/definitions/ref-pnb"
    },
    "https://root-interface.se/protocols/Definitions/products-and-bundles": {
      "$id": "https://root-interface.se/protocols/Definitions/products-and-bundles",
      "$schema": "https://json-schema.org/draft/2019-09/schema",
      "$ref": "ProductsAndBundles#/definitions/products-and-bundles"
    }
  }
}

Two fields are left opaque in this schema because iface-gen embeds one schema per header. Consumers validate them against their own schema. The manifest kind of bundle is likewise referenced loosely from the CuratedList schema.

Field Schema Shape

product.install-spec

schema_InstallSpec

An InstallSpec: what to fetch and how to verify it (method, name, pins).

ref-pnb.cxn-pts[]

schema_ConnectionPoint

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

bundle (manifest kind)

schema_CuratedList

The { ttl_msec, manifest } poll envelope. Its manifest is a bundle of the manifest kind, validated against this schema.