{
  "openapi": "3.1.0",
  "info": {
    "title": "Wire Lang metadata API",
    "version": "0.4.0",
    "summary": "Read-only metadata API for Wire Lang, the text-first language for electronic schematics.",
    "description": "This API exposes machine-readable metadata about Wire Lang: service health, the standard component library, and the documented example circuits. Wire Lang itself is a declarative `.wire` language rendered by the `wire` CLI (`npm install wire-lang`) — this HTTP API never compiles or renders schematics, it only describes the language so agents can discover component names, terminals, and properties before generating `.wire` source.",
    "contact": {
      "name": "Wire Lang",
      "url": "https://github.com/eduardozf/wire-lang/issues"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://www.wirelang.net",
      "description": "Production website and metadata API"
    }
  ],
  "tags": [
    {
      "name": "meta",
      "description": "Service health and discovery endpoints."
    },
    {
      "name": "language",
      "description": "Wire Lang language metadata: components and examples."
    }
  ],
  "externalDocs": {
    "description": "Wire Lang documentation (human-readable)",
    "url": "https://www.wirelang.net/docs/"
  },
  "paths": {
    "/api/health": {
      "get": {
        "operationId": "getHealth",
        "summary": "Check API liveness",
        "description": "Returns service status, the Wire Lang language version this metadata describes, and the current server time. Use it to verify the API is reachable before calling the language endpoints.",
        "tags": ["meta"],
        "responses": {
          "200": {
            "description": "The API is reachable.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Health"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed; only GET is supported.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/api/components": {
      "get": {
        "operationId": "listComponents",
        "summary": "List the standard component library",
        "description": "Returns every standard Wire Lang component type with its terminals, recommended and optional properties, and symbol name. Pass `q` to filter by type or symbol name (for example `q=diode`). Use the result to pick valid component types and terminal names when generating `.wire` source.",
        "tags": ["language"],
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": false,
            "description": "Case-insensitive substring filter over component type and symbol names.",
            "schema": {
              "type": "string",
              "maxLength": 64,
              "examples": ["diode", "led"]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The matching standard components.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["count", "components"],
                  "properties": {
                    "count": {
                      "type": "integer",
                      "minimum": 0,
                      "description": "Number of components in this response."
                    },
                    "components": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Component"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The `q` parameter is invalid (for example, longer than 64 characters).",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed; only GET is supported.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    },
    "/api/examples": {
      "get": {
        "operationId": "listExamples",
        "summary": "List documented example circuits",
        "description": "Returns the copy-pasteable example circuits documented under /docs/examples/, each with a slug, title, description, and documentation URL. Use it to find a starting point close to the circuit you want to generate.",
        "tags": ["language"],
        "responses": {
          "200": {
            "description": "The documented example circuits.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["count", "examples"],
                  "properties": {
                    "count": {
                      "type": "integer",
                      "minimum": 0,
                      "description": "Number of examples in this response."
                    },
                    "examples": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Example"
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed; only GET is supported.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorEnvelope"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Component": {
        "type": "object",
        "description": "One standard Wire Lang component type.",
        "required": ["type", "terminals", "terminalSource", "recommended", "optional", "symbol"],
        "properties": {
          "type": {
            "type": "string",
            "description": "Component type name used after the instance ID in `component <ID> <Type>`."
          },
          "terminals": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Fixed terminal names addressable as `<ID>.<Terminal>`. Empty when terminals come from a `pins=[...]` list."
          },
          "terminalSource": {
            "type": "string",
            "enum": ["fixed", "pins"],
            "description": "`fixed` terminals are listed in `terminals`; `pins` terminals come from the component's `pins=[...]` property."
          },
          "recommended": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Properties the validator recommends (missing ones warn)."
          },
          "optional": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Optional properties with their accepted values."
          },
          "symbol": {
            "type": "string",
            "description": "Renderer symbol name for this component type."
          }
        }
      },
      "Example": {
        "type": "object",
        "description": "One documented Wire Lang example circuit.",
        "required": ["slug", "title", "description", "url"],
        "properties": {
          "slug": {
            "type": "string",
            "description": "URL-safe example identifier."
          },
          "title": {
            "type": "string",
            "description": "Human-readable example title."
          },
          "description": {
            "type": "string",
            "description": "What the example circuit demonstrates."
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Documentation page containing the full `.wire` source."
          }
        }
      },
      "Health": {
        "type": "object",
        "description": "API liveness status.",
        "required": ["status", "service", "wireLangVersion", "time"],
        "properties": {
          "status": {
            "type": "string",
            "enum": ["ok"],
            "description": "Always `ok` when the API serves this response."
          },
          "service": {
            "type": "string",
            "description": "Service identifier."
          },
          "wireLangVersion": {
            "type": "string",
            "description": "Wire Lang language version this metadata describes."
          },
          "time": {
            "type": "string",
            "format": "date-time",
            "description": "Current server time (ISO 8601)."
          }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "description": "Structured error returned by every API failure, including unknown /api/* routes (404), bad parameters (400), and wrong methods (405).",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "hint", "docs"],
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable machine-readable error code (for example `not_found`)."
              },
              "message": {
                "type": "string",
                "description": "Human-readable explanation of what went wrong."
              },
              "hint": {
                "type": "string",
                "description": "What the caller should do instead."
              },
              "docs": {
                "type": "string",
                "format": "uri",
                "description": "Documentation URL for further help."
              }
            }
          }
        }
      }
    }
  }
}