The format, precisely

Install

The reference implementation is a single zero-dependency package: validator, curve math, SVG renderer, React wrapper, headless export, adapters, and CLI.

Quick start

Fetch a document, validate it, render it. The renderer draws into any container and returns a handle with update() and destroy().

import { render, validate } from "open-lec";

const doc = await fetch("/my-lec.json").then((r) => r.json());
const result = validate(doc);

if (result.valid) {
  render(document.querySelector("#chart"), doc, { logX: true });
} else {
  console.error(result.errors);   // [{ path, message }, …]
}

Your first document

Four points and a currency make a conforming curve. Points sample the exceedance function P(annual loss ≥ loss).

Paste it into the playground and break it on purpose — reorder the losses, push a probability above an earlier one — to watch the validator name the exact path and rule.

Document structure

An open-lec document is a single UTF-8 JSON object with three required members and one optional one.

Metadata

Scenarios

A scenario is one curve — the current state, a projected state after a treatment plan, or one member of a portfolio comparison. Comparing a baseline against one or more treatment scenarios is the canonical board visual.

Curves & interpolation

A curve is at least two samples of the exceedance function, under four semantic rules the validator enforces:

• loss is finite and ≥ 0, in the metadata currency;
• p is finite, in [0, 1];
• losses are sorted strictly ascending — no duplicates;
• p is non-increasing — an exceedance function cannot rise.

Curves may declare how to interpolate between knots:

Below the first point the curve extends horizontally at p₀; above the last, at p_N. From the curve alone, compliant tooling derives exceedance probability at any loss, loss at any probability (VaR-style), return periods, and the expected annual loss — the exact per-segment integral under the declared profile, a lower bound when the final p is still > 0.

Uncertainty bands

Bands express an interval around the curve at a stated level, and 0.2 lets them say what kind of uncertainty they carry — the two kinds make very differently sized bands:

Reference lines

Document-level guide lines put governance context in the picture: risk tolerance, insurance attachment and limit, a 1-in-N probability line.

"referenceLines": [
  { "axis": "loss",        "value": 5000000, "label": "Risk tolerance" },
  { "axis": "probability", "value": 0.05,    "label": "1-in-20" }
]

Statistics

Optional precomputed summaries — mean, median, percentiles, sampleCount, observed extremes — so simple consumers can print headline numbers without math. Readers must never trust them over the curve; the reference tooling always re-derives.

Conformance & versioning

• A conforming document validates against the JSON Schema and satisfies the semantic rules — the reference validator checks both, and an agreement test suite keeps the two layers from drifting apart.
• A conforming reader ignores unknown keys, interpolates per the declared profile, and treats statistics as informative.
• Versions are major.minor; 0.x minors are additive, so readers of 0.x accept any 0.y ≥ x by ignoring unknown fields.

JavaScript API

Everything is importable from the package root; adapters and headless export live in subpath exports.

Renderer options

React

import OpenLEC from "open-lec/react";

<OpenLEC
  doc={doc}
  options={{ logX: true }}
  onValidation={(result) => setErrors(result.errors)}
/>

The component validates on every doc change, renders only valid documents, updates in place, and cleans up listeners on unmount.

CLI

Every command reads - as stdin, so adapters, stats, and rendering compose:

JSON Schema

For toolchains that speak draft 2020-12, the schema captures the structural half of conformance (the semantic rules — monotonicity, ordering, band coherence — need the validator).

Served from this site at /schema/openlec.schema.json, canonical in the repository at schema/openlec.schema.json.