{"id":24763198,"url":"https://github.com/contractual-dev/contractual","last_synced_at":"2025-10-11T10:31:12.997Z","repository":{"id":273558468,"uuid":"917350111","full_name":"contractual-dev/contractual","owner":"contractual-dev","description":"Contractual is an open-source tool designed to unify the lifecycle of API definitions and json contracts, ensuring consistency, versioning, and type safety across modern development workflows.","archived":false,"fork":false,"pushed_at":"2025-01-28T16:45:49.000Z","size":39373,"stargazers_count":17,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-28T17:36:34.315Z","etag":null,"topics":["contract","contracts","json-schema","openapi","openapi3","rest","rest-api","schema","spec","ts-rest","typespec","validations"],"latest_commit_sha":null,"homepage":"https://contractual.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/contractual-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-15T20:18:28.000Z","updated_at":"2025-01-28T16:45:52.000Z","dependencies_parsed_at":"2025-01-28T17:30:13.130Z","dependency_job_id":null,"html_url":"https://github.com/contractual-dev/contractual","commit_stats":null,"previous_names":["contractual-dev/contractual"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contractual-dev%2Fcontractual","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contractual-dev%2Fcontractual/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contractual-dev%2Fcontractual/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/contractual-dev%2Fcontractual/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/contractual-dev","download_url":"https://codeload.github.com/contractual-dev/contractual/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236081263,"owners_count":19091757,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["contract","contracts","json-schema","openapi","openapi3","rest","rest-api","schema","spec","ts-rest","typespec","validations"],"created_at":"2025-01-28T20:21:07.865Z","updated_at":"2025-10-11T10:31:12.992Z","avatar_url":"https://github.com/contractual-dev.png","language":"TypeScript","readme":"\u003ch1 align=\"center\"\u003eContractual\u003c/h1\u003e\r\n\r\nContractual is a tool for managing API and data schemas as structured contracts. It ensures that schemas\r\nare defined, versioned, and enforced across teams, whether for REST APIs, event-driven systems, or structured data\r\nexchanges.\r\n\r\nCommon use cases include: \\\r\n🔹 Keeping API Contracts in Sync Between Backend and Frontend \\\r\n🔹 Generating Type-Safe Clients and Server Contracts \\\r\n🔹 Preventing Breaking Changes and Detecting Schema Drift \\\r\n🔹 Ensuring Consistency Between Backend and Data Teams \\\r\n🔹 Generating Language-Specific Types from a Shared Contract\r\n\r\nBy treating schemas as first-class entities, Contractual eliminates uncertainty at integration points, enabling backend,\r\nfrontend, and data engineering teams to maintain predictable and enforceable APIs and structured data across the entire\r\nstack.\r\n\r\n\u003e Initially built for the **Node.js and TypeScript ecosystem**, Contractual is planned to support additional\r\n\u003e languages.\r\n\r\n## 🚀 In Practice\r\n\r\n### Install Contractual\r\n\r\nTo get started, install the Contractual CLI globally:\r\n\r\n```bash\r\nnpm i -g @contractual/cli\r\n```\r\n\r\n### Initialize Your Project\r\n\r\nRun the `init` command to scaffold a new project:\r\n\r\n```bash\r\ncontractual init\r\n```\r\n\r\nThis command creates the following project structure:\r\n\r\n```\r\nfrontend/          # Your frontend application\r\nserver/            # Your server application\r\ncontractual/       # Contractual files\r\n├── api.tsp        # TypeSpec API definition\r\n├── specs/         # OpenAPI auto-generated specs\r\n```\r\n\r\n\u003e Contractual works seamlessly with **monorepos**, **monoliths**, and distributed repositories.\r\n\r\n### Define Your API\r\n\r\nWrite your API definition in the `api.tsp` file. For example:\r\n\r\n```tsp\r\nimport \"@typespec/http\";\r\nimport \"@typespec/openapi\";\r\nimport \"@typespec/openapi3\";\r\n\r\nusing TypeSpec.Http;\r\n\r\n@service({\r\n  title: \"Petstore API\",\r\n})\r\nnamespace PetstoreAPI;\r\n\r\nmodel Pet {\r\n  id: string;\r\n  name: string;\r\n}\r\n\r\n@route(\"/pet\")\r\n@post\r\nop addPet(@body body: Pet): Pet;\r\n```\r\n\r\n\u003e You can experiment and validate your API definitions [using the TypeSpec playground](https://typespec.io/playground/)\r\n\r\n### Manage API Changes\r\n\r\n#### Save the Current State of Your API\r\n\r\nRun the `spec graduate` command to save the current state of your OpenAPI spec:\r\n\r\n```bash\r\ncontractual spec graduate\r\n```\r\n\r\nThis will generate a new OpenAPI (3.1.0) YAML file with versioning, enabling to track API changes over time. The\r\nupdated structure will look like this:\r\n\r\n```\r\ncontractual/\r\n├── api.tsp                  # TypeSpec API definition\r\n├── specs/                   # OpenAPI auto-generated specs\r\n│   ├── openapi-v1.0.0.yaml\r\nclient/                      # Generated API clients\r\nserver/                      # Server contracts\r\ne2e/                         # Type-safe API-driven tests\r\n```\r\n\r\n\u003e You can track API evolution and changes easily with clear, versioned OpenAPI specs.\r\n\r\nHere’s a quick video showing how this works:\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n  \u003cimg src=\"spec-graduate.gif\" /\u003e\r\n\u003c/div\u003e\r\n\r\n### Generate Contracts\r\n\r\nRun the `contract generate` command to generate type-safe clients, server contracts, and updated OpenAPI specs:\r\n\r\n```bash\r\ncontractual contract generate\r\n```\r\n\r\nThis command creates:\r\n\r\n- **Type-safe client libraries** [using **ts-rest**](https://ts-rest.com), integrated with **Zod** for runtime\r\n  validation.\r\n- **Server contracts** for frameworks like **Express**, **Fastify**, and **NestJS**.\r\n- **Updated OpenAPI specs**.\r\n\r\nHere’s a short video showing contract generation in action:\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n  \u003cimg src=\"contract-generate.gif\" /\u003e\r\n\u003c/div\u003e\r\n```\r\n\r\n## 🔍 Why Contractual?\r\n\r\nMaintaining the consistency of schemas across various services presents significant challenges. As systems evolve,\r\ntype-definitions and schemas drift, unnoticed breaking changes occur, and different teams find it challenging to\r\nsynchronize. APIs, event schemas, and structured data formats often become disconnected from their original intent,\r\nleading to brittle integrations, manual fixes, and unexpected failures.\r\n\r\n**Some of the biggest pain points teams face include:**\r\n\r\n- **Schema Drift \u0026 Misalignment:** APIs and data contracts become inconsistent across teams, leading to mismatches, broken integrations, and regressions.\r\n\r\n- **Untracked Changes \u0026 Breaking Updates:** Without tracking modifications, updates can unexpectedly break consumers, causing downtime and costly debugging.\r\n\r\n- **Scattered Schemas \u0026 Code Maintenance:** Outdated documentation and manually managed type definitions create unreliable integrations and make maintaining entity models error-prone.\r\n\r\n## 🔑 The Contract-First Approach\r\nMost teams take a **code-first** approach to API development, where schemas are generated after implementation. This often results in **misalignment between services, outdated documentation, and accidental breaking changes.** Backend teams define APIs, frontend teams consume them, and data engineers rely on structured data formats—all of which can drift over time when schemas are an afterthought.\r\n\r\nA **contract-first** approach flips this process: schemas are designed before any implementation begins, ensuring that API structures, event definitions, and data formats remain stable and predictable. This approach allows teams to:\r\n\r\n- Define schemas upfront and enforce them as the single source of truth.\r\n\r\n- Track changes and prevent breaking updates before they impact consumers.\r\n\r\n- Generate type-safe clients and server contracts in multiple languages, reducing friction between teams.\r\n\r\n## 📘 Roadmap\r\n\r\nWant to contribute? Check out the alpha version [Roadmap](https://github.com/contractual-dev/contractual/issues/8) and\r\njoin the journey! 🚀\r\n\r\n## ❤️ Join the Community\r\n\r\nContractual is open-source, and we’re looking for contributors to help shape its future, if you’re interested in\r\ncollaborating, please reach out.\r\n\r\n📩 **Feedback or Questions?** Reach out\r\nvia [GitHub Discussions](https://github.com/contractual-dev/contractual/discussions).\r\n\r\n## 🔒 License\r\n\r\nLicensed under [MIT](LICENSE).\r\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontractual-dev%2Fcontractual","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcontractual-dev%2Fcontractual","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcontractual-dev%2Fcontractual/lists"}