Zod is commonly used for verifying unknown APIs.

In this example, we're fetching a person from the Star Wars API:

```typescript
export const fetchStarWarsPersonName = async (id: string) => {
  const data = await fetch("<https://swapi.dev/api/people/>" + id).then((res) =>
    res.json(),
  );

  const parsedData = PersonResult.parse(data);

  return parsedData.name;
};
```

Note the call to `PersonResult.parse()` that takes in the data from the fetch request.

The `PersonResult` variable is created with `z.unknown()`. This tells us that our data is typed as `any` because we don't know what it is:

`const PersonResult = z.unknown();`

## Running the Test

If we `console.log(data)` inside of the fetch function, we can see there's loads of stuff included in the API response when the test is run. There's the character's name, but there's also information about their eye color and the films they appear in, and other data we're not interested in at the moment.

The test does pass– it's the issue of `PersonResult` being an unknown type that we need to fix.

## Challenge

Referencing Zod's <a href="https://zod.dev/?id=objects" target="_blank" rel="noopener">Object schema documentation</a>, construct something that includes `name` and allows the types to parse.

## Change PersonResult to use `z.object`

To start, we need to change `PersonResult` into `z.object()`.

This tool allows us to construct objects with the keys and types we want.

In this case, we want the `name` which will be a string:

```typescript
const PersonResult = z.object({
  name: z.string(),
});
```

Note the similarities to how interfaces are created in TypeScript:

```typescript
interface PersonResultType {
  name: string;
}
```

## Checking our Work

Inside of `fetchStarWarsPersonName`, our `parsedData` is now correctly typed and has a structure that Zod understands.

Recall that the response from the API call included lots of information we weren't interested in.

Now if we call `console.log()` and pass in our `parsedData`, we can see that Zod has stripped away all of the keys that we aren't interested in, and gives us only the `name`.

## Going Further

Any additional keys you add to the `PersonResult` `ZodObject` from the original API response will be included in the `parsedData`.

Being able to specify exactly the data we want while being correctly typed is a really useful feature of Zod.

Create an Object Schema

Matt Pocock: 0:00 The solution here then is to change PersonResult here into a `z.object`. `z.object` is a tool that you can use to construct objects. It's like an interface in TypeScript. If we wanted to do the same thing in TypeScript, we would say, "PersonResultType." We'd say, "name string," here. You can see again how Zod really, really copies what TypeScript does. It does it very effectively.

0:24 Here, what we're doing is we're basically using this to understand data, here. This data, now, it's typed as any in this position. parsedData, it's actually typed in the correct way. Zod understands the structure of the object here.

0:41 If we do the same thing we did last time and just console.log the data here, then we're going to get all our keys. We've got films, which is an array. Let's do `eye_color` as well. If we add `eye_color`, which is `z.string`, then what this is going to do is it's going to add `eye_color` onto the bottom here.

0:58 If we actually `console.log `the `parsedData` here -- there we go -- you'll notice that it actually strips out all of the keys it doesn't understand too. What you end up with is a really pure, just the good stuff parsing thing.

1:16 What this means is you can get really, really cool. We can go even deeper on this, if you want to. Let's add another property into here. We could add even all of these properties. Zod wouldn't bat an eyelid. It would still work really, really well.

1:28 What it means is it does ignore keys that you parse that aren't specified on it. It would just reduce it to the amount of keys you have. That's the idea of z.object.

Verify Unknown APIs with an Object Schema

Matt Pocock: 0:00 We're now going to look at another really common use case in Zod, which is verifying unknown APIs. Here, we're calling an API inside `fetchStarWarsPersonName`, which is we're calling `swapi.dev.API people`. We're calling a res API endpoint, and then turning it into JSON.

0:20 This data here, it's typed as any, which is like an unknown data type. We don't really know what data is. We know. We can go and look on the swapi.dev documentation and we can look at the data. We can also, by the way, because we're actually calling it inside these tests, we just console.log(data).

0:39 We can look inside the console, and you'll see that there's loads and loads of stuff here. We're grabbing C-3PO in the second one, and we're grabbing Luke Skywalker in the first one. It looks like our tests are actually passing, but the issue is that this data type this PersonResult, which we're using to parse the data from this API, it's just returning unknown.

0:59 That means that we can't access the name property on something that we don't know what it is. Your challenge is to use the tools that you have in Zod, especially the object tools, to try and construct something that at least has a name on it so we can make the types parse.

TypeScript is great for checking variables at the type level.

For example, you can specify that the `age` property for a `User` should be a number.

However, you can’t always be sure what you’re going to get from a form input. TypeScript will present an error if it’s not a number, but on its own it doesn’t know if a number is too low or too high to be realistic for your use case.

There’s a similar problem with third-party API responses.

You can reference documentation to get an idea for what a response includes, but TypeScript can’t tell how to type it. And what happens if you get an error instead?

Zod allows you to work around uncertainty by checking types at the _runtime_ level as well at the type level.

In this tutorial, you’ll gain hands-on practice with Zod by working through a series of exercises that demonstrate how useful runtime checking is.

## **What is Zod?**

Zod ([github](https://github.com/colinhacks/zod#introduction)) is a TypeScript-first schema declaration and validation library. I'm using the term "schema" to broadly refer to any data type, from a simple **`string`** to a complex nested object.

Zod is designed to be as developer-friendly as possible. The goal is to eliminate duplicative type declarations. With Zod, you declare a validator _once_ and Zod will automatically infer the static TypeScript type. It's easy to compose simpler types into complex data structures.

## **Instructions**

This tutorial is a set of problem exercises for you to work through. Each exercise has a short video that presents the problem along with a code editor to solve the problem in the browser.

You'll know you've solved the exercise when the tests pass.

This Zod tutorial encourages **active, exploratory learning**. In each exercise, I'll explain a problem, and **you'll be asked to try to find a solution**.

To attempt a solution, you'll need to:

1. Look for any 🕵️‍♂️ emojis to give you a hint on what to change
2. Check out <a href="https://github.com/colinhacks/zod" target="_blank" rel="noopener">Zod's docs</a>
3. Try to find something that looks relevant.
4. Give it a go to see if it solves the problem.

You'll know if you've succeeded because the tests will pass.

**If you succeed**, or **if you get stuck**, watch the solution video and check out the **`*.solution.ts`**.

You can see if your solution is better or worse than mine!

### **Prerequisites**

You'll need a working understanding of JavaScript, but even if you are new to TypeScript this tutorial is for you.

### **Running the Exercises Locally**

You'll want to have an understanding of git to clone the repository, basic node and npm (yarn) , as well as TypeScript itself to work through this tutorial.

If you want to save your work or work in a different environment, you can also [clone the git repository](https://github.com/total-typescript/zod-tutorial) and work locally in the editor of your choice. If you [follow this link to use gitpod](https://gitpod.io/#https://github.com/total-typescript/zod-tutorial), you can work in a full VS Code coding environment running in your browser.

Follow the instructions in the [README](https://github.com/total-typescript/zod-tutorial/blob/main/README.md) to get the exercises running.

Zod is a TypeScript-first schema declaration and validation library. In this tutorial, Matt Pocock has prepared a set of exercises that will help you level up.

Transcript

Verify Unknown APIs with an Object Schema

Transcript