{"id":27808247,"url":"https://github.com/appear-sh/api-validator","last_synced_at":"2026-04-25T23:37:41.613Z","repository":{"id":290463844,"uuid":"973937101","full_name":"appear-sh/api-validator","owner":"appear-sh","description":"An API validation tool that showcases our OAS Zod Validator alongside third-party validators and linters, providing a combined quality report for OAS 3.0.x and 3.1 specifications.","archived":false,"fork":false,"pushed_at":"2026-01-26T11:04:32.000Z","size":1019,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-01-27T00:56:21.307Z","etag":null,"topics":["api","openapi-specification","openapi3","openapi31","validator"],"latest_commit_sha":null,"homepage":"https://validator.appear.sh","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/appear-sh.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-28T02:35:04.000Z","updated_at":"2026-01-18T22:34:45.000Z","dependencies_parsed_at":"2025-04-29T01:26:47.172Z","dependency_job_id":"3c400f86-5c4c-47c9-a0c6-aa87910c4de3","html_url":"https://github.com/appear-sh/api-validator","commit_stats":null,"previous_names":["appear-sh/api-validator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/appear-sh/api-validator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appear-sh%2Fapi-validator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appear-sh%2Fapi-validator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appear-sh%2Fapi-validator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appear-sh%2Fapi-validator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/appear-sh","download_url":"https://codeload.github.com/appear-sh/api-validator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appear-sh%2Fapi-validator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32280981,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","openapi-specification","openapi3","openapi31","validator"],"created_at":"2025-05-01T10:25:27.184Z","updated_at":"2026-04-25T23:37:41.607Z","avatar_url":"https://github.com/appear-sh.png","language":"TypeScript","readme":"\u003c!-- PROJECT LOGO --\u003e\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/appear-sh/api-validator\"\u003e\n   \u003cimg src=\"https://github.com/appear-sh/api-validator/blob/main/assets/Appear%20API%20validator.png\" alt=\"Logo\"\u003e\n  \u003c/a\u003e\n\n  \u003ch3 align=\"center\"\u003eAPI Validator \u0026 Agent-Ready Score\u003c/h3\u003e\n\n  \u003cp align=\"center\"\u003e\n    Validate your OpenAPI spec and measure how ready it is for AI agent consumption. From Appear.\n    \u003cbr /\u003e\n    \u003ca href=\"https://appear.sh/blog/why-your-api-docs-break-for-ai-agents\"\u003e\u003cstrong\u003eLearn why this matters »\u003c/strong\u003e\u003c/a\u003e\n    \u003cbr /\u003e\n    \u003cbr /\u003e\n    \u003ca href=\"https://www.appear.sh\"\u003eAppear Website\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/appear-sh/api-validator/issues\"\u003eIssues\u003c/a\u003e\n    ·\n    \u003ca href=\"https://github.com/appear-sh/OAS-Zod-Validator\"\u003eOAS Zod Validator\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/p\u003e\n\n# API Validator \u0026 Agent-Ready Score\n\nAn open-source tool that validates OpenAPI specifications and calculates an **Agent-Ready Score**—a measure of how well your API documentation is prepared for consumption by AI agents, LLM-powered tools, and automated systems.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n## Why Agent Readiness?\n\nAI agents interact with APIs differently than humans. They can't infer intent from context, guess parameter meanings, or improvise when documentation is incomplete. An API that works fine for human developers may fail completely for AI agents due to:\n\n- Missing or vague descriptions\n- Absent operationIds (which become function names)\n- No request/response examples\n- Undocumented error responses\n- Broken schema references\n\nThe Agent-Ready Score quantifies these gaps and provides actionable recommendations.\n\n## Features\n\n### Agent-Ready Score\n- **Six weighted dimensions** evaluating AI agent compatibility:\n  - **Foundational Compliance (25%)** — Structural validity, parsing errors, broken $refs\n  - **Semantic Richness (20%)** — Description coverage and natural language quality\n  - **Agent Usability (20%)** — operationIds, idempotency, pagination patterns\n  - **AI Discoverability (15%)** — Examples, tags, and API metadata\n  - **Security (10%)** — Authentication scheme documentation\n  - **Error Recoverability (10%)** — Structured error responses and retry guidance\n- **Letter grades (A–F)** with readiness levels (Agent Ready, Partially Ready, Needs Work, Not Ready)\n- **Prioritised recommendations** with impact assessment\n- **Transparent methodology** — fully documented, deterministic scoring (no AI/ML black box)\n\n### Technical Validation\n- **Three validation engines** running in parallel:\n  - [Spectral](https://github.com/stoplightio/spectral) — OpenAPI linting and best practices\n  - [Swagger Parser](https://github.com/APIDevTools/swagger-parser) — Structural validation and $ref resolution\n  - [OAS Zod Validator](https://github.com/appear-sh/OAS-Zod-Validator) — Schema type conformance\n- **Grouped issues** — Similar errors collapsed into expandable groups\n- **Accurate line markers** — Click any issue to jump to the exact line in your spec\n- **Supports OpenAPI 3.0.x, 3.1, and 3.2** specifications (YAML or JSON)\n\n### User Experience\n- **Drag-and-drop** or browse for file upload\n- **Fetch from URL** — validate specs hosted online\n- **Collapsible panels** — expand the code viewer when you need more space\n- **Real-time feedback** during validation\n- **Copy/download** validation results as JSON\n- **No account required** — validate specs instantly\n\n## How Scoring Works\n\nThe Agent-Ready Score is **entirely deterministic and rule-based**. There is no AI, no machine learning model, and no external API calls involved in calculating the score.\n\nThe scoring algorithm:\n1. Parses your OpenAPI specification\n2. Runs three validation engines to detect structural issues\n3. Analyses the spec against documented criteria for each dimension\n4. Calculates sub-scores using transparent penalty multipliers\n5. Combines dimension scores using the documented weights\n\n**Same spec = same score, every time.**\n\nFor full methodology details, click \"How is this calculated?\" in the app.\n\n## Getting Started\n\n### Prerequisites\n- Node.js 18+\n- pnpm (recommended) or npm\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/appear-sh/api-validator.git\ncd api-validator\n\n# Install dependencies\npnpm install\n\n# Run the development server\npnpm dev\n```\n\nOpen [http://localhost:3000](http://localhost:3000) to use the validator.\n\n### Production Build\n\n```bash\npnpm build\npnpm start\n```\n\n## Usage\n\n1. **Upload a spec** — Drag an OpenAPI 3.x spec (YAML or JSON) into the upload area, or click to browse\n2. **Or fetch from URL** — Enter a URL to a hosted spec and click \"Fetch \u0026 Validate\"\n3. **Review your Agent-Ready Score** — See your overall grade and dimension breakdown\n4. **Explore recommendations** — Prioritised improvements with impact assessment\n5. **Check technical validation** — Detailed issues from all three validators\n6. **Fix and re-validate** — Iterate until you reach Agent Ready status\n\n## FAQ\n\n### Is this using AI to calculate the score?\nNo. The scoring is entirely deterministic and rule-based. The score measures how well your API will work *with* AI agents, but the measurement itself is traditional static analysis.\n\n### Why is my score low when my API works fine?\nWorking for humans ≠ working for agents. Agents can't infer intent from context like humans can. They need explicit operationIds, examples, and descriptions.\n\n### What's the difference between Technical Validation and Agent-Ready Score?\nTechnical Validation catches structural errors (broken refs, invalid schemas). Agent-Ready Score goes further—a spec can be technically valid but still unusable by AI agents due to missing descriptions, examples, or poor naming.\n\n### Can I game the score?\nTechnically yes—but that would mean improving your spec in ways that genuinely help AI agents. The scoring criteria are based on real-world agent failure modes.\n\n## Related Projects\n\n- [OAS Zod Validator](https://github.com/appear-sh/OAS-Zod-Validator) — Runtime OpenAPI schema validation using Zod\n- [Appear](https://appear.sh) — API observability and documentation platform\n\n## Contributing\n\nContributions are welcome! Please open an issue or submit a pull request.\n\n## License\n\nMIT License — see [LICENSE](LICENSE) for details.\n\n---\n\nBuilt by [Appear](https://appear.sh) — Making APIs work better for humans and AI agents.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappear-sh%2Fapi-validator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fappear-sh%2Fapi-validator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappear-sh%2Fapi-validator/lists"}