ograf.json specification
The HTML animation package contract used by ograf.app and OGRAF Creator Skill: upload files, editable parameters, playback messages and exported manifests. Other OGRAF hosts may have different requirements.
Back to the development guidePackage layout
Place project.json and index.html at the ZIP root and reference assets with relative paths. The upload API also accepts one containing directory. Skill packages usually use .ograf; website downloads use .og.zip. Both are ZIP archives. A .ograf.json file alone cannot replace the two required upload entries.
title.ograf / title-a1b2c3d4.og.zip
├── project.json
├── index.html
├── zh.ograf.json
├── en.ograf.json
└── assets/ (optional)project.json fields
| format / formatVersion | Skill baseline: "ograf" / 1. |
| name / description / version | Name, description and version, such as 1.0.0. The Skill requires name. |
| resolution / fps / duration | Design resolution (1920x1080), frames per second and duration in seconds. Use positive values matching the animation. |
| supportsLandscape / supportsPortrait | Declare supported orientations and verify their visuals and controls. |
| data | Current parameter values, required by the Skill. Keys match schema.properties. |
| schema | A JSON Schema with root type object, required by the Skill. properties describes editable parameters. |
| renderRequirements | Recommended design dimensions, frame rate and accessToPublicInternet: false. Website resources must be self-contained. |
This is the portable Skill baseline. The upload API currently requires a valid JSON object and scans package files; passing upload validation does not prove all metadata, playback or visuals are correct.
project.json for a simple title animation
{
"format": "ograf",
"formatVersion": 1,
"name": "标题淡入",
"description": "透明背景的标题淡入动画",
"version": "1.0.0",
"resolution": "1920x1080",
"fps": 30,
"duration": 3,
"supportsLandscape": true,
"supportsPortrait": false,
"data": {
"title": "你好,OGRAF",
"color": "#ffffff",
"fontSize": 96,
"font": "sans-serif",
"data": [],
"x": 0,
"y": 0,
"scale": 1,
"useOutro": true,
"useIntro": true,
"animationSpeed": 1
},
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"title": "标题",
"default": "你好,OGRAF"
},
"color": {
"type": "string",
"title": "颜色",
"format": "color",
"default": "#ffffff"
},
"fontSize": {
"type": "number",
"title": "字号",
"minimum": 24,
"maximum": 200,
"default": 96
},
"font": {
"type": "string",
"title": "字体",
"gddType": "font",
"default": "sans-serif"
},
"data": {
"type": "array",
"title": "数据",
"items": {
"type": "object"
},
"default": []
},
"x": {
"type": "number",
"title": "X",
"default": 0
},
"y": {
"type": "number",
"title": "Y",
"default": 0
},
"scale": {
"type": "number",
"title": "缩放",
"minimum": 0.1,
"maximum": 3,
"multipleOf": 0.01,
"default": 1
},
"useOutro": {
"type": "boolean",
"title": "是否使用出场动画",
"default": true
},
"useIntro": {
"type": "boolean",
"title": "是否使用入场动画",
"default": true
},
"animationSpeed": {
"type": "number",
"title": "动画速度",
"minimum": 0.1,
"default": 1
}
},
"required": [
"x",
"y",
"scale",
"useOutro",
"useIntro",
"animationSpeed"
]
},
"renderRequirements": {
"resolution": {
"width": 1920,
"height": 1080
},
"frameRate": 30,
"accessToPublicInternet": false
}
}Editable parameter schema
Describe parameters with type, title and default; description is optional. Use minimum / maximum for numbers and enum for choices. data values must match their types and initially agree with defaults.
| string | Text input |
| string + format: color | Color input |
| string + gddType: multi-line | Multiline text |
| enum | Select |
| number / integer | Numeric input with optional bounds |
| boolean | Toggle |
| array / object | JSON input in the Skill debugger; verify support in other hosts |
Every animation must include these six controls in schema.properties and schema.required. Keep data, schema.default and field defaults aligned. The implementation must apply each control; disabling intro or outro immediately shows the corresponding state.
| x / y | X / Y; number, default 0, control position. |
| scale | Scale; number, default 1 (original size), shown as a slider. minimum, maximum and multipleOf define bounds and step. |
| useOutro | Use outro animation; boolean, default true. |
| useIntro | Use intro animation; boolean, default true. |
| animationSpeed | Animation speed; number, default 1, strictly positive. Apply the multiplier to intro and outro playback. |
| Font: font | string with gddType: font for font selection; hosts also recognize fontFamily. Store a font family name and let the host discover fonts on the current computer. Do not hardcode local font file paths. |
| Data: data | schema.properties.data is an editable array / object of structured JSON. It is distinct from top-level project.json data, which holds all parameter values. Store this field in data.data or schema.default.data. |
| Scale: scale | number, with 1 representing original size. Use a numeric multiplier rather than a percentage string; transform stage content together with X and Y. |
.ograf.json export manifest
HTML downloads preserve project.json, index.html and assets while saving current parameters. Provide Chinese and English manifests as zh.ograf.json and en.ograf.json. Both share parameter keys, types and behavior, with localized titles and copy. schema.properties describes controls, schema.default stores downloaded values and field defaults are synchronized. Its filename includes a random eight-character hexadecimal ID, such as title-a1b2c3d4.zh.ograf.json and title-a1b2c3d4.en.ograf.json, to reduce stale DaVinci cache reuse. Downloads keep the selected-language manifest; existing manifests without a language suffix remain a compatibility fallback.
{
"name": "Title fade",
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string",
"title": "Title",
"default": "Hello, OGRAF"
},
"color": {
"type": "string",
"title": "Color",
"format": "color",
"default": "#ffffff"
},
"fontSize": {
"type": "number",
"title": "Font size",
"minimum": 24,
"maximum": 200,
"default": 96
},
"font": {
"type": "string",
"title": "Font",
"gddType": "font",
"default": "sans-serif"
},
"data": {
"type": "array",
"title": "Data",
"items": {
"type": "object"
},
"default": []
},
"x": {
"type": "number",
"title": "X",
"default": 0
},
"y": {
"type": "number",
"title": "Y",
"default": 0
},
"scale": {
"type": "number",
"title": "Scale",
"minimum": 0.1,
"maximum": 3,
"multipleOf": 0.01,
"default": 1
},
"useOutro": {
"type": "boolean",
"title": "Use outro animation",
"default": true
},
"useIntro": {
"type": "boolean",
"title": "Use intro animation",
"default": true
},
"animationSpeed": {
"type": "number",
"title": "Animation speed",
"minimum": 0.1,
"default": 1
}
},
"required": [
"x",
"y",
"scale",
"useOutro",
"useIntro",
"animationSpeed"
],
"default": {
"title": "Hello, OGRAF",
"color": "#ffffff",
"fontSize": 96,
"font": "sans-serif",
"data": [],
"x": 0,
"y": 0,
"scale": 1,
"useOutro": true,
"useIntro": true,
"animationSpeed": 1
}
}
}This example is the website HTML configuration manifest, not a complete entry specification for every desktop OGRAF host. Existing desktop archives may require main and other fields; preserve their original entry points.
HTML playback protocol
For DaVinci, main.js exports an HTMLElement subclass and the native .ograf.json points main to it. Mount the visible stage directly on document.body. Canvas dimensions come first from load({renderCharacteristics}).resolution.width/height, ahead of host-box or viewport dimensions. A requested 1080×1920 portrait canvas must not fit into a stale 1920×1080 host box. Scale previews only when host and canvas aspect ratios match. Clean up the stage, listeners and animation work on disposal. Website index.html reuses that implementation inside sandbox="allow-scripts" with window.postMessage, without parent.document or allow-same-origin.
| Host → graphic | ograf:update | data contains parameters. Update without reloading or automatically replaying. |
| Host → graphic | ograf:start | Start from a known initial frame; repeated starts replay. |
| Host → graphic | ograf:stop | Cancel timers and animation work; return to a consistent resting state. |
| Graphic → host | ograf:ready | Notify after the DOM, assets and listeners are ready. |
| Graphic → host | ograf:ended | Notify when a non-looping animation reaches its final frame. |
| Graphic → host | ograf:error | Provide a readable diagnostic in error. |
// Host → graphic
{ type: 'ograf:update', data: { title: 'Hello, OGRAF' } }
{ type: 'ograf:start' }
{ type: 'ograf:stop' }
// Graphic → host
parent.postMessage({ type: 'ograf:ready' }, '*');
parent.postMessage({ type: 'ograf:ended' }, '*');
parent.postMessage({ type: 'ograf:error', error: 'Playback failed' }, '*');Use parent.postMessage(message, "*") for opaque-origin frames. The graphic validates event.source === parent; the host validates the target iframe.contentWindow. Updates are idempotent; stopping or replaying clears old work. Render user text with textContent.
Resources and upload limits
| Compressed ZIP | ≤ 500 KiB |
| Individual JS / MJS | ≤ 500 KiB; inline HTML scripts are also scanned |
| Individual image | ≤ 1 MiB |
| File count | ≤ 200 |
| Total uncompressed size | ≤ 2 MiB |
| Video | Forbidden, including files disguised with another extension |
Allowed: HTML, JS/MJS, CSS, JSON, PNG/JPEG/GIF/WebP/SVG/AVIF, WOFF/WOFF2/TTF/OTF and TXT/MD. Scripts, styles, fonts and images use local relative paths. External resources, network requests, dynamic code execution and sensitive APIs such as cookies or storage are rejected. No traversal, absolute paths, duplicate entries, symlinks or corrupt ZIP files. The server scans actual decompressed contents; static scanning is not a complete security guarantee. 1 KiB = 1024 bytes.
Before publication
- Validate locally and include both entries with complete relative assets.
- Inspect real previews and immediate title, color and font-size updates.
- Check playback, stop, consecutive replay and completion messages without stale work.
- Verify transparency, design resolution and declared orientations.
- Upload a draft through the Skill, publish it, then verify the public preview and downloaded package.