{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://lambrary.com/library.schema.json",
  "title": "Lambrary library file",
  "description": "A portable library of Excel LAMBDA definitions: each entry carries the defining formula (refersTo) plus structured documentation (description, parameter notes, allowed-value lists). Produced by Lambrary's Export Docs (Lambrary library (JSON) format) and consumed by its Import Library. Importers ignore unknown fields; entries missing name or refersTo, or whose refersTo is not a LAMBDA formula, are skipped.",
  "type": "object",
  "required": ["format", "formatVersion", "lambdas"],
  "properties": {
    "format": {
      "const": "lambrary-library",
      "description": "Format discriminator. Importers reject files where this is absent or different."
    },
    "formatVersion": {
      "type": "integer",
      "const": 1,
      "description": "Schema version. Importers reject versions newer than they understand."
    },
    "exportedBy": {
      "type": "string",
      "description": "Informational provenance stamp, e.g. 'Lambrary 0.2.0-beta.6'. Optional."
    },
    "exportedAt": {
      "type": "string",
      "description": "Informational timestamp (ISO 8601 local, e.g. 2026-06-12T07:30:00). Optional."
    },
    "workbook": {
      "type": "string",
      "description": "Name of the workbook the library was exported from. Optional."
    },
    "lambdas": {
      "type": "array",
      "items": { "$ref": "#/$defs/lambda" }
    }
  },
  "$defs": {
    "lambda": {
      "type": "object",
      "required": ["name", "refersTo"],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "description": "The LAMBDA's defined name, exactly as called in formulas (e.g. 'WAVG'). Must be a valid Excel defined name."
        },
        "refersTo": {
          "type": "string",
          "pattern": "^=",
          "description": "The full defining formula, e.g. '=LAMBDA(values,weights, SUMPRODUCT(values,weights)/SUM(weights))'. Must parse as a LAMBDA or the importer skips the entry."
        },
        "description": {
          "type": "string",
          "description": "What the function does. Plain text (no markdown); newlines allowed. The first line is used as a one-line summary in lists, so lead with the essence."
        },
        "documentationUrl": {
          "type": "string",
          "description": "Optional link to fuller documentation. Opened via Ctrl+click on the LAMBDA's name in Lambrary's Browse window."
        },
        "parameters": {
          "type": "array",
          "items": { "$ref": "#/$defs/parameter" },
          "description": "One entry per parameter of the LAMBDA, in signature order. Names must match the parameter names in refersTo (optional parameters may be written with or without their square brackets; matching ignores the brackets)."
        }
      }
    },
    "parameter": {
      "type": "object",
      "required": ["name"],
      "properties": {
        "name": {
          "type": "string",
          "minLength": 1,
          "description": "The parameter name as it appears in the LAMBDA signature, e.g. 'weights' or '[mode]'."
        },
        "description": {
          "type": "string",
          "description": "A short note on what the argument is and how it's used. Plain text, ideally one phrase or sentence."
        },
        "values": {
          "type": "array",
          "items": { "$ref": "#/$defs/value" },
          "description": "Allowed-values list, ONLY for parameters that accept a small fixed set of codes (modes, flags). Rendered as a pick-list while typing, like Excel's native match_mode dropdown."
        }
      }
    },
    "value": {
      "type": "object",
      "required": ["code"],
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "description": "The exact token inserted into the formula when picked, e.g. '0' or '\"asc\"'."
        },
        "label": {
          "type": "string",
          "description": "Short human-readable label shown beside the code, e.g. 'Exact match'. Avoid commas and pipes; they are replaced with ';' and '/' on import."
        },
        "description": {
          "type": "string",
          "description": "Optional hover note explaining the value. Avoid pipes; commas are fine."
        }
      }
    }
  }
}