Skip to content
Ooidget

Ooidget Component Format 0.1Editor's Draft

Ooidget Component Format 0.1

This version
0.1, Editor's Draft, 27 October 2026
Latest published
none yet
Editors
Andrei Zinca (Zeneka)
Repository
github.com/Ooidget/spec
Licence
text CC BY 4.0; schema and tests MIT

Abstract

The Ooidget Component Format defines interactive user interface components as data. A component is a JSON document that declares its initial state, an ordered list of layers drawn from that state, the components it contains, how they are laid out, and a behaviour that maps input events to changes of state. A conforming runtime reads such documents and renders them, on any platform, with the same appearance and the same response to input.

The format specifies only its component model. For expressions it references ECMAScript; for layout, CSS Flexible Box Layout and CSS positioning; for drawing, SVG and CSS painting; for colour, CSS Color; for design tokens, the W3C Design Tokens Community Group format; for accessibility, WAI-ARIA.

Status of this document

This is an Editor’s Draft, published for review. It has not been implemented interoperably and may change in any way, including incompatibly, before a version 1.0 is published. Implementers should not depend on it for products and should follow the repository for changes.

The format described here generalises one that has been in production use in Ooidget UI, with a native runtime in C++ and a web runtime in JavaScript. Where that practice and this document differ, this document is the target; the changes page lists the differences.

Comments are welcome as issues in the repository.

Conformance

The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY and OPTIONAL in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

All sections are normative except those marked non-normative, and except examples and notes. Requirements phrased as algorithms (“run these steps”) may be implemented in any manner, provided the result is equivalent.

This specification defines conformance for two classes of product, set out in Conformance:

  • a document: an Ooidget file; and
  • a runtime: software that loads documents, maintains their state and renders them, in one of the profiles Static, Interactive, Application and Full.

Document conventions

JSON terminology (object, member, array, string, number, true, false, null) is that of RFC 8259 [RFC8259]. “Member x” means the member of an object whose name is x.

Property definitions are given in tables with the columns Property, Type, Required and Description. A type written number | string accepts either JSON type. A type written Expression<T> accepts a literal of type T or a string that is an expression evaluating to T.

Examples are written in JSON and are non-normative:

{
  "spec": "0.1",
  "about": "A toggle button.",
  "widget": {
    "size": [28, 22],
    "state": { "on": false },
    "layers": [
      { "shape": "rect", "radius": 5, "effects": [{ "type": "fill", "color": "#2a2b31" }] },
      { "shape": "rect", "radius": 5, "effects": [{ "type": "fill", "color": "#4a78c0" }], "when": "s.on" }
    ],
    "behaviour": "({ click(s) { return { on: !s.on } } })"
  }
}

Versioning

This specification is versioned major.minor. A minor version only adds; a document valid under 1.n is valid under 1.n+1 and renders the same. A major version may change the meaning of existing documents.

A document declares the version it was written for in its spec member. A runtime MUST NOT refuse a document whose minor version is higher than the one it implements; it renders what it understands and applies the fallback rules to the rest.