Skip to content

Investigate OpenApi Spec from Directus to import the types, blocks #9

  • Compare openapi-zod-client, typed-openapi, elm-open-api (effortless-sdks/)

  • Matches with our current infrastructure (Directus and Astro)?

  • Generates all necessary types?

  • Is maintained and can be contacted?

  • Re-implement the OAS3 fetcher / schema generator

  • Use types in Astro

    • Do we want to continue using typescript?

Need: Derive strong types and content collection schema from OpenAPI

I've had problems with the Directus API and with mapping it to typescript which I feel is too complex for maintainability.

We definitely don't want to implement the content collection spec as a separate manual step because it'll cause friction with the evolving backend ontology.

The goal is an automated mapping from the backend-defined structure to the frontend types, such that any change in the backend type ontology is a breaking change for the frontend. This concerns the Astro Content Collection engine which relies on zod schemas, and the widgets we foresee to use.

Strong types should not be an end to itself. A php-style templating cascade doesn't need a type system. It needs good naming and as much cohesion as possible.

Editors and cross-site features benefit from strong typing: it becomes impossible to manually test for desired invariants once the number of dimensions grows.

Approach: Investigate the OAS3 spec

  • Learn more about how Directus generates the spec; what the errors I have encountered mean; what it encodes
  • Find solid ways to exploit it as a source for types and specs:
    • Content Collection Schema (zod)
    • Types (typescript, Hindley-Milner)

We can work with a mix of untyped JS and strongly typed elm on the frontend.

For example, we can offer nice wysiwyg editors through elm-in-an-island within astro. Elm would be a custom element with ports for reading and writing the Url, and less-ui can do its job inside (needs to implement element-with-url)

Idea 1: Use a script on node to generate the zod schema

https://github.com/astahmer/openapi-zod-client

https://github.com/astahmer/typed-openapi

Idea 2: Use an Elm service-worker on node to generate the zod schema

Recently, wolfadex published https://www.npmjs.com/package/elm-open-api

Described on https://wolfgangschuster.wordpress.com/2023/10/08/effortless-sdks/

which generates frontend bindings to an OpenApi3 specced backend. His application examples include:

  • Auto documentation and doc publishing
  • Auto types