What replaces Type.Module and Type.Import usage in version 1.0

[cyky]

We used Type.Module with Type.Imports before upgrading to version 1.0 in our project.

The flow that we used was kinda following:

export const HumanModule = Type.Module({
  AddressSchema: Type.Object({
    street: Type.String(),
    streetNumber: Type.Number(),
  }),
  PersonSchema: Type.Object({
    name: Type.String(),
    homeAddress: Type.Ref('AddressSchema'),
    workAddress: Type.Ref('AddressSchema'),
  }),
  PostRequestSchema: Type.Object({
    person: Type.Ref('PersonSchema'),
  }),
});

export const PersonResponseSchema = Type.Object({
  status: Type.String(),
});

export const FooSchema = {
  post: {
    request: HumanModule.Import('PostRequestSchema'),
    response: {
      200: PersonResponseSchema,
    },
  },
};

(example copied from here: fastify/fastify-swagger#854 (comment))

This allowed us to generate correct refs in our fastify application for our schemas. Using for example HumanModule.PostRequestSchema doesn't seem to work in the same way as previously the Import did.

Now with the new version I'm bit unsure how we can archive the similar functionality and I did not find any mentions regarding removal of Type.Import in the migration notes (https://github.com/sinclairzx81/typebox/blob/main/changelog/1.0.0-migration.md)

[sinclairzx81]

@cyky Hi,

Module is still supported, Import was deprecated in favor of left-side destructuring.

Reference

import Type from 'typebox'

type AddressSchema = Type.Static<typeof AddressSchema>
type PersonSchema = Type.Static<typeof PersonSchema>
type PostRequestSchema = Type.Static<typeof PostRequestSchema>

export const { AddressSchema, PersonSchema, PostRequestSchema } = Type.Module({
  AddressSchema: Type.Object({
    street: Type.String(),
    streetNumber: Type.Number(),
  }),
  PersonSchema: Type.Object({
    name: Type.String(),
    homeAddress: Type.Ref('AddressSchema'),
    workAddress: Type.Ref('AddressSchema'),
  }),
  PostRequestSchema: Type.Object({
    person: Type.Ref('PersonSchema'),
  }),
})

Alternatively you can use a indexed accessors to infer module sub schemas.

Reference

import Type from 'typebox'

type AddressSchema = Type.Static<typeof HumanModule['AddressSchema']>
type PersonSchema = Type.Static<typeof HumanModule['PersonSchema']>
type PostRequestSchema = Type.Static<typeof HumanModule['PostRequestSchema']>

export const HumanModule = Type.Module({
  AddressSchema: Type.Object({
    street: Type.String(),
    streetNumber: Type.Number(),
  }),
  PersonSchema: Type.Object({
    name: Type.String(),
    homeAddress: Type.Ref('AddressSchema'),
    workAddress: Type.Ref('AddressSchema'),
  }),
  PostRequestSchema: Type.Object({
    person: Type.Ref('PersonSchema'),
  }),
})

// ... as per provided example

export const PersonResponseSchema = Type.Object({
  status: Type.String(),
});

export const FooSchema = {
  post: {
    request: HumanModule.PostRequestSchema,
    response: {
      200: PersonResponseSchema,
    },
  },
};

Hope this helps!
S

[paulius-valiunas]

In pre-1.0 versions we used modules to make the resulting JSON schema more human readable, so it could be published as part of our OpenAPI documentation. If Typebox started inlining schemas as much as possible, we lose that advantage and I guess using modules is the same as simply copying schemas in Typescript:

export const AddressSchema = Type.Object({
  street: Type.String(),
  streetNumber: Type.Number(),
});
export const PersonSchema = Type.Object({
  name: Type.String(),
  homeAddress: AddressSchema,
  workAddress: AddressSchema,
});

Of course there's still the advantage of being able to declare schemas out of order and have cyclic dependencies.

[cyky]

I did not manage to get this working for our use case.

One thing that I probably didn't mention was that in pre 1.0 typebox we used multiple different Type.Module definitions that had bit of cross referencing between them.

Something like this:

export const CommonModule = Type.Module({
  Uuid: Type.String({ format: 'uuid' }),
  DateTime: Type.String({ format: 'date-time' }),
});

export const HumanModule = Type.Module({
  AddressSchema: Type.Object({
    id: CommonModule.Import('Uuid'),
    street: Type.String(),
    streetNumber: Type.Number(),
  }),
  PersonSchema: Type.Object({
    id: CommonModule.Import('Uuid'),
    name: Type.String(),
    homeAddress: Type.Ref('AddressSchema'),
    workAddress: Type.Ref('AddressSchema'),
    modified: CommonModule.Import('DateTime')
  }),
  PostRequestSchema: Type.Object({
    person: Type.Ref('PersonSchema'),
  }),
})

This allowed us to have the common types that are used a lot within our responses to be defined once in the generated openapi schema and the other types would reference those.

However I still guess this wasn't the intended use case for this library(?) and the inlining the types probably works for most of the typebox users.

[sinclairzx81]

@cyky Hi,

I have been working on a new API for modules layouts based on the MCP protocol specification (which makes heavy use of $def and $ref) https://tsplay.dev/wEKObm

import { type Static } from 'typebox'

type ProtocolTypes<Spec extends { '$defs': Record<string, unknown> }> = {
  [Def in Extract<keyof Spec['$defs'], string>]: Static<Spec & { $ref: `#/$defs/${Def}` }>
}

I am mostly using their specification as a basis for scaling up the Json Schema inference backend (which is new in 1.0), but where it creates some options for Module representations outside those directly supported by TypeBox.

However I still guess this wasn't the intended use case for this library(?) and the inlining the types probably works for most of the typebox users.

I think there is value in non-inlined schematics, but getting the API design right for it has been quite difficult. The 1.0 Module API is mostly in service to Script types where each definition produces a standalone inline type, and I am weighing whether it's better to introduce an intermediate step between the referential types that would be produced by Script, and the inlining step which reduces them all down to standalone schematics, or whether I support functionality via the new Json Schema inference system (which would let you define your own API for modules)

I am open to thoughts.

[cyky]

In the end it seems like I got it working by using "custom ref" implementation like mentioned here: fastify/fastify-type-provider-typebox#240 (comment)

Basically it means that instead of CommonModule.Uuid I use Ref(CommonModule.Uuid) and I just use modules as a container that hold together our schema definitions.

On fastify side I need to iterate through the modules and add the schemas for ajv.

I checked the tsplay.dev link and it seems useful when you need to transform json into types but our issue is the otherway around.

Maybe some kind of option for module usage would help us. Inlining the refs is fine but I think if the object would still have the $ref definition would allow tools like fastify/swagger and the typebox provider to generate openapi schemas that are smaller.

Thanks again for you replies. You've built awesome library 💪

[sinclairzx81]

@cyky Hi,

I checked the tsplay.dev link and it seems useful when you need to transform json into types but our issue is the otherway around.

Ah, that was just a reference I had been working on at the time, but you can use that technique to emulate the 0.34.x Module ... but does require getting low level with the new V1 inference system (it's not too bad)

GraphicsModule Reference

import Type from 'typebox'

// ------------------------------------------------------------------------------
// TImport<Module, Ref>
//
// Import definitions from { $defs } schematics.
// ------------------------------------------------------------------------------
export type TImport<Module extends { $defs: Type.TProperties }, Ref extends string = Extract<keyof Module['$defs'], string>> = (
  Module & { $ref: `#/$defs/${Ref}` }
)
export function Import<Module extends { $defs: Type.TProperties }, Ref extends string = Extract<keyof Module['$defs'], string>>(module: Module, ref: Ref): TImport<Module, Ref> {
  return { ...module, $ref: `#/$defs/${ref}` } as never
}

// ------------------------------------------------------------------------------
// GraphicsModule
//
// Layout for cross-dependent type definitions
// ------------------------------------------------------------------------------
export const GraphicsModule = {
  $defs: {
    Vector2: Type.Object({
      x: Type.Number(),
      y: Type.Number()
    }),
    Vector3: Type.Object({
      x: Type.Number(),
      y: Type.Number(),
      z: Type.Number()
    }),
    Vertex: Type.Object({
      position: Type.Ref('#/$defs/Vector3'),
      normal: Type.Ref('#/$defs/Vector3'),
      texcoord: Type.Ref('#/$defs/Vector2'),
    }),
    Geometry: Type.Object({
      vertices: Type.Array(Type.Ref('#/$defs/Vertex')),
      indices: Type.Array(Type.Integer())
    }),
    Material: Type.Object({
      ambient: Type.Ref('#/$defs/Vector3'),
      diffuse: Type.Ref('#/$defs/Vector3'),
      specular: Type.Ref('#/$defs/Vector3'),
    }),
    Mesh: Type.Object({
      geometry: Type.Ref('#/$defs/Geometry'),
      material: Type.Ref('#/$defs/Material'),
    })
  }
} as const

// Inference

export type Vector2 = Type.Static<typeof Vector2>
export type Vector3 = Type.Static<typeof Vector3>
export type Vertex = Type.Static<typeof Vertex>
export type Geometry = Type.Static<typeof Geometry>
export type Material = Type.Static<typeof Material>
export type Mesh = Type.Static<typeof Mesh>

export const Vector2 = Import(GraphicsModule, 'Vector2')
export const Vector3 = Import(GraphicsModule, 'Vector3')
export const Vertex = Import(GraphicsModule, 'Vertex')
export const Geometry = Import(GraphicsModule, 'Geometry')
export const Material = Import(GraphicsModule, 'Material')
export const Mesh = Import(GraphicsModule, 'Mesh')

---

I haven't figured out an ideal API for this (maybe the above just works), but the V1 API is a bit more conducive to supporting custom composition types, and mixing and matching TB with Json Schema.

I will be documenting some of these techniques in early next year once i finalize the schema compiler system.
Again, hope this helps
S