Investigate alternatives to json-schema-to-graphql-types

[cbeer]

We use lifeomic/json-schema-to-graphql-types to automagically convert from FOLIO's JSON schemas to graphql schemas. Unfortunately, it isn't compatible with Graphql 16, and a year later seems like it may never be.

Is there something new or better out there, or should we fork or pull the code into this repo?

[marlo-longley]

Here’s what I’ve learned:

• There is not a replacement library that does approximately the same thing as lifeomic (transforming json-schema into graphql schema). If we want to keep things relatievely the same, I think we should import this code and make required adjustments locally.
• if we want to rewrite some of our stack here, there are different tools we could consider. Specifically I researched the tools available through graphql-mesh. graphql-mesh could technically be a total replacement for our apollo server architecture but I am considering it here for it’s schema-generating tools, which are more robust than what apollo offers.
  • Here’s a comparison (written by mesh!) https://the-guild.dev/graphql/mesh/docs/getting-started/comparison
  • Here’s what Apollo has to say for themselves: https://www.apollographql.com/blog/three-ways-to-represent-your-graphql-schema.
  • Mesh tools can work directly with json-schema files to generate a schema, which is the essential function we are getting out of lifeomic. Apollo tools cannot (the json it can work with is introspection json, generated from an existing graphql server).

Mesh

I found 2 possible paths for generating schemas given what we have from FOLIO. These involve 2 different “handlers”. Options can be configured in a meshrc.yml file and a schema can be built with npm run mesh build. If we went forward with this, we would set something up to copy this schema to the proper place in our setup after generation assuming the rest of our stack remains the same.

1. 1st mesh option: json-schema handler
   Using json-schema sources from FOLIO, you can generate a schema using the provided example files (example). We would get these from FOLIO Github, similarly to how we use FOLIO Github now. Then we’d reference them in config. The downside is that this config would get pretty huge with entries per endpoint or type. I got this working successfully with a limited number of fields, though.

// package.json
"@graphql-mesh/cli": "^0.88.9",
"@graphql-mesh/json-schema": "^0.98.2",

// .meshrc.yml
sources:
  - name: APIs
    handler:
      jsonSchema: 
        operations:
          - type: Query
            field: item
            responseSample: ./samples/callnumbertype.json
            responseTypeName: Item        

2. 2nd mesh option: postgres handler
   This option is intriguing. I tried it on okapi-test with success on a limited number of tables.

// package.json
"@graphql-mesh/cli": "^0.88.9",
"@graphql-mesh/postgraphile": "^0.96.6",

// .meshrc.yml
sources:
  - name: FolioDB
    handler:
      postgraphile:
        connectionString: postgres://okapi:password@localhost:5432/okapi
        schemaName: ["sul_mod_circulation_storage", "sul_mod_courses"]
        appendPlugins:
          - './my-plugin.js'

I got further with this approach than the one above. The cool thing here is that we could remove the existing setup of linking with the FOLIO Github repositories to pull the JSON schemas. This approach relies on the graphile library which is pretty powerful https://www.graphile.org/postgraphile/usage-library/. They offer the ability to do transforms https://the-guild.dev/graphql/mesh/docs/transforms/transforms-introduction and write custom plugins that, in theory, could do a lot of what we are doing in generate-graphql-from-json-schema.js such as renaming and merging types.

• This would need further prototyping to make sure we can get the schema exactly how we want and resolve conflicts between modules, and import into our existing architecture. I didn't want to take too much time away from the workcycle doing this yet.

To summarize

I recommend importing the lifeomic library locally for the simplest transition. If we are more ambitious we can try prototyping an approach using mesh and graphile that would simplify our process of generating the graphql schema, eliminating the complex process of importing json-schemas from git.