Describe your product with two YAML files

On a platform deploy, forge-control reads both files, validates them with @blueforge-studio/blueforge-sidecar-schemas and sends them with the deployment registration. From your own CI you send the same content yourself in the product and features fields of POST /api/deployments. The site merges the two into one record per product.

The split is deliberate: identity changes rarely and is reviewed; copy can change on any deploy without touching the identity file.

The file is { version: "2.0.0", products: [...] } with at least one entry. Every object is strict: an unknown or misspelled key is a validation error, not a silently ignored field.

The file is { version: "2.0.0", features: [...], promotions?: [...] }. Each features[] row names the product it describes with product:, which must match an id in the product file.

• The id is the load-bearing key. Changing it creates a second catalog card; the old id stays until its registration is retired. Pick it once.
• The sidecar wins. Once a deploy has registered a sidecar for a product, its copy overrides any other description of the same id the catalog holds.
• First writer owns the app. A registration is keyed by (repo, app) and belongs to the organization that registered it first; another organization writing the same pair is refused with 403 tenant-mismatch.

Asset paths are repo-relative. The platform hashes each declared file and uploads only the ones whose sha256 changed; the site renders every size it needs from the upload. Any format the image pipeline decodes is accepted (png, jpeg, webp, gif, avif, svg, tiff).

The upload protocol, the fallbacks and the approval gate are on Asset sync.

Both files carry version: "2.0.0", the current schema version. The registration endpoint also accepts the older single-file shape (one product's fields at the top level of blueforge.product.yml), so an older repo keeps registering while it migrates — but new repos should write the two-file form above.

Imagery is versioned by content: a replaced file is a new object at a new URL, so caches never serve a stale image under a fresh name.

Schema changes

The schemas are strict, so a new field is only accepted once your pinned version of the schemas package knows it. Bump the package in the same change that starts using a new field.

Parse the YAML and run it through the schema before you deploy; a failure lists every issue with its path.

import { readFileSync } from "node:fs";
import { parse } from "yaml";
import { parseProductSidecar, parseFeaturesSidecar } from "@blueforge-studio/blueforge-sidecar-schemas";

const product = parseProductSidecar(parse(readFileSync("blueforge.product.yml", "utf8")));
const features = parseFeaturesSidecar(parse(readFileSync("blueforge.features.yml", "utf8")));

for (const r of [product, features]) {
  if (!r.ok) {
    console.error(r.issues);
    process.exit(1);
  }
}