Reference / listing
The catalog storefront entry for a blueprint or component.
JSON Schema · Specification · Examples · Source
This reference is generated from the schema bundle and is informative. Where it differs from the specification, the specification governs. A documented default is an annotation: no validator inserts it.
Structural and type validation only — cross-document reference resolution, slug/directory agreement, and platform capability checks are separate validation layers. See spec.md.
The catalog storefront entry for a blueprint or component.
Structural and type validation only — cross-document reference resolution, slug/directory agreement, and platform capability checks are separate validation layers. See spec.md.
Document kind discriminator. Must be LISTING.
Version of the Musher specification this document is written against.
Identity block of a listing document. A listing names the item it presents and carries no revision of its own; the item's revision is the blueprint's. See spec.md §3.
Item slug — must equal the item's directory name.
One storefront screenshot declared as a relative media path.
Accessible caption shown beneath the screenshot. Omitted when none.
Path of the screenshot asset under the item's media/ directory, relative to the item root. Must be a .png, .jpg, .jpeg or .webp below media/.
Lookahead-free so it compiles under RE2 as well as ECMA-262. A segment must begin with a letter or digit, which is how . and .. are excluded without a negative lookahead; the extension alternation is spelled in character classes because a JSON Schema pattern carries no case-insensitive flag. See spec.md §5.
The spec block of a listing document — how the item is presented,
categorised, and discovered on the storefront.
Identity lives in metadata, not here. icon and screenshots[].file are
media paths, resolved inside the item root and required to begin with
media/.
Storefront category the listing is browsed under.
Long-form Markdown storefront description. Omitted when none.
Storefront title shown to prospective installers.
Project homepage URL. Omitted when none. Must use the https, http, or mailto scheme, in any case.
Anchored and lookahead-free, so it compiles under RE2 as well as ECMA-262 and cannot be driven to backtrack. The scheme set is spec.md §4.1's, applied to a field that carries a URL directly rather than inside Markdown. The scheme alternation is spelled in character classes because a JSON Schema pattern carries no case-insensitive flag, and RFC 3986 §3.1 makes the scheme case-insensitive — the same reason the media path alternation is spelled that way. Without it this pattern would reject an upper-case scheme the description half of the same rule accepts.
Path of the listing's icon under the item's media/ directory (e.g. media/icon.png), relative to the item root. Omitted for no icon.
The same grammar ListingScreenshot.file carries; see the note there.
Shape of the catalog item this listing presents: BLUEPRINT (a composition) or COMPONENT (a single building block).
spec.md §3. BLUEPRINT if and only if the item root holds blueprint.yaml — a semantic rule, because it reads the item root rather than the document.
SPDX licence expression for the listed software, such as MIT or Apache-2.0 WITH LLVM-exception. Omitted when unspecified.
spec.md §4 / ADR 0003 §2 and §4. The shape is this contract's and the membership is SPDX's, published at https://spdx.org/licenses/ and deliberately not restated. Flat: a parenthesised expression is outside this grammar, which spec.md §9 records. Anchored and lookahead-free, so it compiles under RE2 as well as ECMA-262.
Maturity stage shown on the storefront: STABLE, BETA, EXPERIMENTAL, or SUNSET.
Storefront screenshots in display order, declared as media paths. At most twelve.
Source repository URL. Omitted when none. Must use the https, http, or mailto scheme, in any case.
The same grammar homepageURL carries; see the note there.
One-line storefront tagline summarising the listing.
Support or documentation URL. Omitted when none. Must use the https, http, or mailto scheme, in any case.
The same grammar homepageURL carries; see the note there. mailto: is in the set for this field in particular — a support address is a plausible value.
Free-form discovery tags applied to the listing. At most sixteen, and a tag may not repeat.