Javascript

Level up your REST API's with JSON Schema

Feb 16, 2024

5 min read

JSON Schema isn’t a hot topic that gets a lot of attention compared to GraphQL or other similar tools. I discovered the power of JSON Schema while I was building a REST API with Fastify. What is it exactly? The website describes it as “the vocabulary that enables JSON data consistency, validity, and interoperability at scale”. Or more simply, it’s a schema specification for JSON data. This article is going to highlight some of the benefits gained by defining a JSON Schema for a REST API.

JSON Schema Basics

Here’s an example of a simple schema representing a user:

{
  "$id": "<https://example.com/schemas/user>",
  "$schema": "<http://json-schema.org/draft-07/schema#>",
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string"
    },
    "lastName": {
      "type": "string"
    },
    "email": {
      "type": "string",
      "format": "email"
    },
    "age": {
      "type": "integer"
    },
    "newsletterSubscriber": {
      "type": "boolean"
    },
    "favoriteGenres": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": ["email"],
  "additionalProperties": false
}

If you’re familiar with JSON already, you can probably understand most of this at a glance. This schema represents a JSON object with some properties that define a User in our system, for example. Along with the object’s properties, we can define additional metadata about the object. We can describe which fields are required and whether or not the schema can accept any additional properties that aren’t defined on the properties list.

Types

We covered a lot of types in our example schema. The root type of our JSON schema is an object with various properties defined on it. The base types available to define in your JSON Schema map to valid JSON types: object, array, string, number, integer, boolean. Check the type reference page to learn more.

Formats

The email property in our example has an additional field named format next to its type. The format property allows us to define a semantic identification for string values. This allows our schema definition to be more specific about the type of values allowed for a given field. “hello” is not a valid string value for our email type.

Another common example is for date or timestamp values that get serialized. Validation implementations can use the format definition to make sure a value matches the expected type and format defined. There’s a section on the website that lists the various formats available for the string type.

Schema Structuring

JSON Schema supports referencing schemas from within a schema. This is a very important feature that helps us keep our schemas DRY. Looking back to our initial example we might want to define a schema for a list of users. We defined an id on our user schema of “user”, we can use this to reference that schema from another schema.

{
	"type": "array",
	"items": {
		"$ref": "<https://example.com/schemas/user>"
	}
}

In this example we have a simple schema that is just an array whose items definition references our user schema. This schema is exactly the same as if we defined our initial schema inside of "items": { }. The JSON Schema website has a page dedicated to structuring schemas.

JSON Schema Benefits

Validation

One of the main benefits of defining a schema for your API is being able to validate inputs, outputs. Inputs include things like the request body, URL parameters, and search parameters. The output is your response JSON data or headers. There are some different libraries available to handle schema validation. A popular choice and the one used by Fastify is called Ajv.

Security

Validating inputs has some security advantages. It can prevent bad or malicious data from being accepted by your API. For instance, you can specify that a certain field must be an integer, or that a string must match a certain regex pattern. This can help prevent SQL injection, cross-site scripting (XSS).

Defining a schema for your response types can help to prevent leaking sensitive data from your database. Your web server can be configured to not include any data that is not defined in the schema from your responses.

Performance

By validating data at the schema level, you can reject invalid requests early, before they reach more resource-intensive parts of your application. This can help protect against Denial of Service (DoS) attacks.

fast-json-stringify is a library that creates optimized stringify functions from JSON schemas that can help improve response times and throughput for JSON API’s.

Documentation

JSON Schema also greatly aids in API documentation. Tools like OpenAPI and Swagger use JSON Schema to automatically generate human-readable API documentation. This documentation provides developers with clear, precise information about your API’s endpoints, request parameters, and response formats. This not only helps to maintain consistent and clear communication within your development team, but also makes your API more accessible to outside developers.

Type-safety

I plan to cover this in more detail in an upcoming post but there are tools available that can help achieve type-safety both on your server and client-side by pairing JSON Schema with TypeScript. In Fastify for example, you can infer types in your request handlers based on your JSON Schema specifications.

Schema Examples

I’ve taken some example schemas from the Fastify website to walk through how they would work in practice.

### queryStringJsonSchema

const queryStringJsonSchema = {
  type: 'object',
   properties: {
     name: { type: 'string' },
     excitement: { type: 'integer' }
   }, 
  additionalProperites: "false"
}

We would use this schema to define, validate, and parse the query string of an incoming request in our API.

Given a query string like: ?name=Dane&excitement=10&other=additional - we can expect to receive an object that looks like this:

{
  name: "Dane",
  excitement: 10
}

Since additionalProperties are not allowed, the other property that wasn’t defined on our schema gets parsed out.

### paramsJsonSchema

Imagining we had a route in our API defined like /users/:userId/posts/:slug

const paramsJsonSchema = {
  type: 'object',
  properties: {
     userId: { type: 'number' },
     slug: { type: 'string' }
   },
 additionalProperties: "false",
 required: ["userId", "slug"]
}

Given this url: /users/1/posts/hello-world - we can expect to get an object in our handler that looks like this:

{
  userId: 1,
  slug: "hello-world"
}

We can be sure about this since the schema doesn’t allow for additional properties and both properties are required. If either field was missing or not matching its type, our API can automatically return a proper error response code.

Just to highlight what we are getting here again. We are able to provide fine-grained schema definitions for all the inputs and outputs of our API. Aside from serving as documentation and specification, it powers validation, parsing, and sanitizing values. I’ve found this to be a very simple and powerful tool in my toolbox.

Summary

In this post, we've explored the power and functionality of JSON Schema, a tool that often doesn't get the spotlight it deserves. We've seen how it provides a robust structure for JSON data, ensuring consistency, validity, and interoperability on a large scale. Through our user schema example, we've delved into key features like types, formats, and the ability to structure schemas using references, keeping our code DRY. We've also discussed the substantial benefits of using JSON Schema, such as validation, enhanced security, improved performance, and the potential for type-safety. We've touched on useful libraries like Ajv for validation and fast-json-stringify for performance optimization.

In a future post we will explore how we can utilize JSON Schema to achieve end-to-end type-safety in our applications.

This Dot is a consultancy dedicated to guiding companies through their modernization and digital transformation journeys. Specializing in replatforming, modernizing, and launching new initiatives, we stand out by taking true ownership of your engineering projects.

We love helping teams with projects that have missed their deadlines or helping keep your strategic digital initiatives on course. Check out our case studies and our clients that trust us with their engineering.

Dane Grant

JavaScript developer building things on web, native, and server environments. Free time filled with reading, cooking, dog, sports, comedy, and music.

@danecando @danecando

End-to-end type-safety with JSON Schema

End-to-end type-safety with JSON Schema I recently wrote an introduction to JSON Schema post. If you’re unfamiliar with it, check out the post, but TLDR: It’s a schema specification that can be used to define the input and output data for your JSON API. In my post, I highlight many fantastic benefits you can reap from defining schemas for your JSON API. One of the more interesting things you can achieve with your schemas is end-to-end type safety from your backend API to your client application(s). In this post, we will explore how this can be accomplished slightly deeper. Overview The basic idea of what we want to achieve is: * a JSON API server that validates input and output data using JSON Schema * The JSON Schema definitions that our API uses transformed into TypeScript types With those pieces in place, we can achieve type safety on our API server and the consuming client application. The server side is pretty straightforward if you’re using a server like Fastify with already enabled JSON Schema support. This post will focus on the concepts more than the actual implementation details though. Here’s a simple diagram illustrating the high-level concept: We can share the schema and type declaration between the client and server. In that case, we can make a request to an endpoint where we know its type and schema, and assuming the server validates the data against the schema before sending it back to the client, our client can be confident about the type of the response data. Marrying JSON Schema and TypeScript There are a couple of different ways to accomplish this: * Generating types from schema definitions using code generation tools * Creating TypeBox definitions that can infer TypeScript types and be compiled to JSON Schema I recommend considering both and figuring out which would better fit your application and workflows. Like anything else, each has its own set of trade-offs. In my experience, I’ve found TypeBox to be the most compelling if you want to go deep with this pattern. Code generation A couple of different packages are available for generating TS types from JSON Schema definitions. * https://github.com/bcherny/json-schema-to-typescript * https://github.com/vega/ts-json-schema-generator They are CLI tools that you can provide a glob path to where your schema files are located and will generate TS declaration files to a specified output path. You can set up an npm hook or a similar type of script that will generate types for your development environment. TypeBox TypeBox is a JSON Schema type builder. With this approach, instead of json files, we define schemas in code using the TypeBox API. The TypeBox definitions infer to TypeScript types directly, which eliminates the code generation step described above. Here’s a simple example from the documentation of a JSON Schema definition declared with TypeBox: ` This can then be inferred as a TypeScript type: ` Aside from schemas and types, TypeBox can do a lot more to help us on our type-safety journey. We will explore it a bit more in upcoming sections. Sharing schemas between client and server applications Sharing our JSON Schema between our server and client app is the main requirement for end-to-end type-safety. There are a couple of different ways to accomplish this, but the simplest would be to set up our codebase as a monorepo that contains both the server and client app. Some popular options for TypeScript monorepos are: PNPM, Turborepo, and NX. If a monorepo is not an option, you can publish your schema and types as a package that can be installed in both projects. However, this setup would require a lot more maintenance work. Ultimately, as long as you can import your schemas and types from the client and server app, you are in good shape. Server-to-client validation and type-safety For the sake of simplicity, let's focus on data flowing from the server to the client for now. Generally speaking, the concepts also apply in reverse, as long as your JSON API server validates your inputs and outputs. We’ll look at the most basic version of having strongly typed data on the client from a request to our server. Type-safe client requests In our server application, if we validate the /users endpoint with a shared schema - on the client side, when we make the request to the endpoint, we know that the response data is validated using the user schema. As long as we are confident of this fact, we can use the generated type from that schema as the return type on our client fetch call. Here’s some pseudocode: ` Our server endpoint would look something like this: ` You could get creative and build out a map that defines all of your endpoints, their metadata, and schemas, and use the map to define your server endpoints and create an API client. Transforming data over the wire Everything looks stellar, but we can still take our efforts a bit further. To this point, we are still limited to serialized JSON data. If we have a created_at field (number or ISO string) tied to our user, and we want it to be a Date object when we get a hold of it on the client side - additional work and consideration are required. There are some different strategies out there for deserializing JSON data. The great thing about having shared schemas between our client and server is that we can encode our type information in the schema without sending additional metadata from our server to the client. Using format to declare type data In my initial JSON Schema blog post, I touched on the format field of the specification. In our schema, if the actual type of our date is a string in ISO8601 format, we can declare our format to be "date-time". We can use this information on the client to transform the field into a proper Date object. ` Transforming serialized JSON Data This can be a little bit tricky; again, there are many ways to accomplish it. To demonstrate the concept, we’ll use TypeBox to define our schemas as discussed above. TypeBox provides a Transform type that you can use to declare, encode, and decode methods for your schema definition. ` It even provides helpers to statically generate the decoded and encoded types for your schema ` If you declare your decode and encode functions for your schemas, you can then use the TypeBox API to handle decoding the serialized values returned from your JSON API. Here’s what the concept looks like in practice fetching a user from our API: ` Nice. You could use a validation library like Zod to achieve a similar result but here we aren’t actually doing any validation on our client side. That happened on the server. We just know the types based on the schema since both ends share them. On the client, we are just transforming our serialized JSON into what we want it to be in our client application. Summary There are a lot of pieces in play to accomplish end-to-end type safety. With the help of JSON Schema and TypeBox though, it feels like light work for a semi-roll-your-own type of solution. Another great thing about it is that it’s flexible and based on pretty core concepts like a JSON API paired with a TypeScript-based client application. The number of benefits that you can reap from defining JSON Schemas for your APIs is really great. If you’re like me and wanna keep it simple by avoiding GraphQL or other similar tools, this is a great approach....

Apr 17, 2024

6 mins

JSONTypeScript

Building interactive forms with TanStack Form

TanStack Form is a new headless form library that makes building more complex and interactive forms easy. TanStack has understood the power of ‘headless’ UI libraries for quite some time with some really incredible tools like TanStack Table and TanStack Query. Given the high quality of all the other libraries in the TanStack suite, I was excited to give this new form library a try. If you’ve used react-hook-form before the two libraries have quite a bit in common. The transition should be mostly straightforward. Let's start by comparing the two libraries and bit and then dig into the TanStack Form API with some examples and code. Comparison to react-hook-form At a high level, the two libraries are pretty similar: - Headless, hook-based API - Performance (both libraries minimize amount of renders triggered by state changes) - Lightweight, zero-dependencies (TanStack 4.4kb, react-hook-form 9.7kb) - Comprehensive feature set - Type-safety / TypeScript support - Form / Input validation and schemas There are a few things that set TanStack Form apart: - UI Agnostic - TanStack Form offers support for other UI libraries and frameworks through a plugin-style system. Currently, React & Solid is supported out of the box. - Simpler API and documentation - The API surface area is a bit smaller, and the documentation makes it easy to find the details on all the APIs. - First-class TypeScript support - TanStack Form provides really impressive type inference. It stays out of your way and lets you focus on writing code instead of wrangling types. Building forms Since the API for TanStack Form is pretty small, we can walk through the important APIs pretty quickly to see how they work together to help us build interactive client-side forms. useForm(options) useForm accepts an options object that accepts defaultValues, defaultState, and event handler functions like onSubmit, onChange, etc. The types are clear, and the source code is easy to read so you can refer to FormApi.ts file for more specifics. Currently, the examples on the website don’t provide a type for the generic TData that useForm accepts. It will infer the form types based on the defaultValues that are provided, but in this example, I will provide the type explicitly. ` The API for your form is returned from the useForm hook. We will use this API to build the fields and their functionality in our component. useField(opts) If you want to abstract one of your form fields into its own component we can use the useField hook. The useField generic parameters take the type definition of your form and the field name. ` Validation is as simple as returning a string from your field onChange handler. For our password field we return an error message if the length isn’t at least 8 characters long. We bind our field states and event handlers to the form input by passing them in as props. Component API form includes a component API with a Context Provider, a component for rendering Field components, and a Subscribe component for subscribing to state changes. I’ve added the remaining fields to our form using the Field component and included our PasswordField from above. Using the Field component is similar to using the useField hook - the difference is our field instance gets passed in via a render prop. ` We wrapped our submit button with the Subscribe component which has a pretty interesting API. Subscribe allows you to subscribe to state changes granularly. Whatever state items you return from the selector gets passed into the render prop and re-render it on changes. This will be really useful in places where render performance is critical. Async event handlers We can use the built-in async handlers and debounce options to implement a search input. This feature makes a common pattern like this trivial. ` Async event handlers can be used for other things like async validation as well. We could update our email input from our create account form to check to see if the account already exists. ` Validation adapters Since this post was first written, TanStack Form has added adapters for popular schema validation libraries like Yup and Zod. The actual API for using the schemas is a little bit different then what you might be used to from react-hook-form. Instead of passing a schema definition for all of the fields to the root form API, you provide schemas for each field individually. We’ll look at the Zod example from the documentation. ` To use the schema validation you need to pass the schema validation adapter into the validatorAdapter option in the useForm declaration. Looking at the FieldInfo component from the example we can see that the internal state and API for form validation is the same. The adapter takes care of wiring up the schema validation library to handle the underlying field validation. ` So we can easily check the state of our field to see if there are any errors or if it’s processing some async validation logic. We mentioned that without the schema adapter we can just return an error message string from a validation function to indicate an error. With the schema adapter, we instead just return the schema itself. This works for async validations as well. ` Initially, I wasn’t sure that I would like defining a schema at the field level instead of providing a schema up front for the entire form. After sitting with it for a bit, I think it’s a better solution. The validations are decoupled from the value of the field and it allows a clean and simple API to decide when they run. In the example above validations against the schema will run on every change to the field value but we could easily change this to onBlur or any of the other available event handlers. Conclusion If you don’t mind taking a chance on a newer library from a well-established author in the ecosystem, Tanstack Form is a solid choice. - The APIs are easy to understand, and it has some nice async event handling features that are extremely useful. - It includes adapters for using schema validation libraries like Zod. - It is UI library/framework agnostic (currently has plugins to support React, React Native, and Solid) - Quality TypeScript support In my opinion, it’s the most intuitive and flexible form library out there. TanStack and all of its libraries are amazingly well designed. 10/10...

Jan 12, 2024

5 mins

TanStack QueryReact

How to Make Coding Both Your Hobby and Profession with Jason Lengsdorf @ CityJS Conf 2024

Join us backstage at CityJS Conf for this conversation with Jason Lengsdorf. In this discussion, we explore strategies for reducing stress and anxiety among engineers, ensuring they maintain relevance in the dynamic world of coding. Jason emphasizes the importance of self-assurance and the role of play in fostering continual engagement with evolving technologies. Moreover, we get a sneak peek into Jason's latest venture, "Web Lunch," a platform where he converses with developers who have found harmony between their careers and personal satisfaction. Coding isn't just a job; it's a passion and a lifestyle. Jason highlights the significance of pursuing work that excites and challenges us, echoing the sentiment that coding can be both a career and a hobby. By infusing enjoyment and creativity into our coding endeavors, we can shape our professional trajectories in alignment with our values and interests. This approach not only minimizes regret but also maximizes happiness and fulfillment in our careers. Central to our discussion is the pivotal role of effective leadership in creating a supportive and encouraging work environment. Leaders who prioritize the well-being and happiness of their team members foster a culture of collaboration and empowerment. Through mentorship, guidance, and opportunities for growth, these leaders enable developers to align their personal goals with organizational objectives, leading to increased job satisfaction and professional fulfillment. Adaptability is key to sustained success in software engineering. Jason emphasizes the value of remaining open-minded and continuously learning, even when it means stepping out of our comfort zones. Embracing discomfort is an integral part of personal growth, allowing us to overcome obstacles and unlock our full potential. By nurturing a spirit of curiosity and adaptability, developers can navigate the complexities of their careers with resilience and enthusiasm....

Apr 25, 2024

2 mins

JavaScriptMentorship

Level up your REST API's with JSON Schema

JSON Schema Basics

Types

Formats

Schema Structuring

JSON Schema Benefits

Validation

Security

Performance

Documentation

Type-safety

Schema Examples

Summary

Dane Grant

You might also like

End-to-end type-safety with JSON Schema

Building interactive forms with TanStack Form

How to Make Coding Both Your Hobby and Profession with Jason Lengsdorf @ CityJS Conf 2024

You might also like

End-to-end type-safety with JSON Schema

Building interactive forms with TanStack Form

How to Make Coding Both Your Hobby and Profession with Jason Lengsdorf @ CityJS Conf 2024