apiext-format

.apiext is an extended element-API format for WebObjects (and ng-objects) dynamic elements — the successor to WO's .api format, keeping its skeleton and adding what an element's bindings deserve: per-element and per-binding documentation, binding types, directionality, value interpretation, and typed cross-binding constraints. Enough to render an element's API in an editor and to check templates against it. (Legacy .api files aren't valid .apiext — their validation language was replaced — but converting them is mechanical.)

This repository is the format specification: the grammar, the field-by-field spec, illustrative examples, and status. It is implementation-agnostic — a reference parser may live here later, but the format is defined independently of any consumer.

Contents

In brief

.api declares an element's bindings — names, a few flags, cross-binding validation — and nothing about what a binding means, its type, or its direction. .apiext keeps its skeleton and adds all of that; the legacy areas whose only purpose was compatibility are removed rather than carried (the <validation> predicate language → typed constraints, settable → <push>, and the rest — each removal issue-tracked), with legacy files handled by a mechanical converter rather than by the grammar. The WO runtime does not read .api (only tooling does — WOBuilder, WOLips, Parsley), so the format is constrained only by "don't strand existing files" — and conversion, not compatibility, is how they're kept un-stranded.

<wodefinitions>
  <wo class="WOCheckBox" wrapsContent="false" unknownAttributes="passthrough">

    <doc><![CDATA[A checkbox. Use **either** `checked` or `value`+`selection`.]]></doc>

    <binding name="checked">
      <pull><type interpretation="truthy">java.lang.Object</type></pull>
      <push><type>java.lang.Boolean</type></push>
      <doc>The checked state.</doc>
    </binding>

  </wo>
</wodefinitions>

See FORMAT.md for the full walkthrough — documentation, types, directionality (<pull>/<push>), and interpretation (interpretation="truthy").

Status

Proposal stage; in use. The format drives the AjaxSlim element reference (in the wonder-slim repository) and a WOLips plugin preview. The vocabulary is still settling — see DONE.md for what's present and ROADMAP.md for what's open.