diff --git a/schemas/htmlasset.yaml b/schemas/htmlasset.yaml
index ab663d1..2ea77e6 100644
--- a/schemas/htmlasset.yaml
+++ b/schemas/htmlasset.yaml
@@ -1,7 +1,7 @@
HtmlAsset:
deprecated: true
description: |
- **Notice: The HtmlAsset is deprecated, use the [TextAsset](#tocs_textasset) instead.**
+ **Notice: The HtmlAsset is deprecated, use the [RichTextAsset](#tocs_richtextasset) instead.**
The HtmlAsset clip type lets you create text based layout and formatting using
HTML and CSS. You can also set the height and width of a bounding box for the HTML
diff --git a/schemas/soundtrack.yaml b/schemas/soundtrack.yaml
index 313e25f..5bb058f 100644
--- a/schemas/soundtrack.yaml
+++ b/schemas/soundtrack.yaml
@@ -1,5 +1,10 @@
Soundtrack:
+ deprecated: true
description: >-
+ **Notice: The Soundtrack is deprecated, use an [AudioAsset](#tocs_audioasset)
+ clip on its own track instead.** This type continues to function; no behaviour
+ change for existing integrations.
+
A music or audio file in mp3 format that plays for the duration of the
rendered video or the length of the audio file, which ever is shortest.
properties:
diff --git a/schemas/textasset.yaml b/schemas/textasset.yaml
index 36eea9c..3f2f900 100644
--- a/schemas/textasset.yaml
+++ b/schemas/textasset.yaml
@@ -1,5 +1,9 @@
TextAsset:
+ deprecated: true
description: |
+ **Notice: The TextAsset is deprecated, use the [RichTextAsset](#tocs_richtextasset) instead.** This type
+ continues to function; no behaviour change for existing integrations.
+
The TextAsset is used to add text and titles to a video. The text can be styled with built in and custom
[Fonts](#tocs_font). You can also add a background bounding box used to control wrapping and overflow. Emoticons are also supported.
type: object
diff --git a/schemas/timeline.yaml b/schemas/timeline.yaml
index e58e7e3..d8cebfb 100644
--- a/schemas/timeline.yaml
+++ b/schemas/timeline.yaml
@@ -7,7 +7,10 @@
specific amount of time.
properties:
soundtrack:
- description: A music or audio soundtrack file in mp3 format.
+ deprecated: true
+ description: >-
+ A music or audio soundtrack file in mp3 format. Deprecated - use an
+ [AudioAsset](#tocs_audioasset) clip on its own track instead.
$ref: "./soundtrack.yaml#/Soundtrack"
background:
description: >-
diff --git a/schemas/titleasset.yaml b/schemas/titleasset.yaml
index f6d9da0..3a7665b 100644
--- a/schemas/titleasset.yaml
+++ b/schemas/titleasset.yaml
@@ -1,7 +1,7 @@
TitleAsset:
deprecated: true
description: |
- **Notice: The TitleAsset is deprecated, use the [TextAsset](#tocs_textasset) instead.**
+ **Notice: The TitleAsset is deprecated, use the [RichTextAsset](#tocs_richtextasset) instead.**
The TitleAsset clip type lets you create video titles from a text string and apply styling and positioning.
type: object
diff --git a/scripts/generate-json-schema.cjs b/scripts/generate-json-schema.cjs
index 9d68cd2..4264bd2 100644
--- a/scripts/generate-json-schema.cjs
+++ b/scripts/generate-json-schema.cjs
@@ -1,874 +1,140 @@
+/**
+ * Full-fidelity JSON Schema for the Edit API, for consumers that want the
+ * complete contract (MCP tool inputSchemas, editor validation, docs tooling).
+ *
+ * Keeps optionality, every enum value, every asset type, all validation
+ * keywords, `deprecated` flags, and descriptions (HTML converted to plain
+ * text). OAS-only keywords (`xml`, `x-*`) are dropped; `nullable` and
+ * `example` are converted to their JSON Schema equivalents.
+ *
+ * Output: dist/json-schema/edit.json — self-contained draft 2020-12 schema
+ * with internal $defs, plus barrel index files for the `/json` subpath export.
+ */
const fs = require("fs");
const path = require("path");
const BUNDLED_PATH = path.join(__dirname, "..", "dist", "api.bundled.json");
const OUT_DIR = path.join(__dirname, "..", "dist", "json-schema");
-const MAX_CHARS = 5000;
-
-// Properties to remove from object schemas
-const STRIP_PROPERTIES = new Set(["instance"]);
-
-// Max total chars for enum values per field.
-// Cerebras limits total property/definition/enum string length to 5000 chars.
-// Enums exceeding this are reduced to base variants (no Slow/Fast suffixes)
-// then stripped entirely if still over.
-const MAX_ENUM_CHARS = 400;
-
-// For large enums: strip speed suffixes (Slow/Fast) to create a compact base set.
-// Falls back to full strip if the reduced set still exceeds MAX_ENUM_CHARS.
-function reduceEnum(values) {
- const reduced = values.filter(
- (v) => !v.endsWith("Slow") && !v.endsWith("Fast"),
- );
- return reduced.length > 0 && reduced.length < values.length
- ? reduced
- : values;
-}
-
-// Schema names to exclude entirely from $defs and anyOf branches
-// Schemas to exclude (exact names and patterns)
-const EXCLUDE_EXACT = new Set([
- "MuxDestination",
- "MuxDestinationOptions",
- "DolbyEnhancement",
- "DolbyEnhancementOptions",
- "HtmlAsset",
- "Html5Asset",
- "TitleAsset",
- "TextAsset",
-]);
-const EXCLUDE_PATTERNS = [
- /GeneratedAsset/, // All generated asset schemas (HeyGen, OpenAi, StabilityAi, DID, etc.)
- /TextToSpeechOptions/,
- /TextToImageOptions/,
- /TextToAvatarOptions/,
- /TextGeneratorOptions/,
-];
-function isExcluded(name) {
- return EXCLUDE_EXACT.has(name) || EXCLUDE_PATTERNS.some((p) => p.test(name));
-}
-
-const STRIP_KEYWORDS = new Set([
- // OAS-only keywords
- "example",
- "xml",
- "deprecated",
- "discriminator",
- // Informational metadata (unsupported by Cerebras strict mode)
- "title",
- "default",
- "$schema",
- // String validation (unsupported by Cerebras)
- "minLength",
- "maxLength",
- "pattern",
- "format",
- // Array validation (unsupported by Cerebras)
- "minItems",
- "maxItems",
- "uniqueItems",
- // Object validation (not needed with additionalProperties: false)
- "minProperties",
- "maxProperties",
-]);
-
-// Number constraints ARE supported by Cerebras:
-// minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf
const api = JSON.parse(fs.readFileSync(BUNDLED_PATH, "utf8"));
const oasSchemas = api.components.schemas;
-// Make a property schema nullable using anyOf with null
-function makeNullable(propSchema) {
- if (propSchema.$ref) {
- return { anyOf: [propSchema, { type: "null" }] };
- }
- if (propSchema.anyOf) {
- if (!propSchema.anyOf.some((s) => s.type === "null")) {
- return { ...propSchema, anyOf: [...propSchema.anyOf, { type: "null" }] };
- }
- return propSchema;
- }
- if (propSchema.oneOf) {
- if (!propSchema.oneOf.some((s) => s.type === "null")) {
- const { oneOf, ...rest } = propSchema;
- return { ...rest, anyOf: [...oneOf, { type: "null" }] };
- }
- return propSchema;
- }
- if (propSchema.type) {
- const types = Array.isArray(propSchema.type)
- ? propSchema.type
- : [propSchema.type];
- if (!types.includes("null")) {
- const { type, ...rest } = propSchema;
- return {
- anyOf: [
- { type: types.length === 1 ? types[0] : types, ...rest },
- { type: "null" },
- ],
- };
- }
- }
- return propSchema;
-}
-
+// OAS descriptions use HTML (- , , ) — flatten to plain text so
+// agent-facing schema descriptions read cleanly.
+function htmlToText(s) {
+ return s
+ .replace(/
- /g, "\n- ")
+ .replace(/]*href="([^"]+)"[^>]*>([^<]*)<\/a>/g, "$2 ($1)")
+ .replace(//g, "\n")
+ .replace(/<[^>]+>/g, "")
+ .replace(/[ \t]+\n/g, "\n")
+ .replace(/\n{3,}/g, "\n\n")
+ .trim();
+}
+
+// OAS 3.0 schema object → JSON Schema draft 2020-12.
+// Keeps everything except OAS-only keywords; converts nullable and example.
function convertSchema(schema) {
- if (schema === null || schema === undefined || typeof schema !== "object") {
- return schema;
- }
-
- if (Array.isArray(schema)) {
- return schema.map(convertSchema).filter((item) => {
- // Remove $refs to excluded schemas from arrays (e.g. anyOf branches)
- if (item && item.$ref) {
- const match = item.$ref.match(/\/([^/]+)$/);
- if (match && isExcluded(match[1])) return false;
- }
- return true;
- });
- }
+ if (schema === null || typeof schema !== "object") return schema;
+ if (Array.isArray(schema)) return schema.map(convertSchema);
const out = {};
for (const [key, value] of Object.entries(schema)) {
- if (STRIP_KEYWORDS.has(key) || key.startsWith("x-")) continue;
-
- // Rewrite $ref paths
+ // OAS-only keywords: discriminator is a routing hint (oneOf branches still
+ // discriminate via their `type` enums) and its mapping holds unrewritten
+ // #/components/schemas/ paths; ajv strict mode rejects unknown keywords.
+ if (key === "xml" || key === "discriminator" || key.startsWith("x-")) continue;
+ if (key === "nullable") continue; // handled below
+ // OAS numeric type modifiers are not JSON Schema formats (which apply to
+ // strings); strict validators reject them as unknown.
+ if (key === "format" && ["float", "double", "int32", "int64"].includes(value)) continue;
if (key === "$ref" && typeof value === "string") {
- out[key] = value
- .replace("#/components/schemas/", "#/$defs/")
- .replace(/\/oneOf\//g, "/anyOf/");
+ out.$ref = value.replace("#/components/schemas/", "#/$defs/");
continue;
}
-
- // Skip OAS nullable (handled below)
- if (key === "nullable") continue;
-
- // Rename oneOf → anyOf (Cerebras only supports anyOf)
- if (key === "oneOf") {
- out.anyOf = convertSchema(value);
+ if (key === "example") {
+ out.examples = [value];
continue;
}
-
- // Convert properties dict: each value is a schema, but the dict itself is not
- if (
- key === "properties" &&
- typeof value === "object" &&
- !Array.isArray(value)
- ) {
- const props = {};
- for (const [propName, propSchema] of Object.entries(value)) {
- if (STRIP_PROPERTIES.has(propName)) continue;
- const converted = convertSchema(propSchema);
- // Derive enum from default/example for discriminator-like fields (e.g. provider)
- // When both default and example are the same string, it's a constant identifier
- if (
- propSchema.type === "string" &&
- !propSchema.enum &&
- propSchema.default &&
- propSchema.default === propSchema.example
- ) {
- converted.enum = [propSchema.default];
- }
- props[propName] = converted;
- }
- out.properties = props;
+ if (key === "description" && typeof value === "string") {
+ out.description = htmlToText(value);
continue;
}
-
out[key] = convertSchema(value);
}
- // Handle OAS nullable → anyOf with null (move all props into base branch)
- if (schema.nullable === true && out.type) {
- const base = { ...out };
- for (const k of Object.keys(out)) delete out[k];
- out.anyOf = [base, { type: "null" }];
- }
+ // Some OAS schemas declare properties without type: object; make it explicit.
+ if (out.properties && !out.type) out.type = "object";
- // anyOf unions: strip type/additionalProperties from parent (branches define types)
- if (out.anyOf && !out.properties) {
- delete out.type;
+ // Union schemas (e.g. Asset) declare additionalProperties: false as an OAS
+ // discriminator-context hint. In pure JSON Schema that bans every property
+ // (no sibling `properties`), failing all branches — the members define the
+ // object shape, so drop it.
+ if ((out.oneOf || out.anyOf) && !out.properties && out.additionalProperties === false) {
delete out.additionalProperties;
}
- // Reduce or strip large enums to stay under Cerebras string length limit
- if (
- out.enum &&
- out.enum.reduce((sum, v) => sum + String(v).length, 0) > MAX_ENUM_CHARS
- ) {
- const reduced = reduceEnum(out.enum);
- if (
- reduced.reduce((sum, v) => sum + String(v).length, 0) <= MAX_ENUM_CHARS
- ) {
- out.enum = reduced;
- } else {
- delete out.enum;
- }
- }
-
- // Strict mode: untyped schemas default to string
- if (
- !out.type &&
- !out.$ref &&
- !out.anyOf &&
- !out.enum &&
- !out.properties &&
- !out.items &&
- out.description
- ) {
- out.type = "string";
- }
-
- // Strict mode: schemas with properties must have type: "object"
- if (out.properties && !out.type) {
- out.type = "object";
+ if (schema.nullable === true) {
+ if (out.$ref) return { anyOf: [{ $ref: out.$ref }, { type: "null" }] };
+ if (out.type && !Array.isArray(out.type)) out.type = [out.type, "null"];
}
-
- // Strict mode: objects need additionalProperties: false
- if (out.type === "object" && out.properties) {
- out.additionalProperties = false;
- }
-
- // Strict mode: all properties must be required, optional ones become nullable
- if (out.properties) {
- const originalRequired = new Set(schema.required || []);
- const allKeys = Object.keys(out.properties);
-
- for (const key of allKeys) {
- if (!originalRequired.has(key)) {
- out.properties[key] = makeNullable(out.properties[key]);
- }
- }
-
- out.required = allKeys;
- }
-
return out;
}
-// Collect all $ref dependencies for a schema (transitive)
-function collectDeps(schema, allDefs) {
- const deps = new Set();
- function walk(obj) {
- if (!obj || typeof obj !== "object") return;
- if (Array.isArray(obj)) {
- obj.forEach(walk);
- return;
- }
- if (obj.$ref && typeof obj.$ref === "string") {
- const match = obj.$ref.match(/^#\/\$defs\/(.+?)(?:\/|$)/);
- if (match && !deps.has(match[1])) {
- deps.add(match[1]);
- if (allDefs[match[1]]) walk(allDefs[match[1]]);
- }
+function collectDeps(schema, allDefs, deps = new Set()) {
+ if (!schema || typeof schema !== "object") return deps;
+ if (Array.isArray(schema)) {
+ schema.forEach((s) => collectDeps(s, allDefs, deps));
+ return deps;
+ }
+ if (typeof schema.$ref === "string") {
+ const name = schema.$ref.replace("#/$defs/", "");
+ if (allDefs[name] && !deps.has(name)) {
+ deps.add(name);
+ collectDeps(allDefs[name], allDefs, deps);
}
- for (const v of Object.values(obj)) walk(v);
}
- walk(schema);
+ Object.values(schema).forEach((v) => collectDeps(v, allDefs, deps));
return deps;
}
-// Collect all description strings with their paths for truncation
-function collectDescriptions(obj, path, result) {
- if (!obj || typeof obj !== "object") return;
- if (Array.isArray(obj)) {
- obj.forEach((v, i) => collectDescriptions(v, [...path, i], result));
- return;
- }
- for (const [k, v] of Object.entries(obj)) {
- if (k === "description" && typeof v === "string") {
- result.push({ path: [...path, k], length: v.length });
- }
- collectDescriptions(v, [...path, k], result);
- }
-}
-
-// Set a value at a nested path
-function setAtPath(obj, pathArr, value) {
- let current = obj;
- for (let i = 0; i < pathArr.length - 1; i++) {
- current = current[pathArr[i]];
- }
- current[pathArr[pathArr.length - 1]] = value;
-}
-
-// Get a value at a nested path
-function getAtPath(obj, pathArr) {
- let current = obj;
- for (const key of pathArr) {
- current = current[key];
- }
- return current;
-}
-
-// Truncate descriptions proportionally to fit within maxChars
-function fitToSize(output, maxChars) {
- let json = JSON.stringify(output);
- if (json.length <= maxChars) return output;
-
- // Deep clone to avoid mutating original
- const clone = JSON.parse(json);
-
- // Collect all descriptions
- const descs = [];
- collectDescriptions(clone, [], descs);
- if (descs.length === 0) return clone;
-
- const totalDescChars = descs.reduce((sum, d) => sum + d.length, 0);
- const excess = json.length - maxChars;
-
- if (excess >= totalDescChars) {
- // Even removing all descriptions won't be enough — strip them all
- for (const d of descs) setAtPath(clone, d.path, "");
- // Remove empty description keys
- stripEmptyDescriptions(clone);
- return clone;
- }
-
- // Calculate max length per description (proportional reduction)
- const ratio = 1 - excess / totalDescChars;
- for (const d of descs) {
- const maxLen = Math.max(0, Math.floor(d.length * ratio));
- const current = getAtPath(clone, d.path);
- if (current.length > maxLen) {
- setAtPath(
- clone,
- d.path,
- maxLen > 3 ? current.slice(0, maxLen - 3) + "..." : "",
- );
- }
- }
-
- // Verify and do a second pass if still over (due to JSON escaping)
- json = JSON.stringify(clone);
- if (json.length > maxChars) {
- const stillOver = json.length - maxChars;
- const remaining = [];
- collectDescriptions(clone, [], remaining);
- const totalRemaining = remaining.reduce((sum, d) => sum + d.length, 0);
- if (totalRemaining > 0) {
- const ratio2 = Math.max(0, 1 - stillOver / totalRemaining - 0.1);
- for (const d of remaining) {
- const current = getAtPath(clone, d.path);
- const maxLen = Math.max(0, Math.floor(current.length * ratio2));
- if (current.length > maxLen) {
- setAtPath(
- clone,
- d.path,
- maxLen > 3 ? current.slice(0, maxLen - 3) : "",
- );
- }
- }
- }
- }
-
- stripEmptyDescriptions(clone);
- return clone;
-}
-
-function stripEmptyDescriptions(obj) {
- if (!obj || typeof obj !== "object") return;
- if (Array.isArray(obj)) {
- obj.forEach(stripEmptyDescriptions);
- return;
- }
- if (obj.description === "") delete obj.description;
- for (const v of Object.values(obj)) stripEmptyDescriptions(v);
-}
-
-// Convert all schemas (only non-excluded)
const allDefs = {};
for (const [name, schema] of Object.entries(oasSchemas)) {
- if (isExcluded(name)) continue;
allDefs[name] = convertSchema(schema);
}
-// Collect Edit API schemas: Edit + all transitive deps
const editDeps = collectDeps(allDefs.Edit, allDefs);
-editDeps.add("Edit");
-const defs = {};
-for (const name of editDeps) {
- if (allDefs[name]) defs[name] = allDefs[name];
-}
+const $defs = {};
+for (const name of [...editDeps].sort()) $defs[name] = allDefs[name];
+
+const output = {
+ $schema: "https://json-schema.org/draft/2020-12/schema",
+ title: "Edit",
+ ...allDefs.Edit,
+ $defs,
+};
-// Clean and recreate output directory
fs.rmSync(OUT_DIR, { recursive: true, force: true });
fs.mkdirSync(OUT_DIR, { recursive: true });
-
-let totalFiles = 0;
-let overLimit = 0;
-
-for (const [name, schema] of Object.entries(defs)) {
- const deps = collectDeps(schema, defs);
- const localDefs = {};
- for (const dep of deps) {
- if (defs[dep]) localDefs[dep] = defs[dep];
- }
-
- const output = {
- name,
- strict: true,
- schema: {
- ...schema,
- ...(Object.keys(localDefs).length > 0 ? { $defs: localDefs } : {}),
- },
- };
-
- const fitted = fitToSize(output, MAX_CHARS);
- if (JSON.stringify(fitted).length > MAX_CHARS) overLimit++;
-
- const fileName =
- name.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase() + ".json";
- fs.writeFileSync(
- path.join(OUT_DIR, fileName),
- JSON.stringify(fitted, null, 2) + "\n",
- );
- totalFiles++;
-}
-
-// Also output combined schemas.json for general use (no size limit)
fs.writeFileSync(
- path.join(OUT_DIR, "schemas.json"),
- JSON.stringify({ $defs: defs }, null, 2) + "\n",
-);
-
-// Report
-const files = fs
- .readdirSync(OUT_DIR)
- .filter((f) => f.endsWith(".json") && f !== "schemas.json");
-const sizes = files.map((f) => ({
- name: f,
- chars: JSON.stringify(
- JSON.parse(fs.readFileSync(path.join(OUT_DIR, f), "utf8")),
- ).length,
-}));
-const under = sizes.filter((s) => s.chars <= MAX_CHARS).length;
-const editSize = sizes.find((s) => s.name === "edit.json");
-
-console.log(`Generated ${totalFiles} Edit API schema files + schemas.json`);
-console.log(` ${under}/${totalFiles} under ${MAX_CHARS} chars`);
-if (overLimit > 0) console.log(` ${overLimit} over limit`);
-if (editSize) console.log(` edit.json: ${editSize.chars} chars`);
-
-// ---------------------------------------------------------------------------
-// Multi-pass LLM template generation schemas.
-// Each schema must fit within the Cerebras 5,000-char strict-mode limit.
-//
-// Pipeline:
-// 1. blueprint.json — timeline structure (tracks/clips with asset type
-// strings, timing, transitions, mergeField hints) + output + merge
-// 2. Per-asset-type detailer schemas — generate asset objects in isolation:
-// - rich-text-content.json — text, font, background, border, padding, align
-// - rich-text-effects.json — style, stroke, shadow, gradient, animation
-// - caption-detailer.json — full CaptionAsset with font, background, margin
-// - template.json — simple assets (Video/Image/Audio) as single-call fallback
-// ---------------------------------------------------------------------------
-
-// Remove all descriptions from a schema tree
-function stripDescriptions(obj) {
- if (!obj || typeof obj !== "object") return obj;
- if (Array.isArray(obj)) return obj.map(stripDescriptions);
- const out = {};
- for (const [k, v] of Object.entries(obj)) {
- if (k === "description") continue;
- out[k] = stripDescriptions(v);
- }
- return out;
-}
-
-// Deep clone and strip descriptions from a $def
-function cloneDef(name) {
- return stripDescriptions(JSON.parse(JSON.stringify(defs[name])));
-}
-
-// Strip named properties from a schema and rebuild its required array
-function stripProps(schema, props) {
- const s = JSON.parse(JSON.stringify(schema));
- for (const p of props) {
- delete s.properties[p];
- }
- if (s.required) {
- s.required = s.required.filter((r) => !props.has(r));
- }
- return s;
-}
-
-// Remove $ref branches pointing to defs not in an allowed set
-function filterRefs(obj, allowed) {
- if (!obj || typeof obj !== "object") return obj;
- if (Array.isArray(obj)) {
- return obj
- .filter((item) => {
- if (item && item.$ref) {
- const m = item.$ref.match(/^#\/\$defs\/(.+?)(?:\/|$)/);
- if (m && !allowed.has(m[1])) return false;
- }
- return true;
- })
- .map((item) => filterRefs(item, allowed));
- }
- const out = {};
- for (const [k, v] of Object.entries(obj)) {
- if (k === "$ref" && typeof v === "string") {
- const m = v.match(/^#\/\$defs\/(.+?)(?:\/|$)/);
- if (m && !allowed.has(m[1])) continue;
- }
- out[k] = filterRefs(v, allowed);
- }
- return out;
-}
-
-// Remove orphaned array branches left after ref filtering (e.g. Tween arrays)
-function cleanOrphanedArrays(obj) {
- if (!obj || typeof obj !== "object") return obj;
- if (Array.isArray(obj)) return obj.map(cleanOrphanedArrays);
- if (obj.anyOf) {
- obj.anyOf = obj.anyOf.filter((branch) => {
- if (branch.type === "array" && branch.items) {
- const items = branch.items;
- return items.type || items.$ref || items.anyOf || items.properties;
- }
- return true;
- });
- if (obj.anyOf.length === 1) return cleanOrphanedArrays(obj.anyOf[0]);
- }
- const out = {};
- for (const [k, v] of Object.entries(obj)) {
- out[k] = cleanOrphanedArrays(v);
- }
- return out;
-}
-
-// Write a schema file and report its size
-function writeSchema(name, fileName, schema) {
- const output = { name, strict: true, schema };
- const json = JSON.stringify(output);
- fs.writeFileSync(
- path.join(OUT_DIR, fileName),
- JSON.stringify(output, null, 2) + "\n",
- );
- const status = json.length <= MAX_CHARS ? "OK" : "OVER";
- console.log(` ${fileName}: ${json.length} chars [${status}]`);
- if (json.length > MAX_CHARS) {
- console.log(
- ` WARNING: exceeds ${MAX_CHARS} limit by ${json.length - MAX_CHARS}`,
- );
- }
- return json.length;
-}
-
-// --- blueprint.json ---
-// Full edit structure but asset is just a type string + mergeField + textHint
-const blueprintTransition = cloneDef("Transition");
-const blueprintOutput = stripProps(
- cloneDef("Output"),
- new Set([
- "size",
- "scaleTo",
- "repeat",
- "mute",
- "range",
- "poster",
- "thumbnail",
- "destinations",
- ]),
-);
-const blueprintMergeField = cloneDef("MergeField");
-
-const blueprintClip = {
- type: "object",
- properties: {
- asset: {
- type: "string",
- enum: ["video", "image", "audio", "rich-text", "svg", "caption"],
- },
- start: { anyOf: [{ type: "number", minimum: 0 }, { type: "string" }] },
- length: { anyOf: [{ type: "number", minimum: 0 }, { type: "string" }] },
- fit: {
- anyOf: [
- { type: "string", enum: ["cover", "contain", "crop", "none"] },
- { type: "null" },
- ],
- },
- position: {
- anyOf: [
- {
- type: "string",
- enum: [
- "top",
- "topRight",
- "right",
- "bottomRight",
- "bottom",
- "bottomLeft",
- "left",
- "topLeft",
- "center",
- ],
- },
- { type: "null" },
- ],
- },
- transition: {
- anyOf: [{ $ref: "#/$defs/Transition" }, { type: "null" }],
- },
- effect: { anyOf: [{ type: "string" }, { type: "null" }] },
- mergeField: { anyOf: [{ type: "string" }, { type: "null" }] },
- textHint: { anyOf: [{ type: "string" }, { type: "null" }] },
- },
- additionalProperties: false,
- required: [
- "asset",
- "start",
- "length",
- "fit",
- "position",
- "transition",
- "effect",
- "mergeField",
- "textHint",
- ],
-};
-
-writeSchema("Blueprint", "blueprint.json", {
- type: "object",
- properties: {
- output: { $ref: "#/$defs/Output" },
- merge: {
- anyOf: [
- { type: "array", items: { $ref: "#/$defs/MergeField" } },
- { type: "null" },
- ],
- },
- timeline: {
- type: "object",
- properties: {
- tracks: {
- type: "array",
- items: {
- type: "object",
- properties: {
- clips: {
- type: "array",
- items: { $ref: "#/$defs/BlueprintClip" },
- },
- },
- additionalProperties: false,
- required: ["clips"],
- },
- },
- },
- additionalProperties: false,
- required: ["tracks"],
- },
- },
- additionalProperties: false,
- required: ["output", "merge", "timeline"],
- $defs: {
- BlueprintClip: blueprintClip,
- Transition: blueprintTransition,
- Output: blueprintOutput,
- MergeField: blueprintMergeField,
- },
-});
-
-// --- rich-text-content.json ---
-// RichTextAsset with font, background, border, padding, align (no effects)
-const rtContentAsset = stripProps(
- cloneDef("RichTextAsset"),
- new Set(["style", "stroke", "shadow", "animation"]),
+ path.join(OUT_DIR, "edit.json"),
+ JSON.stringify(output, null, 2) + "\n",
);
-const rtContentFont = stripProps(cloneDef("RichTextFont"), new Set(["stroke"]));
-const rtContentDefs = new Set([
- "RichTextAsset",
- "RichTextFont",
- "RichTextBackground",
- "RichTextAlignment",
-]);
-const rtContentFiltered = filterRefs(rtContentAsset, rtContentDefs);
-
-writeSchema("RichTextContent", "rich-text-content.json", {
- type: "object",
- properties: {
- assets: { type: "array", items: { $ref: "#/$defs/RichTextAsset" } },
- },
- additionalProperties: false,
- required: ["assets"],
- $defs: {
- RichTextAsset: rtContentFiltered,
- RichTextFont: rtContentFont,
- RichTextBackground: cloneDef("RichTextBackground"),
- RichTextAlignment: cloneDef("RichTextAlignment"),
- },
-});
-
-// --- rich-text-effects.json ---
-// Style, stroke, shadow, gradient, animation per asset
-writeSchema("RichTextEffects", "rich-text-effects.json", {
- type: "object",
- properties: {
- effects: { type: "array", items: { $ref: "#/$defs/RichTextEffect" } },
- },
- additionalProperties: false,
- required: ["effects"],
- $defs: {
- RichTextEffect: {
- type: "object",
- properties: {
- style: { anyOf: [{ $ref: "#/$defs/RichTextStyle" }, { type: "null" }] },
- stroke: {
- anyOf: [{ $ref: "#/$defs/RichTextStroke" }, { type: "null" }],
- },
- shadow: {
- anyOf: [{ $ref: "#/$defs/RichTextShadow" }, { type: "null" }],
- },
- animation: {
- anyOf: [{ $ref: "#/$defs/RichTextAnimation" }, { type: "null" }],
- },
- },
- additionalProperties: false,
- required: ["style", "stroke", "shadow", "animation"],
- },
- RichTextStyle: cloneDef("RichTextStyle"),
- RichTextStroke: cloneDef("RichTextStroke"),
- RichTextShadow: cloneDef("RichTextShadow"),
- RichTextGradient: cloneDef("RichTextGradient"),
- RichTextAnimation: cloneDef("RichTextAnimation"),
- },
-});
-
-// --- caption-detailer.json ---
-writeSchema("CaptionDetails", "caption-detailer.json", {
- type: "object",
- properties: {
- assets: { type: "array", items: { $ref: "#/$defs/CaptionAsset" } },
- },
- additionalProperties: false,
- required: ["assets"],
- $defs: {
- CaptionAsset: cloneDef("CaptionAsset"),
- CaptionFont: cloneDef("CaptionFont"),
- CaptionBackground: cloneDef("CaptionBackground"),
- CaptionMargin: cloneDef("CaptionMargin"),
- },
-});
-
-// --- template.json ---
-// Single-call fallback for simple templates (Video/Image/Audio only)
-const TEMPLATE_DEFS = new Set([
- "Timeline",
- "Track",
- "Clip",
- "Asset",
- "VideoAsset",
- "ImageAsset",
- "AudioAsset",
- "Transition",
- "Output",
- "MergeField",
-]);
-const TEMPLATE_STRIP_PROPS = {
- Timeline: new Set(["soundtrack", "background", "fonts", "cache"]),
- Clip: new Set([
- "scale",
- "width",
- "height",
- "offset",
- "filter",
- "opacity",
- "transform",
- "alias",
- ]),
- Output: new Set([
- "size",
- "scaleTo",
- "repeat",
- "mute",
- "range",
- "poster",
- "thumbnail",
- "destinations",
- ]),
- VideoAsset: new Set(["crop", "chromaKey", "transcode"]),
- ImageAsset: new Set(["crop"]),
- AudioAsset: new Set(["speed"]),
-};
-
-const templateDefs = {};
-for (const name of TEMPLATE_DEFS) {
- if (!defs[name]) continue;
- let schema = cloneDef(name);
- if (TEMPLATE_STRIP_PROPS[name]) {
- schema = stripProps(schema, TEMPLATE_STRIP_PROPS[name]);
- }
- schema = filterRefs(schema, TEMPLATE_DEFS);
- schema = cleanOrphanedArrays(schema);
- templateDefs[name] = schema;
-}
-writeSchema("Template", "template.json", {
- type: "object",
- properties: {
- timeline: { $ref: "#/$defs/Timeline" },
- output: { $ref: "#/$defs/Output" },
- merge: {
- anyOf: [
- { type: "array", items: { $ref: "#/$defs/MergeField" } },
- { type: "null" },
- ],
- },
- },
- additionalProperties: false,
- required: ["timeline", "output", "merge"],
- $defs: templateDefs,
-});
-
-// Generate barrel files for module imports
+// Barrel files so `@shotstack/schemas/json` resolves for both module systems.
fs.writeFileSync(
path.join(OUT_DIR, "index.js"),
- [
- "import { createRequire } from 'module';",
- "const require = createRequire(import.meta.url);",
- "export const edit = require('./edit.json');",
- "export const template = require('./template.json');",
- "export const blueprint = require('./blueprint.json');",
- "export const richTextContent = require('./rich-text-content.json');",
- "export const richTextEffects = require('./rich-text-effects.json');",
- "export const captionDetailer = require('./caption-detailer.json');",
- "",
- ].join("\n"),
+ `import { createRequire } from 'module';\nconst require = createRequire(import.meta.url);\nexport const edit = require('./edit.json');\n`,
);
-
fs.writeFileSync(
path.join(OUT_DIR, "index.cjs"),
- [
- "module.exports.edit = require('./edit.json');",
- "module.exports.template = require('./template.json');",
- "module.exports.blueprint = require('./blueprint.json');",
- "module.exports.richTextContent = require('./rich-text-content.json');",
- "module.exports.richTextEffects = require('./rich-text-effects.json');",
- "module.exports.captionDetailer = require('./caption-detailer.json');",
- "",
- ].join("\n"),
+ `module.exports = { edit: require('./edit.json') };\n`,
);
-
fs.writeFileSync(
path.join(OUT_DIR, "index.d.ts"),
- [
- "export interface JsonSchema {",
- " name: string;",
- " strict: boolean;",
- " schema: Record;",
- "}",
- "export declare const edit: JsonSchema;",
- "export declare const template: JsonSchema;",
- "export declare const blueprint: JsonSchema;",
- "export declare const richTextContent: JsonSchema;",
- "export declare const richTextEffects: JsonSchema;",
- "export declare const captionDetailer: JsonSchema;",
- "",
- ].join("\n"),
+ `export declare const edit: Record;\n`,
);
-console.log("Generated barrel files: index.js, index.cjs, index.d.ts");
+console.log(
+ `Generated edit.json (${Object.keys($defs).length} $defs, ${(JSON.stringify(output).length / 1024).toFixed(1)} KB) + barrel files`,
+);
diff --git a/tests/smoke.cjs b/tests/smoke.cjs
index 968a9ee..fc5e09a 100644
--- a/tests/smoke.cjs
+++ b/tests/smoke.cjs
@@ -388,6 +388,52 @@ async function run() {
assert.ok(typeof mod.edit === "object", "edit export not found");
});
+ console.log("\n--- JSON Schema validation checks ---\n");
+
+ const Ajv2020 = require("ajv/dist/2020");
+ const ajv = new Ajv2020({ strict: true, validateFormats: false });
+ const editJsonSchema = require(path.join(distDir, "json-schema/edit.json"));
+ let validateEdit;
+
+ check("edit.json compiles under ajv strict (2020-12)", () => {
+ validateEdit = ajv.compile(editJsonSchema);
+ });
+
+ const baseEdit = (asset) => ({
+ timeline: { tracks: [{ clips: [{ asset, start: 0, length: 3 }] }] },
+ output: { format: "mp4", resolution: "hd" },
+ });
+
+ const schemaCases = [
+ ["accepts a valid rich-text edit", baseEdit({ type: "rich-text", text: "Hello" }), true],
+ ["accepts a valid video edit", baseEdit({ type: "video", src: "https://x.com/a.mp4" }), true],
+ ["accepts deprecated title asset", baseEdit({ type: "title", text: "Old" }), true],
+ ["rejects unknown asset property", baseEdit({ type: "video", src: "https://x.com/a.mp4", bogus: 1 }), false],
+ ["rejects missing output", { timeline: { tracks: [] } }, false],
+ ];
+
+ const sepiaEdit = baseEdit({ type: "video", src: "https://x.com/a.mp4" });
+ sepiaEdit.timeline.tracks[0].clips[0].filter = "sepia";
+ schemaCases.push(["rejects invalid filter enum value", sepiaEdit, false]);
+
+ const soundtrackEdit = baseEdit({ type: "video", src: "https://x.com/a.mp4" });
+ soundtrackEdit.timeline.soundtrack = { src: "https://x.com/a.mp3", effect: "fadeIn" };
+ schemaCases.push(["accepts deprecated soundtrack", soundtrackEdit, true]);
+
+ for (const [label, edit, expected] of schemaCases) {
+ check(label, () => {
+ assert.ok(validateEdit, "schema did not compile");
+ const ok = validateEdit(edit);
+ assert.strictEqual(
+ ok,
+ expected,
+ expected
+ ? `Expected valid, got: ${JSON.stringify((validateEdit.errors || []).slice(0, 2))}`
+ : "Expected validation to fail but it passed"
+ );
+ });
+ }
+
console.log("\n========================================");
console.log(` Results: ${passed} passed, ${failed} failed`);
console.log("========================================\n");