Using JSON Schemas to encode type information in HTTP responses

Introduction

Hey so I've been doing a-lot of REST API development in Go lately and recently stumbled upon the practice of using JSON Schemas as a way of including type information in HTTP responses.

Basically, if I have an type object on my server that I plan to send over to the client, I'm going to want to ensure the data I receive in the client matches the data that was sent on the server.

This is partly what Swaggers OpenAPI spec sets out to accomplish, but what we're doing isn't as complex or a involved. I like to think of this approach as a bare-bones version of what you'd expect from the OpenAPI spec.

In Practice

I want to work through what an implementation would look like because this was surprising challenging for me to find information about online. It'll be a pretty quick process and for simplicity, we won't dive too deep into edge cases.

1. Initialize an HTTP server in Go and serve a static HTML file
2. Create a route to serve JSON data over HTTP
3. Create a route to serve JSON schemas (dynamic) over HTTP
4. Validate on the client side (via the network tab)

Requirements

This is one of those follow along articles but the concept is universal as we're specifically focused on working with the HTTP protocol.

• Go https://go.dev/
• jsonschema github.com/invopop/jsonschema

Tbh the versions probably won't matter much here, but if it really does to you, then you'd find the most up-to-date answer in the jsonschema repository at https://github.com/invopop/jsonschema

Build a basic HTTP server

Lets begin be creating a new Go module, you could name it anything.

# create the directory and navigate into it
mkdir hello-world
cd hello-world

# initialize the module
go mod init hello-world

Create the main entry point for the application, and a static HTML file that we'll serve from the server via HTTP.

touch main.go
touch index.html

Put this in your index.html (or something else it truely doesn't matter)

Create a minimal server in the main.go file. We'll use the "net/http" module from the standard library for this example. We'll also omit error handling for an readability. You'll want to make a note to handle those in production.

package main

import (
	"log"
	"net/http"
)

func main() {
	http.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
    	http.ServeFile(w, r, "./index.html")
	})

	// Define the port for the server to listen on
	var port = ":8080"

	log.Printf("App runnign on %s\n", port)
    http.ListenAndServe(port, nil);
}

At this point we're ready to launch the server and pull up the application in a browser window. When ever you're ready we'll dive into the guts of this article

Create a JSON endpoint

Create an endpoint to serve the schema

package api

import (
    "encoding/json"
    "github.com/invopop/jsonschema"
)

func GetJsonSchema() ([]byte, error) {
    schema := jsonschema.Reflect(&UpdateProfileResponse{})
    return json.Marshal(schema)
}

func SchemaHandler(c *gin.Context) {
    schema, err := GetJsonSchema()
    if err != nil {
        c.JSON(500, gin.H{"error": err.Error()})
        return
    }

    c.Header("Content-Type", "application/schema+json")
    c.Data(200, "application/schema+json", schema)
}

Add schema information to your API responses

func UpdateProfileHandler(c *gin.Context) {
    // ... existing code ...

    c.Header("Content-Type", "application/json")
    c.Header("Link", "</api/v1/schema#/definitions/UpdateProfileResponse>; rel=describedby")
    c.JSON(http.StatusOK, response)
}

Create validation utilities on the front end

import Ajv from "ajv/dist/2020";
import addFormats from "ajv-formats";

// Initialize Ajv with your preferred options
const ajv = new Ajv({
  allErrors: true,
  removeAdditional: true,
  useDefaults: true,
});
// Add support for formats like email, date-time, etc.
addFormats(ajv);

export async function getSchema(schemaUrl: string): Promise<any> {
  const response = await fetch(schemaUrl);
  if (!response.ok) {
    throw new Error("Failed to fetch schema");
  }
  return response.json();
}

export async function validateResponse(response: Response): Promise<any> {
  const linkHeader = response.headers.get("Link");
  if (!linkHeader) {
    return response.json();
  }

  // Extract schema URL from Link header
  const schemaUrl = linkHeader.split(";")[0].slice(1, -1);
  const schema = await getSchema(schemaUrl);
  const data = await response.json();

  const validate = ajv.compile(schema);
  if (!validate(data)) {
    throw new Error("Response does not match schema");
  }

  return data;
}