{
  "openapi": "3.1.0",
  "info": {
    "title": "The Internet of Value Spec API",
    "version": "0.1.0",
    "description": "Public read-only API for The Internet of Value canonical protocol registry."
  },
  "servers": [
    {
      "url": "http://localhost:8787",
      "description": "Local development server"
    },
    {
      "url": "https://spec.theinternetofvalue.xyz",
      "description": "Production static/API origin"
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "summary": "Health check",
        "responses": {
          "200": {
            "description": "API is healthy"
          }
        }
      }
    },
    "/version": {
      "get": {
        "summary": "Current API and spec version",
        "responses": {
          "200": {
            "description": "Version metadata"
          }
        }
      }
    },
    "/registry": {
      "get": {
        "summary": "Full canonical registry",
        "responses": {
          "200": {
            "description": "Canonical registry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Registry"
                }
              }
            }
          }
        }
      }
    },
    "/latest/registry": {
      "get": {
        "summary": "Latest canonical registry alias",
        "responses": {
          "200": {
            "description": "Latest canonical registry",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Registry"
                }
              }
            }
          }
        }
      }
    },
    "/v{version}/registry": {
      "get": {
        "summary": "Versioned canonical registry",
        "parameters": [
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Versioned canonical registry"
          },
          "404": {
            "description": "Requested spec version is unavailable"
          }
        }
      }
    },
    "/versions": {
      "get": {
        "summary": "List spec versions",
        "responses": {
          "200": {
            "description": "Spec version history"
          }
        }
      }
    },
    "/versions/{version}": {
      "get": {
        "summary": "Get spec version metadata",
        "parameters": [
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Spec version metadata"
          },
          "404": {
            "description": "Spec version not found"
          }
        }
      }
    },
    "/versions/{version}/registry": {
      "get": {
        "summary": "Get registry snapshot for a spec version when available",
        "parameters": [
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Versioned registry snapshot"
          },
          "404": {
            "description": "Registry snapshot not found"
          }
        }
      }
    },
    "/versions/{version}/changelog": {
      "get": {
        "summary": "Get changelog metadata for a spec version",
        "parameters": [
          {
            "name": "version",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Version changelog metadata"
          },
          "404": {
            "description": "Spec version not found"
          }
        }
      }
    },
    "/versions/compare": {
      "get": {
        "summary": "Compare two spec versions",
        "parameters": [
          {
            "name": "from",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Version comparison"
          },
          "404": {
            "description": "Spec version not found"
          }
        }
      }
    },
    "/rfcs": {
      "get": {
        "summary": "List IOV RFC-style decision records",
        "responses": {
          "200": {
            "description": "RFC-style decision record index"
          }
        }
      }
    },
    "/rfcs/{id}": {
      "get": {
        "summary": "Get an IOV RFC-style decision record",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "RFC-style decision record"
          },
          "404": {
            "description": "RFC not found"
          }
        }
      }
    },
    "/authors": {
      "get": {
        "summary": "List spec authors",
        "responses": {
          "200": {
            "description": "Author index"
          }
        }
      }
    },
    "/authors/{id}": {
      "get": {
        "summary": "Get a spec author",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Author metadata"
          },
          "404": {
            "description": "Author not found"
          }
        }
      }
    },
    "/protocols": {
      "get": {
        "summary": "List protocols",
        "responses": {
          "200": {
            "description": "Protocol list"
          }
        }
      }
    },
    "/protocols/{protocolId}": {
      "get": {
        "summary": "Get a protocol by ID",
        "parameters": [
          {
            "name": "protocolId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Protocol record"
          },
          "404": {
            "description": "Protocol not found"
          }
        }
      }
    },
    "/variables": {
      "get": {
        "summary": "List variables with optional filters",
        "parameters": [
          {
            "name": "level",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "L1",
                "L2",
                "L3",
                "L4"
              ]
            }
          },
          {
            "name": "protocol",
            "in": "query",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Variable list"
          }
        }
      }
    },
    "/variables/{path}": {
      "get": {
        "summary": "Get a variable by encoded path",
        "parameters": [
          {
            "name": "path",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Variable record"
          },
          "404": {
            "description": "Variable not found"
          }
        }
      }
    },
    "/schemas/registry": {
      "get": {
        "summary": "Registry JSON schema",
        "responses": {
          "200": {
            "description": "Registry schema"
          }
        }
      }
    },
    "/schemas/protocol": {
      "get": {
        "summary": "Protocol JSON schema",
        "responses": {
          "200": {
            "description": "Protocol schema"
          }
        }
      }
    },
    "/schemas/registered-expression": {
      "get": {
        "summary": "Registered expression JSON schema",
        "responses": {
          "200": {
            "description": "Registered expression schema"
          }
        }
      }
    },
    "/schemas/wellbeing-identity-document": {
      "get": {
        "summary": "Wellbeing Identity document JSON schema",
        "responses": {
          "200": {
            "description": "Wellbeing Identity document schema"
          }
        }
      }
    },
    "/schemas/wellbeing-identity-workshop": {
      "get": {
        "summary": "Wellbeing Identity workshop completion JSON schema",
        "responses": {
          "200": {
            "description": "Workshop completion schema"
          }
        }
      }
    },
    "/schemas/creator-eligibility-credential": {
      "get": {
        "summary": "Registered Expression creator eligibility JSON schema",
        "responses": {
          "200": {
            "description": "Creator eligibility credential schema"
          }
        }
      }
    },
    "/registered-expressions/{slug}": {
      "get": {
        "summary": "Get a registered-expression conformance fixture",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Registered-expression fixture"
          },
          "404": {
            "description": "Registered expression not found"
          }
        }
      }
    },
    "/identity-workshops/{slug}": {
      "get": {
        "summary": "Get a public workshop-completion conformance fixture",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Workshop completion fixture"
          },
          "404": {
            "description": "Workshop not found"
          }
        }
      }
    },
    "/creator-eligibility/{slug}": {
      "get": {
        "summary": "Get a public creator-eligibility conformance fixture",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Creator eligibility fixture"
          },
          "404": {
            "description": "Credential not found"
          }
        }
      }
    },
    "/wellbeing-identities": {
      "get": {
        "summary": "List explicitly published WellbeingIdentity profiles",
        "responses": {
          "200": {
            "description": "Published WellbeingIdentity directory"
          }
        }
      }
    },
    "/wellbeing-identities/{slug}": {
      "get": {
        "summary": "Get an explicitly published WellbeingIdentity profile",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Published WellbeingIdentity profile"
          },
          "404": {
            "description": "Published profile not found"
          }
        }
      }
    },
    "/openapi.json": {
      "get": {
        "summary": "OpenAPI JSON document",
        "responses": {
          "200": {
            "description": "OpenAPI JSON document"
          }
        }
      }
    },
    "/changelog": {
      "get": {
        "summary": "Machine-readable changelog placeholder",
        "responses": {
          "200": {
            "description": "Changelog entries"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Registry": {
        "type": "object",
        "required": [
          "apiVersion",
          "specVersion",
          "protocols",
          "variables"
        ],
        "properties": {
          "apiVersion": {
            "type": "string"
          },
          "specVersion": {
            "type": "string"
          },
          "protocols": {
            "type": "array"
          },
          "variables": {
            "type": "array"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}