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 |
|---|---|
|
The catalog: an array of |
|
|
|
An installable (or donate-only) thing, or a curated list, published by a developer. |
|
A collection of references. Comes in two kinds, |
|
A reference to a product or bundle by its portable |
|
The presentation face: a discriminated union of card styles. |
|
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
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 |
|---|---|---|---|
|
string |
yes |
The kind discriminator. Part of the identity, so it never changes. One of:
|
|
string |
yes |
The store-minted record key. Store-specific: it is never a cross-store identity. |
|
string |
no |
The friendly, official identity: a scoped package-style name such as |
|
string |
yes |
The display title. |
|
string |
no |
Facet. The card’s descriptive line, and the text that full-text search operates on. Present regardless of card style: a |
|
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). |
|
string |
no |
Authorship: the publishing party. |
|
string |
no |
Facet. The release date, normalized to an ISO 8601 calendar date |
|
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 |
|
array of string |
no |
Facet. Free-form labels, rendered as the card’s chip row and searched and filtered uniformly. |
|
no |
The presentation face. |
|
|
yes |
The commerce face. |
|
|
any |
yes |
Opaque install specification (an InstallSpec). Validated against |
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.
-
bundleis the catalog kind: a collection with a face of its own (display,price-block,oses,date_release), listed and retrievable as content. -
manifestis 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 thecurated-listproduct whose install signature points at it. A list is updated, not released, sodate_releasedoes 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 |
|---|---|---|---|---|
|
string |
yes |
both |
The kind discriminator. One of:
|
|
string |
yes |
both |
The store-minted record key. |
|
string |
no |
both |
The display title (the heading face of a |
|
string |
no |
both |
Descriptive text. |
|
string |
no |
both |
Who the bundle is from. |
|
string |
no |
both |
Authorship. For the |
|
string |
no |
bundle only |
The release date. |
|
string |
no |
both |
The date the contents were last updated. |
|
array of string |
no |
bundle only |
The operating systems the bundle targets. |
|
no |
bundle only |
The presentation face. |
|
|
no |
bundle only |
The commerce face. |
|
|
array of ref-pnb |
yes |
both |
The contents, as references by |
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 |
|---|---|---|---|
|
string |
yes |
The friendly |
|
array |
yes |
Where to fetch it. Each item is a ConnectionPoint: either a string, or an object with |
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 |
|---|---|---|
|
|
The single-row card (today’s Row look): text-only presentation. |
|
|
The image-banner card (the old ImgBanner230 template): authored cover or banner art. |
|
|
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 |
|---|---|---|---|
|
string |
yes |
The constant |
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 |
|---|---|---|---|
|
string |
yes |
The denomination of the block’s amounts, as an ISO 4217 code including the X-codes for non-national units: |
|
number |
yes |
The constant regular price, in
|
|
number |
no |
The current sale price, in |
|
boolean |
no |
Pay-what-you-want. Overrides |
How price and donate combine
price |
donate |
Meaning |
|---|---|---|
|
|
Not commerce: a plain Install. |
|
|
Donate, with no suggested amount. |
|
|
Free, through the bag. |
greater than |
|
Sold at |
greater than |
|
Donate, with |
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"
}
}
}
Related schemas
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 |
|---|---|---|
|
An InstallSpec: what to fetch and how to verify it (method, name, pins). |
|
|
A ConnectionPoint: a string, or an object with |
|
|
|
The |