Harvest and transform FOLIO json schemas into a base GraphQL schema

[cbeer]

This PR uses the upstream JSON schemas to generate (the start of) a base GraphQL schema. Previously, our GraphQL schema was hand-crafted, but by automating some of the work we can get a more complete + consistent representation of the upstream APIs and set ourselves up better for consuming upstream updates.

The downside to all this is that the upstream schema expressions are not well-suited for using existing JSON schema to GraphQL schema tooling, including:

• missing $id properties, leaving the schemas unconnected and poorly named
• mangled $ref properties (or FOLIO-custom expressions) that expect to operate on a local file system (?)
• a variety of ways of referencing common models (like UUIDs), and a lot of cross-project duplication that ought to be reconciled for our convenience (or needs distinct names to fit within a single GraphQL schema). Unfortunately, there's also some almost-but-not-quite-the-same models for dereferenced information across models (see e.g. Loan items)
• bad data in the schema, missing properties or properties that are mistyped, need to be cleaned up.
• confusing inferred model name (e.g. Account would be the base model from mod_patron, and Accountdata would be the model for /accounts)

After all that, we still need to extend the generated schema with linking properties to connect various models together.

Perhaps something like #64 would let us keep the upstream-generated code fully separate from our enhancements.

---

As of this writing, the upstream schema to graphql converter isn't compatible with graphql 16, but it just needs a couple changes

--- /Users/cabeer/Projects/tmp/folio-json/a/node_modules/@lifeomic/json-schema-to-graphql-types/src/converter.js	2023-05-30 10:44:29
+++ node_modules/@lifeomic/json-schema-to-graphql-types/src/converter.js	2023-05-30 13:26:14
@@ -88,7 +88,7 @@
 
   context.enumMaps.set(attributeName, graphqlToJsonMap);
   const enumType = new GraphQLEnumType({
-    name: enumName,
+    name: normalizeTypeName(attributeName),
     values: mapValues(graphqlToJsonMap, function (value) {
       return { value };
     })
@@ -113,7 +113,7 @@
       const qualifiedAttributeName = `${typeName}.${attributeName}`;
       const type = mapType(context, attributeDefinition, qualifiedAttributeName, buildingInputType);
 
-      const modifiedType = includes(schema.required, attributeName) ? GraphQLNonNull(type) : type;
+      const modifiedType = includes(schema.required, attributeName) ? new GraphQLNonNull(type) : type;
       return { type: modifiedType, description: attributeDefinition.description };
     }),
     { type: DROP_ATTRIBUTE_MARKER }
@@ -128,7 +128,7 @@
     if (elementType === DROP_ATTRIBUTE_MARKER) {
       return DROP_ATTRIBUTE_MARKER;
     }
-    return GraphQLList(GraphQLNonNull(elementType));
+    return new GraphQLList(new GraphQLNonNull(elementType));
   }
 
   if (attributeDefinition.type === 'object') {

With those changes, you can run the npm run update-graphql-schema script and get the graphql output you can merge into the schema.graphql file

[marlo-longley]

I ran the following commands on this branch on got the error:

➜  folio-graphql git:(consume-folio-json-schemas) npm install

added 55 packages, changed 1 package, and audited 906 packages in 2s

➜  folio-graphql git:(consume-folio-json-schemas) npm run update-graphql-schema

> sul-folio-graphql-server@1.0.0 update-graphql-schema
> node scripts/generate-graphql-from-json-schemas.js json-schemas/

/Users/marloelilongley/Projects/folio-graphql/node_modules/@lifeomic/json-schema-to-graphql-types/src/converter.js:116
      const modifiedType = includes(schema.required, attributeName) ? GraphQLNonNull(type) : type;
                                                                      ^

TypeError: Class constructor GraphQLNonNull cannot be invoked without 'new'
    at /Users/marloelilongley/Projects/folio-graphql/node_modules/@lifeomic/json-schema-to-graphql-types/src/converter.js:116:71
    at /Users/marloelilongley/Projects/folio-graphql/node_modules/lodash/mapValues.js:38:34
    at /Users/marloelilongley/Projects/folio-graphql/node_modules/lodash/_createBaseFor.js:17:11
    at baseForOwn (/Users/marloelilongley/Projects/folio-graphql/node_modules/lodash/_baseForOwn.js:13:20)
    at mapValues (/Users/marloelilongley/Projects/folio-graphql/node_modules/lodash/mapValues.js:37:3)
    at getObjectFields (/Users/marloelilongley/Projects/folio-graphql/node_modules/@lifeomic/json-schema-to-graphql-types/src/converter.js:112:5)
    at fields (/Users/marloelilongley/Projects/folio-graphql/node_modules/@lifeomic/json-schema-to-graphql-types/src/converter.js:146:23)
    at resolveObjMapThunk (/Users/marloelilongley/Projects/folio-graphql/node_modules/graphql/type/definition.js:504:40)
    at defineFieldMap (/Users/marloelilongley/Projects/folio-graphql/node_modules/graphql/type/definition.js:766:20)
    at GraphQLObjectType._fields (/Users/marloelilongley/Projects/folio-graphql/node_modules/graphql/type/definition.js:691:26)

Node.js v18.8.0

[cbeer]

Oops - I forgot I made some local changes to the upstream library (which isn't compatible with the latest graphql... they have a ticket upstream..)

you've got to go in and add a couple new s 😬 (e.g. make that new GraphQLNonNull(type))

[marlo-longley]

OK will do -- but just so I'm clear, are we blocked on merging this until the upstream ticket is handled?

[cbeer]

I hope not. It's only a problem for running the sync script, but we don't need to do that regularly and we can always change a couple files in node_modules if we have to 🤷

[thatbudakguy]

i imagine you already considered it, but would using git submodules alleviate the problem of tracking the ref for each of the folio repos we want to pull in? there might be a clever way to specify that we only want shallow clones of each of them, and only some files, so that we don't need to commit all the JSON itself to this repo

[cbeer]

@thatbudakguy : if you feel strongly, maybe we can ticket that for investigation? I didn't bother because FOLIO is already a mess of submodules and the repositories themselves are pretty big. For as often as we'll need to sync, I'm not sure it's worth making things even more complex just yet.

[thatbudakguy]

i don't feel strongly, just wanted to check if you'd already investigated — i'm cool with this approach

[hudajkhan]

Works!