From 832b2856a6ab5a2c003c9d469d0be577fe010411 Mon Sep 17 00:00:00 2001 From: Omer Morad Date: Thu, 6 Feb 2025 18:43:19 +0200 Subject: [PATCH 1/6] chore: update readme file [skip ci] --- README.md | 117 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 70 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 8bc0e77..0a4cbad 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,64 @@

Contractual

-**Contractual is an open-source project intended to unify the entire lifecycle of API definitions, schemas, and data -contracts across diverse systems to ensure clarity, consistency, and control.** Contractual adopts a **spec-first -approach**, with **TypeSpec** as the single source of truth to make sure that definitions and schemas stay consistent, -versioned, and are type-safe across the entire stack. +**Contractual is a tool for managing API and data schemas as structured contracts. It ensures that schemas +are defined, versioned, and enforced across teams, whether for REST APIs, event-driven systems, or structured data +exchanges.** Built on **TypeSpec**, it provides a contract-first approach that helps teams track changes, prevent schema +drifts, and generate type-safe clients and server contracts. -Contractual starts with **OpenAPI** and **JSON Schemas** as its core, intended to improve processes for backend teams, -frontend developers, and data engineers. +By treating schemas as first-class entities, Contractual eliminates uncertainty at integration points, enabling backend, +frontend, and data engineering teams to maintain predictable and enforceable APIs and structured data across the entire +stack. -## 🚨 Why Contractual? +Common use cases include: \ +🔹 Keeping API Contracts in Sync Between Backend and Frontend \ +🔹 Generating Type-Safe Clients and Server Contracts \ +🔹 Preventing Breaking Changes and Detecting Schema Drift \ +🔹 Ensuring Consistency Between Backend and Data Teams \ +🔹 Generating Language-Specific Types from a Shared Contract -Handling APIs, schemas, and data contracts in modern systems can be complex and frequently fragmented, resulting in -inefficiencies and misaligned workflows across teams. In addition to traditional REST APIs, teams encounter difficulties -in managing structured data for uses such as validation, communication, and integrations across services. +> Initially built for the **Node.js and TypeScript ecosystem**, Contractual is planned to support additional +> languages. -- **Scattered Definitions:** Duplicating schemas and contracts across backend, frontend, and data workflows often - results in potential regressions. +## 🔍 Why Contractual? -- **Breaking Changes:** Without proper tracking, changes to contracts or schemas can unintentionally break downstream - systems or clients, causing regressions. +Maintaining the consistency of schemas across various services presents significant challenges. As systems evolve, +type-definitions and schemas drift, unnoticed breaking changes occur, and different teams find it challenging to +synchronize. APIs, event schemas, and structured data formats often become disconnected from their original intent, +leading to brittle integrations, manual fixes, and unexpected failures. -- **Fragmented Tooling:** Teams depend on a variety of disconnected tools for client generation, schema validation, and - version management, leading to interruptions in developer workflows. +**Some of the biggest pain points teams face include:** -- **Collaboration Gaps:** Misaligned definitions between teams—whether backend, frontend, or data engineers—lead to - mismatches, bugs, and wasted time. +- **Schema Drift & Misalignment:** APIs and data contracts become inconsistent across teams, leading to mismatches, +broken integrations, and regressions. -Contractual solves these problems by putting the specs first and using TypeSpec as the only source of truth. This -makes teams better at managing APIs and structured data processes. +- **Code Sharing**: Teams struggle to share and reuse schemas across services, leading to duplicated efforts and + inconsistent data structures. -## 🌟 Spec-First Approach and Use Cases +- **Untracked & Breaking Changes:** Without tracking modifications, updates can unexpectedly break consumers, causing +downtime and costly debugging. -A **spec-first approach** puts the definition of APIs and schemas at the center of the workflow, treating the -specification as the **single source of truth**. This ensures alignment across frontend, backend, and data teams while -streamlining development workflows. +- **Scattered Schemas & Code Maintenance:** Outdated documentation and manually managed type definitions create +unreliable integrations and make maintaining entity models error-prone. -### How Spec-First Works +#### How Spec-First Works 1. **Define Once**: - - Use **TypeSpec**, a declarative DSL, to define your API or schema in a centralized file. - - This becomes the authoritative source for your API’s structure, endpoints, and data contracts. + - Use **TypeSpec**, a declarative DSL, to define your API or schema in a centralized file. + - This becomes the authoritative source for your API’s structure, endpoints, and data contracts. 2. **Generate Everything**: - - From the spec, Contractual generates: - - **OpenAPI specifications** for REST documentation and tooling. - - **Type-safe clients** with **ts-rest** and **Zod** for runtime validation. - - **Server contracts** for Express, Fastify, and NestJS. - - **JSON Schemas** for validation or data workflows. + - From the spec, Contractual generates: + - **OpenAPI specifications** for REST documentation and tooling. + - **Type-safe clients** with **ts-rest** and **Zod** for runtime validation. + - **Server contracts** for Express, Fastify, and NestJS. + - **JSON Schemas** for validation or data workflows. 3. **Version and Diff**: - - Track changes to your APIs or schemas. - - Use versioning and diffing tools to detect and prevent breaking changes. + - Track changes to your APIs or schemas. + - Use versioning and diffing tools to detect and prevent breaking changes. 4. **Enforce Consistency**: - - Use the spec to drive all API-related workflows, ensuring backend, frontend, and data teams are in sync. + - Use the spec to drive all API-related workflows, ensuring backend, frontend, and data teams are in sync. ## 🚀 In Practice @@ -168,21 +173,39 @@ Here’s a short video showing contract generation in action: ### Use Cases -1. **API-Driven Applications**: - - Create consistent and versioned REST APIs with type-safe clients and server contracts. - - Ensure changes to your APIs don’t break downstream systems or clients. +- **API-Driven Applications**: + - Create consistent and versioned REST APIs with type-safe clients and server contracts. + - Ensure changes to your APIs don’t break downstream systems or clients. -2. **Data Validation Workflows**: - - Leverage **JSON Schemas** for validating complex data structures across services and teams. - - Seamlessly integrate validation into pipelines for ETL processes or data ingestion workflows. +- **Data Validation Workflows**: + - Leverage **JSON Schemas** for validating complex data structures across services and teams. + - Seamlessly integrate validation into pipelines for ETL processes or data ingestion workflows. -3. **Microservices and Distributed Systems**: - - Maintain uniform contracts across services, reducing integration bugs. - - Use diffing tools to communicate API changes across teams. +- **Microservices and Distributed Systems**: + - Maintain uniform contracts across services, reducing integration bugs. + - Use diffing tools to communicate API changes across teams. -4. **Frontend-Backend Synchronization**: - - Use generated type-safe clients to keep your frontend perfectly aligned with backend APIs. - - Integrate tools like React Query or Vue for a seamless developer experience. +- **Frontend-Backend Synchronization**: + - Use generated type-safe clients to keep your frontend perfectly aligned with backend APIs. + - Integrate tools like React Query or Vue for a seamless developer experience. + +## 🔑 The Contract-First Approach + +Most teams take a code-first approach to API development, where schemas are generated after implementation. This leads +to 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. + +A 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: + +- Define schemas upfront and enforce them as the single source of truth. + +- Track changes and prevent breaking updates before they impact consumers. + +- Generate type-safe clients and server contracts in multiple languages, reducing friction between teams. + +- Distribute schemas efficiently across backend services, frontend applications, and data pipelines. ## 📃 Goals From c50242f6fc2d78f6c6db0ddfd1ba77ace47ad24a Mon Sep 17 00:00:00 2001 From: Omer Morad Date: Thu, 6 Feb 2025 18:45:09 +0200 Subject: [PATCH 2/6] update [skip ci] --- README.md | 41 +++++++++++++++++++++-------------------- 1 file changed, 21 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 0a4cbad..b351f71 100644 --- a/README.md +++ b/README.md @@ -40,26 +40,6 @@ downtime and costly debugging. - **Scattered Schemas & Code Maintenance:** Outdated documentation and manually managed type definitions create unreliable integrations and make maintaining entity models error-prone. -#### How Spec-First Works - -1. **Define Once**: - - Use **TypeSpec**, a declarative DSL, to define your API or schema in a centralized file. - - This becomes the authoritative source for your API’s structure, endpoints, and data contracts. - -2. **Generate Everything**: - - From the spec, Contractual generates: - - **OpenAPI specifications** for REST documentation and tooling. - - **Type-safe clients** with **ts-rest** and **Zod** for runtime validation. - - **Server contracts** for Express, Fastify, and NestJS. - - **JSON Schemas** for validation or data workflows. - -3. **Version and Diff**: - - Track changes to your APIs or schemas. - - Use versioning and diffing tools to detect and prevent breaking changes. - -4. **Enforce Consistency**: - - Use the spec to drive all API-related workflows, ensuring backend, frontend, and data teams are in sync. - ## 🚀 In Practice ### Install Contractual @@ -207,6 +187,27 @@ structures, event definitions, and data formats remain stable and predictable. T - Distribute schemas efficiently across backend services, frontend applications, and data pipelines. +--- + +1. **Define Once**: + - Use **TypeSpec**, a declarative DSL, to define your API or schema in a centralized file. + - This becomes the authoritative source for your API’s structure, endpoints, and data contracts. + +2. **Generate Everything**: + - From the spec, Contractual generates: + - **OpenAPI specifications** for REST documentation and tooling. + - **Type-safe clients** with **ts-rest** and **Zod** for runtime validation. + - **Server contracts** for Express, Fastify, and NestJS. + - **JSON Schemas** for validation or data workflows. + +3. **Version and Diff**: + - Track changes to your APIs or schemas. + - Use versioning and diffing tools to detect and prevent breaking changes. + +4. **Enforce Consistency**: + - Use the spec to drive all API-related workflows, ensuring backend, frontend, and data teams are in sync. + + ## 📃 Goals * Provide a centralized tool for managing OpenAPI and JSON Schema lifecycles. From 8f3ec5e68ecec851382c5cb617674e0714d0ca9f Mon Sep 17 00:00:00 2001 From: Omer Morad Date: Thu, 6 Feb 2025 19:05:34 +0200 Subject: [PATCH 3/6] Update README.md --- README.md | 82 ++++++++++--------------------------------------------- 1 file changed, 14 insertions(+), 68 deletions(-) diff --git a/README.md b/README.md index b351f71..2f1543d 100644 --- a/README.md +++ b/README.md @@ -28,17 +28,23 @@ leading to brittle integrations, manual fixes, and unexpected failures. **Some of the biggest pain points teams face include:** -- **Schema Drift & Misalignment:** APIs and data contracts become inconsistent across teams, leading to mismatches, -broken integrations, and regressions. +- **Schema Drift & Misalignment:** APIs and data contracts become inconsistent across teams, leading to mismatches, broken integrations, and regressions. -- **Code Sharing**: Teams struggle to share and reuse schemas across services, leading to duplicated efforts and - inconsistent data structures. +- **Untracked Changes & Breaking Updates:** Without tracking modifications, updates can unexpectedly break consumers, causing downtime and costly debugging. -- **Untracked & Breaking Changes:** Without tracking modifications, updates can unexpectedly break consumers, causing -downtime and costly debugging. +- **Scattered Schemas & Code Maintenance:** Outdated documentation and manually managed type definitions create unreliable integrations and make maintaining entity models error-prone. -- **Scattered Schemas & Code Maintenance:** Outdated documentation and manually managed type definitions create -unreliable integrations and make maintaining entity models error-prone. + +## 🔑 The Contract-First Approach +Most 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. + +A **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: + +- Define schemas upfront and enforce them as the single source of truth. + +- Track changes and prevent breaking updates before they impact consumers. + +- Generate type-safe clients and server contracts in multiple languages, reducing friction between teams. ## 🚀 In Practice @@ -169,66 +175,6 @@ Here’s a short video showing contract generation in action: - Use generated type-safe clients to keep your frontend perfectly aligned with backend APIs. - Integrate tools like React Query or Vue for a seamless developer experience. -## 🔑 The Contract-First Approach - -Most teams take a code-first approach to API development, where schemas are generated after implementation. This leads -to 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. - -A 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: - -- Define schemas upfront and enforce them as the single source of truth. - -- Track changes and prevent breaking updates before they impact consumers. - -- Generate type-safe clients and server contracts in multiple languages, reducing friction between teams. - -- Distribute schemas efficiently across backend services, frontend applications, and data pipelines. - ---- - -1. **Define Once**: - - Use **TypeSpec**, a declarative DSL, to define your API or schema in a centralized file. - - This becomes the authoritative source for your API’s structure, endpoints, and data contracts. - -2. **Generate Everything**: - - From the spec, Contractual generates: - - **OpenAPI specifications** for REST documentation and tooling. - - **Type-safe clients** with **ts-rest** and **Zod** for runtime validation. - - **Server contracts** for Express, Fastify, and NestJS. - - **JSON Schemas** for validation or data workflows. - -3. **Version and Diff**: - - Track changes to your APIs or schemas. - - Use versioning and diffing tools to detect and prevent breaking changes. - -4. **Enforce Consistency**: - - Use the spec to drive all API-related workflows, ensuring backend, frontend, and data teams are in sync. - - -## 📃 Goals - -* Provide a centralized tool for managing OpenAPI and JSON Schema lifecycles. - -* Simplify API workflows with type-safe client/server generation. - -* Offer robust versioning and diffing tools to prevent breaking changes. - -* Lay the foundation for multi-language support, starting with Python. - -* Enable language-agnostic workflows, allowing developers to generate code and contracts across multiple languages ( - e.g., TypeScript to Python). - -* Introduce "contractual pack" to prepare contracts and generated clients/servers into distributable packages for - publication. - -## 🚫 Non-Goals - -* Contractual does not currently support gRPC, ProtoBufs, or GraphQL. While these protocols may be considered in the - future, the initial focus is on REST APIs and JSON Schemas. - ## 📘 Roadmap Want to contribute? Check out the alpha version [Roadmap](https://github.com/contractual-dev/contractual/issues/8) and From f9fcf5e43a6a6431b5d541db17b891f7f05109c0 Mon Sep 17 00:00:00 2001 From: Omer Morad Date: Fri, 7 Feb 2025 17:33:07 +0200 Subject: [PATCH 4/6] Update README.md --- README.md | 31 ++++++------------------------- 1 file changed, 6 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 2f1543d..bc73bae 100644 --- a/README.md +++ b/README.md @@ -34,18 +34,6 @@ leading to brittle integrations, manual fixes, and unexpected failures. - **Scattered Schemas & Code Maintenance:** Outdated documentation and manually managed type definitions create unreliable integrations and make maintaining entity models error-prone. - -## 🔑 The Contract-First Approach -Most 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. - -A **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: - -- Define schemas upfront and enforce them as the single source of truth. - -- Track changes and prevent breaking updates before they impact consumers. - -- Generate type-safe clients and server contracts in multiple languages, reducing friction between teams. - ## 🚀 In Practice ### Install Contractual @@ -157,23 +145,16 @@ Here’s a short video showing contract generation in action: ``` -### Use Cases +## 🔑 The Contract-First Approach +Most 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. -- **API-Driven Applications**: - - Create consistent and versioned REST APIs with type-safe clients and server contracts. - - Ensure changes to your APIs don’t break downstream systems or clients. +A **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: -- **Data Validation Workflows**: - - Leverage **JSON Schemas** for validating complex data structures across services and teams. - - Seamlessly integrate validation into pipelines for ETL processes or data ingestion workflows. +- Define schemas upfront and enforce them as the single source of truth. -- **Microservices and Distributed Systems**: - - Maintain uniform contracts across services, reducing integration bugs. - - Use diffing tools to communicate API changes across teams. +- Track changes and prevent breaking updates before they impact consumers. -- **Frontend-Backend Synchronization**: - - Use generated type-safe clients to keep your frontend perfectly aligned with backend APIs. - - Integrate tools like React Query or Vue for a seamless developer experience. +- Generate type-safe clients and server contracts in multiple languages, reducing friction between teams. ## 📘 Roadmap From b4ce804eff8aec9e8373991e731084dbb9c0116e Mon Sep 17 00:00:00 2001 From: Omer Morad Date: Fri, 7 Feb 2025 17:34:38 +0200 Subject: [PATCH 5/6] Update README.md --- README.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index bc73bae..551a30b 100644 --- a/README.md +++ b/README.md @@ -19,21 +19,6 @@ Common use cases include: \ > Initially built for the **Node.js and TypeScript ecosystem**, Contractual is planned to support additional > languages. -## 🔍 Why Contractual? - -Maintaining the consistency of schemas across various services presents significant challenges. As systems evolve, -type-definitions and schemas drift, unnoticed breaking changes occur, and different teams find it challenging to -synchronize. APIs, event schemas, and structured data formats often become disconnected from their original intent, -leading to brittle integrations, manual fixes, and unexpected failures. - -**Some of the biggest pain points teams face include:** - -- **Schema Drift & Misalignment:** APIs and data contracts become inconsistent across teams, leading to mismatches, broken integrations, and regressions. - -- **Untracked Changes & Breaking Updates:** Without tracking modifications, updates can unexpectedly break consumers, causing downtime and costly debugging. - -- **Scattered Schemas & Code Maintenance:** Outdated documentation and manually managed type definitions create unreliable integrations and make maintaining entity models error-prone. - ## 🚀 In Practice ### Install Contractual @@ -145,6 +130,21 @@ Here’s a short video showing contract generation in action: ``` +## 🔍 Why Contractual? + +Maintaining the consistency of schemas across various services presents significant challenges. As systems evolve, +type-definitions and schemas drift, unnoticed breaking changes occur, and different teams find it challenging to +synchronize. APIs, event schemas, and structured data formats often become disconnected from their original intent, +leading to brittle integrations, manual fixes, and unexpected failures. + +**Some of the biggest pain points teams face include:** + +- **Schema Drift & Misalignment:** APIs and data contracts become inconsistent across teams, leading to mismatches, broken integrations, and regressions. + +- **Untracked Changes & Breaking Updates:** Without tracking modifications, updates can unexpectedly break consumers, causing downtime and costly debugging. + +- **Scattered Schemas & Code Maintenance:** Outdated documentation and manually managed type definitions create unreliable integrations and make maintaining entity models error-prone. + ## 🔑 The Contract-First Approach Most 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. From bb420c558a0c7e57fd8661053c9481b4b76329e7 Mon Sep 17 00:00:00 2001 From: Omer Morad Date: Fri, 7 Feb 2025 17:36:14 +0200 Subject: [PATCH 6/6] Update README.md --- README.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 551a30b..eeff71e 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,8 @@

Contractual

-**Contractual is a tool for managing API and data schemas as structured contracts. It ensures that schemas +Contractual is a tool for managing API and data schemas as structured contracts. It ensures that schemas are defined, versioned, and enforced across teams, whether for REST APIs, event-driven systems, or structured data -exchanges.** Built on **TypeSpec**, it provides a contract-first approach that helps teams track changes, prevent schema -drifts, and generate type-safe clients and server contracts. - -By treating schemas as first-class entities, Contractual eliminates uncertainty at integration points, enabling backend, -frontend, and data engineering teams to maintain predictable and enforceable APIs and structured data across the entire -stack. +exchanges. Common use cases include: \ 🔹 Keeping API Contracts in Sync Between Backend and Frontend \ @@ -16,6 +11,10 @@ Common use cases include: \ 🔹 Ensuring Consistency Between Backend and Data Teams \ 🔹 Generating Language-Specific Types from a Shared Contract +By treating schemas as first-class entities, Contractual eliminates uncertainty at integration points, enabling backend, +frontend, and data engineering teams to maintain predictable and enforceable APIs and structured data across the entire +stack. + > Initially built for the **Node.js and TypeScript ecosystem**, Contractual is planned to support additional > languages.