Skip to content

Implement data validation for openapi with zod #23

@kainpets

Description

@kainpets

We basically want to go from this:

export const TypesModuleSchema = z.object({
  codeSampleDefinitions: z.array(CodeSampleDefinitionSchema).default([]),
  // TODO: Import and use openapi zod schema here
  openapi: z.any(),
})

export type TypesModuleInput = z.input<typeof TypesModuleSchema>

export type TypesModule = z.output<typeof TypesModuleSchema>

export const createBlueprint = (typesModule: TypesModuleInput): Blueprint => {
  const { codeSampleDefinitions } = TypesModuleSchema.parse(typesModule)

  // TODO: Move openapi to TypesModuleSchema
  const openapi = typesModule.openapi as Openapi

to this

export const TypesModuleSchema = z.object({
  codeSampleDefinitions: z.array(CodeSampleDefinitionSchema).default([]),
  openapi: Openapi,
})

export type TypesModuleInput = z.input<typeof TypesModuleSchema>

export type TypesModule = z.output<typeof TypesModuleSchema>

export const createBlueprint = (typesModule: TypesModuleInput): Blueprint => {
  const { codeSampleDefinitions } = TypesModuleSchema.parse(typesModule)
  const openapi = OpenapiScheam.parse(openapi)

We don't need to implement a perfect openapi zod schema, we only need to implement what we need to support or expect. For example, there are limits on expected nesting or complexity. Additionally, we don't care about large parts of the schema (anything other than the 200 response).

The idea is that by doing the parsing up front, the documentation author will get feedback on any invalid properties. This will simplify code complexity and correctness as the parsing step can fill in defaults and ensure things are not null, etc.

There is a risk that implementing this parsing is a deep hole of complexity. In order to break down the problem, partial parsing schemas are defined in https://github.com/seamapi/blueprint/blob/main/src/lib/openapi-schema.ts and used as needed. The goals is to eventually combine these schemas into a single OpenapiSchema and do parsing once at the top of createBlueprint.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions