Start 0.3.0 WIP

.github/workflows/ci.yml

@@ -25,5 +25,10 @@ jobs:
       - name: Test
         run: opam exec -- dune runtest
 
+      - name: Run examples
+        run: |
+          opam exec -- dune exec examples/users_api.exe
+          opam exec -- dune exec examples/http_style_app.exe
+
       - name: Lint opam file
         run: opam lint contract.opam

CHANGES.md

@@ -1,5 +1,13 @@
 # Changes
 
+## 0.3.0 - Unreleased
+
+- Add pure API contracts for endpoint route tables.
+- Add API-level request matching and validation.
+- Allow OpenAPI output from validated API contracts.
+- Add an example-only HTTP-style adapter around API validation and response
+  validation.
+
 ## 0.2.0 - 2026-06-09
 
 - Add pure response validation for declared status codes and JSON response

README.md

@@ -4,12 +4,12 @@
 [![opam](https://badgen.net/opam/v/contract)](https://opam.ocaml.org/packages/contract/)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-`contract` is an OCaml library for describing HTTP API contracts as typed values. The current code covers a small pure core: endpoint definitions, path matching, scalar and JSON decoding, request and response validation, and OpenAPI output.
+`contract` is an OCaml library for describing HTTP API contracts as typed values. The current code covers a small pure core: endpoint definitions, API route matching, scalar and JSON decoding, request and response validation, and OpenAPI output.
 
-## Current MVP
+## Scope
 
-The current source tree is a thin vertical slice for REST-style JSON APIs. It has no HTTP server dependency.
-A request is a value passed to the validator; a response is a status plus optional JSON body checked against the endpoint's declared responses.
+`contract` currently targets REST-style JSON APIs. It has no HTTP server dependency.
+Endpoints can be grouped into an API value for pure route selection. A request is a value passed to the endpoint or API validator; a response is a status plus optional JSON body checked against the endpoint's declared responses.
 Path parameters are percent-decoded after route matching.
 
 Released package:
@@ -19,9 +19,11 @@ opam install contract
 ```
 
 See `examples/users_api.ml` for a small users API with `GET /users/:id` and `POST /users`.
+See `examples/http_style_app.ml` for example-only HTTP-style glue around the pure API validator.
 
 ```sh
 dune exec examples/users_api.exe
+dune exec examples/http_style_app.exe
 ```
 
 Development:

RELEASE.md

@@ -13,22 +13,24 @@ opam exec -- dune build -p contract
 opam exec -- dune runtest -p contract
 opam lint contract.opam
 opam exec -- dune exec examples/users_api.exe
+opam exec -- dune exec examples/http_style_app.exe
 ```
 
-Check that the example prints OpenAPI JSON with:
+Check that the examples print OpenAPI JSON with:
 
 - `"openapi": "3.0.3"`
 - `/users/{id}`
 - `GET /users/{id}`
 - `POST /users`
 
-For 0.2.0:
+When cutting a release:
 
 ```sh
-git tag -a 0.2.0 -m "Release 0.2.0"
-git push origin 0.2.0
-opam publish --tag 0.2.0 -v 0.2.0 .
+git tag -a <version> -m "Release <version>"
+git push origin <version>
+opam publish --tag <version> -v <version> .
 ```
 
 Use the tag created from the checked release commit. If `opam publish` cannot be
-used from this machine, open an opam-repository pull request for `packages/contract/contract.0.2.0/opam`.
+used from this machine, open an opam-repository pull request for the package
+version being released.

contract.opam

@@ -11,7 +11,8 @@ synopsis: "Typed HTTP API contracts for OCaml"
 description: """
 contract describes REST-style HTTP API contracts as typed OCaml values.
 The current package provides a pure core for endpoint definitions, parameter
-and JSON decoding, request and response validation, and OpenAPI 3.0.3 output.
+and JSON decoding, route matching, request and response validation, and
+OpenAPI 3.0.3 output.
 """
 depends: [
   "ocaml" {>= "5.0"}

dune-project

@@ -1,13 +1,13 @@
 (lang dune 3.11)
 
 (name contract)
-(version 0.2.0)
+(version 0.3.0)
 
 (package
  (name contract)
  (synopsis "Typed HTTP API contracts for OCaml")
  (description
-  "A pure core for typed HTTP API contracts, request and response validation, and OpenAPI output.")
+  "A pure core for typed HTTP API contracts, route matching, request and response validation, and OpenAPI output.")
  (license MIT)
  (depends
   (ocaml (>= 5.0))

examples/dune

@@ -1,3 +1,3 @@
-(executable
- (name users_api)
+(executables
+ (names users_api http_style_app)
  (libraries contract yojson))