{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://raw.githubusercontent.com/mathlib-initiative/formalization.yaml/main/schema/v0.4.schema.json",
  "title": "formalization.yaml (v0.4)",
  "description": "Repo-root metadata schema for formalization projects (v0.4). Validates a filled-in formalization.yaml.",
  "type": "object",
  "$comment": "Permissive: extra keys allowed everywhere. Required fields use minLength/minItems so a blank template is invalid.",
  "required": ["project", "sources", "automation", "review"],
  "properties": {
    "version": {
      "type": "string"
    },
    "project": {
      "type": "object",
      "description": "the formalization itself (not the source)",
      "required": ["name", "authors", "license"],
      "properties": {
        "name": { "type": "string", "minLength": 1 },
        "description": {
          "type": "string",
          "description": "a concise account of the mathematical content and principal results of the formalization"
        },
        "authors": {
          "type": "array",
          "minItems": 1,
          "items": { "type": "string", "minLength": 1 },
          "description": "who did the formalization"
        },
        "responsible_maintainers": {
          "type": "array",
          "items": { "type": "string" },
          "description": "people responsible for the formalization repository"
        },
        "license": { "type": "string", "minLength": 1 }
      }
    },
    "repository": {
      "type": "object",
      "description": "optional relationship to a separately pinned substantive formalization; omission means this repository is the substantive development",
      "properties": {
        "role": {
          "type": "string",
          "enum": ["", "substantive-development", "thin-wrapper"]
        },
        "substantive_formalization": {
          "type": "object",
          "required": ["id"],
          "properties": {
            "id": {
              "type": "string",
              "minLength": 1,
              "description": "repository URL or another stable identifier"
            },
            "revision": {
              "type": "string",
              "description": "immutable commit or revision when available"
            }
          }
        }
      },
      "allOf": [
        {
          "if": { "properties": { "role": { "const": "thin-wrapper" } }, "required": ["role"] },
          "then": { "required": ["substantive_formalization"] }
        },
        {
          "if": { "properties": { "role": { "const": "substantive-development" } }, "required": ["role"] },
          "then": {
            "not": { "required": ["substantive_formalization"] }
          }
        }
      ]
    },
    "sources": {
      "type": "array",
      "minItems": 1,
      "description": "what was formalized; use an original-proof entry when the theorem is first presented by the formalization",
      "items": {
        "type": "object",
        "required": ["title"],
        "properties": {
          "title": { "type": "string", "minLength": 1 },
          "authors": {
            "type": "array",
            "items": { "type": "string", "minLength": 1 },
            "description": "bibliographic authors of this source"
          },
          "contributors": {
            "type": "array",
            "description": "people credited for non-author roles associated with this source",
            "items": {
              "type": "object",
              "required": ["name", "role"],
              "properties": {
                "name": { "type": "string", "minLength": 1 },
                "role": {
                  "type": "string",
                  "minLength": 1,
                  "description": "free-form contribution role, e.g. editor or problem-proposer"
                }
              }
            }
          },
          "id": {
            "type": "string",
            "description": "optional URL, DOI, ISBN, arXiv ID, citation, or other stable identifier"
          },
          "type": {
            "type": "string",
            "description": "kind of source (article, book, web post, folklore, conversation, original-proof, ...)"
          },
          "location": {
            "type": "string",
            "description": "theorem, section, page, post, answer, or other locator within the source"
          },
          "relationship": {
            "type": "string",
            "enum": ["", "formalizes", "adapts", "independently-proves", "background", "other"]
          },
          "note": {
            "type": "string",
            "description": "free-form source detail; use this to explain relationship or author_endorsement: other"
          },
          "license": { "type": "string" },
          "author_endorsement": {
            "type": "string",
            "enum": ["", "participated", "endorsed", "no-response", "not-contacted", "declined", "n/a", "other"],
            "description": "source-author involvement or response; separate from repository submission authorization; explain other in note"
          }
        }
      }
    },
    "related_formalizations": {
      "type": "array",
      "description": "prior or parallel formalizations, if known",
      "items": {
        "type": "object",
        "required": ["id"],
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "description": "URL or stable identifier"
          },
          "relationship": {
            "type": "string",
            "enum": ["", "builds-on", "adapts", "independent", "supersedes", "other"]
          },
          "note": { "type": "string" }
        }
      }
    },
    "classification": {
      "type": "object",
      "description": "what area of mathematics the formalized result belongs to",
      "properties": {
        "arxiv": {
          "type": "array",
          "items": { "type": "string", "minLength": 1 },
          "description": "arXiv categories, e.g. [\"math.NT\", \"math.CO\"]"
        },
        "msc2020": {
          "type": "array",
          "items": { "type": "string", "minLength": 1 },
          "description": "MSC2020 codes, e.g. [\"11N25\", \"05C35\"]"
        }
      }
    },
    "automation": {
      "type": "object",
      "description": "how it was produced",
      "required": ["methods"],
      "properties": {
        "methods": {
          "type": "array",
          "minItems": 1,
          "description": "one entry per distinct phase/run/tool",
          "items": {
            "type": "object",
            "required": ["method"],
            "properties": {
              "method": {
                "type": "string",
                "enum": ["manual", "copilot", "agent", "autonomous", "other"],
                "description": "manual | copilot | agent | autonomous | other"
              },
              "models": {
                "type": "array",
                "items": { "type": "string" },
                "description": "e.g. [\"claude-opus-4-7\", \"gpt-5\"]"
              },
              "framework": {
                "type": "string",
                "description": "e.g. \"Claude Code\", \"OpenClaw\", \"LeanCopilot\""
              },
              "tool_setup": {
                "type": "string",
                "description": "tools, harnesses, plugins, orchestration, customizations"
              },
              "cost": {
                "type": "object",
                "properties": {
                  "wall_time": {
                    "type": ["string", "number"],
                    "description": "e.g. \"3 weeks\" or \"240 GPU-hours\""
                  },
                  "spend_usd": {
                    "type": ["string", "number"],
                    "description": "spend for this method, e.g. \"$10 API credits\""
                  },
                  "hardware": {
                    "type": ["string", "number"],
                    "description": "GPU count, \"API-only\", \"my laptop\", whatever's relevant"
                  }
                }
              },
              "prompting_notes": {
                "type": "string",
                "description": "freeform notes/examples about the prompts or task specs used"
              }
            }
          }
        },
        "spend_usd": {
          "type": ["string", "number"],
          "description": "total spend across the project, e.g. \"$10 API credits\" or \"subscription-based usage\""
        },
        "notes": {
          "type": "string",
          "description": "freeform details on the overall process and interaction setup"
        }
      }
    },
    "status": {
      "type": "object",
      "description": "project status",
      "properties": {
        "scope": {
          "type": "string",
          "description": "describe the scope of the project"
        },
        "sorry_count": {
          "type": "integer",
          "minimum": 0,
          "description": "number of unresolved sorries in the proof development, excluding deliberate placeholders in Comparator challenge modules"
        },
        "sorry_in_definitions": {
          "type": "integer",
          "minimum": 0,
          "description": "number of unresolved sorries in proof-development definitions, excluding deliberate definition holes in Comparator challenge modules"
        },
        "axioms": {
          "type": "array",
          "items": { "type": "string" },
          "description": "list all axioms used (including standard axioms such as `Quot.sound`)"
        },
        "main_results": {
          "type": "array",
          "description": "list the main results of the project",
          "items": {
            "type": "object",
            "properties": {
              "declaration": {
                "type": "string",
                "description": "declaration proving this main result"
              },
              "file": {
                "type": "string",
                "description": "file containing the declaration"
              },
              "sorry_count": {
                "type": "integer",
                "minimum": 0,
                "description": "number of unresolved sorries in the proved declaration, excluding the deliberate placeholder in its Comparator challenge module"
              },
              "axioms": {
                "type": "array",
                "items": { "type": "string" },
                "description": "axioms used for this result"
              },
              "comparator_config": {
                "type": "string",
                "description": "path to the comparator (leanprover/comparator) JSON config that verifies this result"
              },
              "literature_dependencies": {
                "type": "array",
                "description": "results this result relies on but does not prove, assumed from the literature",
                "items": {
                  "type": "object",
                  "properties": {
                    "statement": {
                      "type": "string",
                      "description": "the result being relied on"
                    },
                    "source": {
                      "type": "string",
                      "description": "the specific source it comes from (reference a `sources` entry)"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "fidelity": {
      "type": "object",
      "properties": {
        "divergences": {
          "type": "string",
          "description": "places the formalization deviates from sources: generalizations, weakened hypotheses, renamed lemmas, etc."
        }
      }
    },
    "review": {
      "type": "object",
      "description": "review status",
      "required": ["status"],
      "properties": {
        "status": {
          "type": "string",
          "minLength": 1,
          "description": "unchecked | agent-reviewed | self-assessed | peer-reviewed | author-verified | other/freeform"
        },
        "reviewers": {
          "type": "array",
          "items": { "type": "string" }
        },
        "notes": {
          "type": "string",
          "description": "more details on the review process"
        }
      }
    },
    "alignment": {
      "description": "freeform YAML describing how source statements map to formal declarations. The structured table in the template is only a suggested shape; replace or extend as useful."
    },
    "acknowledgements": {
      "type": "string",
      "description": "optional credits for libraries, tools, discussions, etc."
    }
  }
}