Validating Response Bodies (JSON)

Every call to response.json in this course so far has returned unknown. This means TypeScript has no idea what shape the data is, so it can’t warn you if you access a property that doesn’t exist or if the API changes its response format.

HttpClientResponse.schemaBodyJson() solves this by validating the response body against a Schema. If the response matches, you get a fully typed value. If it doesn’t, you get a typed SchemaError.

1
import {
2
  FetchHttpClient,
3
  HttpClient,
4
  HttpClientRequest,
5
  HttpClientResponse,
6
} from "effect/unstable/http";
7
import { Effect, Schema } from "effect";
8

9
const User = Schema.Struct({
10
  id: Schema.Number,
11
  firstName: Schema.String,
12
  lastName: Schema.String,
13
  email: Schema.String,
14
  age: Schema.Number,
15
});
16

17
function fetchUser(userId: number) {
18
  return Effect.gen(function* () {
19
    const client = yield* HttpClient.HttpClient;
20

21
    const request = HttpClientRequest.get(
22
      `https://dummyjson.com/users/${userId}`,
23
    );
24

25
    const response = yield* client.execute(request);
26

27
    // Validate the response body against the User schema
28
    const user = yield* HttpClientResponse.schemaBodyJson(User)(response);
29

30
    return user;
31
  }).pipe(Effect.provide(FetchHttpClient.layer));
32
}
33

34
// Test it
35
Effect.runPromise(fetchUser(1)).then((user) => {
36
  // user is fully typed: { id: number, firstName: string, ... }
37
  console.log(`${user.firstName} ${user.lastName}, age ${user.age}`);
38
  console.log(`Email: ${user.email}`);
39
});

Output:

1
Emily Johnson, age 29
2
Email: emily.johnson@x.dummyjson.com

schemaBodyJson is a curried function. You first pass the schema, then the response:

1
HttpClientResponse.schemaBodyJson(User)(response);
2
//                                ^^^^  ^^^^^^^^
3
//                               schema  response

In the example above, the return type is now { id: number; firstName: string; lastName: string; email: string; age: number } instead of unknown. TypeScript knows exactly what you’re working with.

Under the hood, schemaBodyJson() calls response.json to parse the body, then runs the schema validation. If validation fails, it produces a SchemaError in the error channel.

Note that SchemaError is a schema validation failure, not an HTTP failure. This means it’s a separate error type from HttpClientError, and you can catch them independently.

By default, schema validation strips unknown properties. The dummyJSON API returns many more fields (like phone, image, address), but our schema only declares five fields, so those extras are silently dropped. This is a good thing. Your code only depends on the fields you’ve explicitly declared, making it resilient to upstream API changes.