TypeBox/JSON:API/OpenAPI Integration Strategies

[bosconian-dynamics]

Hello there 👋

I'm just getting started with TypeBox, JSON:API, and OpenAPI - and I think I'm already in love with all three - but I am struggling to integrate them.

Please forgive the length of this post and do not feel compelled to address any large part of it - I'm open to any and all input.

Background

Most of my TypeBox types representing my data are hand-written, but I also have others which are generated from my database schema using drizzle-typebox, with some properties overwritten with my hand-written types for the purposes of better validation and documentation.

Questions

At a high level, I'm generally just looking for any advice, suggestions, and/or examples with regards to how to compose my TypeBox types into an OpenAPI Description document. I have found many tools and resources for using the OAD as the source of truth, but far fewer for working in the opposite direction, using my database schemas and TypeBox types as the source of truth.

...Or perhaps I should be using the OAD as the source of truth for domain data and be converting the database objects to domain objects as necessary?

In my efforts thus far, I've ran into a few specific problems:

1. Embedding Types for logic while referencing them for schemas

Many of my data types have relationships to one another and depend on more atomic shared types, such as one representing the format of an Id value or a URL Slug.

My understanding is that in my logic, I need the dependency types to be used directly in the dependent types in order to match the format of the data itself. But in my OpenAPI Description, most of the schemas for these types will be enumerated at the /components/schemas path and should be referenced elsewhere in the document.

My best guess on how to achieve this is to create a TypeBox type for the schema, then dereference it into a second type for use in my logic. Is this a reasonable approach?

import { createSelectSchema } from 'drizzle-typebox';
import { type Static, Ref, Deref } from '@sinclair/typebox';

import { projects } from '@/lib/db/schemas/projects';

import { Id } from './Id';
import { Slug } from './Slug';

export const ProjectSchema = createSelectSchema(
  projects,
  {
    id: Id,
    slug: Ref(
      Slug,
      {
        description: 'An abbreviated human-friendly identifier used in URLs and file paths for the project. Must be unique.'
      }
    )
  }
);

export type ProjectSchema = Static<typeof ProjectSchema>;

export const Project = Deref(ProjectSchema, [Slug]);

export type Project = Static<typeof Project>;

I do really like that this enables me to override a dependency-type's description with something more relevant to the dependent type, but it leads into another question:

2. How to add SchemaOptions to types which do not provide a parameter for them?

In the example above, Id is a simple Type.Number({ minimum: 0, multipleOf: 1 }), but it may evolve into a more complex type down the road. I'd like to represent it's schema in the OAD at /components/schemas/Id and reference it from other types to reduce repetition and simplify a possible migration later, but Type.Number() does not support a SchemaOptions parameter so I cannot add an $id, and thus cannot pass it to Type.Ref().

Is there a utility for just adding this information to simple types?

3. Converting/mapping TypeScript types for compatibility with other packages

I would like to use my TypeBox-typed data with a few other tools such as ts-japi, and type my OAD itself with openapi-types - as a simplified example:

const oad: OpenAPIV3_1.Document = {
  openapi: '3.1.0',
  info: {
    title: 'FooBar API',
    version: '0.1.0'
  },
  paths: {
    '/projects': {
      [OpenAPIV3.HttpMethods.GET]: {
        responses: {
          '200': {
            description: 'OK',
            content: {
              'application/vnd.api+json': {
                schema: {
                  type: 'object',
                  properties: {
                    data: {
                      type: 'array',
                      items: ProjectSchema
                    }
                  }
                }
              },
            }
          }
        }
      }
    }
  },
  components: {
    schemas: {
      Slug,
      Project,
    }
  }
};

...but of course the TypeScript types are not inherently compatible:

Are these instances where I should start looking in to employing Unsafe() to convert the types? Something like

const OpenApiV3SchemaObject = <T extends TSchema>(schema: T) => Unsafe<OpenAPIV3_1.SchemaObject>({
  // ... ?
});

components: {
  schemas: {
    Slug: OpenApiV3SchemaObject(Slug),
    Project: OpenApiV3SchemaObject(Project),
  }
}

Or would this be barking up the wrong tree, and there is a more appropriate utility available?