Generating jsonschema from cue

[cueckoo]

Originally opened by @khepin in cuelang/cue#663

Wanted / needed to generate jsonschema from a cue file and while that isn't directly supported, I found a couple tools that you can stitch together to achieve that:

Here's the cue file:

#Root: {
	name:    string
	address: #Address
}

#Address: {
	street:  string
	region:  string
	country: string
	zip:     string
}

From this, cue can generate an open api specification cue export --out openapi test.cue

Which gives us the following openapi spec:

{
   "openapi": "3.0.0",
   "info": {
      "title": "Generated by cue.",
      "version": "no version"
   },
   "paths": {},
   "components": {
      "schemas": {
         "Address": {
            "type": "object",
            "required": [
               "street",
               "region",
               "country",
               "zip"
            ],
            "properties": {
               "street": {
                  "type": "string"
               },
               "region": {
                  "type": "string"
               },
               "country": {
                  "type": "string"
               },
               "zip": {
                  "type": "string"
               }
            }
         },
         "Root": {
            "type": "object",
            "required": [
               "name",
               "address"
            ],
            "properties": {
               "name": {
                  "type": "string"
               },
               "address": {
                  "$ref": "#/components/schemas/Address"
               }
            }
         }
      }
   }
}

With that, there are a couple tools online that claim to go from openapi to jsonschema. The one I found that seems up to date and actually worked was: https://www.npmjs.com/package/@openapi-contrib/openapi-schema-to-json-schema
With the following javascript / nodejs code:

var toJsonSchema = require('@openapi-contrib/openapi-schema-to-json-schema');
var openapi = require('../test.openapi.json')

var conv = {
    "components": {
        schemas: {}
    }
}
for (s in openapi.components.schemas) {
    conv.components.schemas[s] = toJsonSchema(openapi.components.schemas[s])
}
root = conv.components.schemas.Root
delete conv.components.schemas.Root
console.log(JSON.stringify({
    ...conv,
    ...root
}))

We finally get our jsonschema:

{
  "components": {
    "schemas": {
      "Address": {
        "type": "object",
        "required": [
          "street",
          "region",
          "country",
          "zip"
        ],
        "properties": {
          "street": {
            "type": "string"
          },
          "region": {
            "type": "string"
          },
          "country": {
            "type": "string"
          },
          "zip": {
            "type": "string"
          }
        },
        "$schema": "http://json-schema.org/draft-04/schema#"
      }
    }
  },
  "type": "object",
  "required": [
    "name",
    "address"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "address": {
      "$ref": "#/components/schemas/Address"
    }
  },
  "$schema": "http://json-schema.org/draft-04/schema#"
}

I briefly verified it at https://www.jsonschemavalidator.net/ and it seems to behave correctly. I haven't tested more advanced use cases though, but for simple ones this works well.

So by using cuelang + golang + javascript, you get a jsonschema that you can now import and use in your I guess!

[cueckoo]

Original reply by @bfallik in cuelang/cue#663 (comment)

I'm just getting started learning cue so I was wondering why the need for Go code in that chain above? I would have expected cue to be able to output openapi directly and my local tests seem to confirm that it can:

%!c(MISSING)ue version
cue version 0.3.0-beta.3 darwin/amd64
%!c(MISSING)at foo.cue
#Root: {
	name:    string
	address: #Address
}

#Address: {
	street:  string
	region:  string
	country: string
	zip:     string
}

%!c(MISSING)ue export --out openapi foo.cue
{
    "openapi": "3.0.0",
    "info": {
        "title": "Generated by cue.",
        "version": "no version"
    },
    "paths": {},
    "components": {
        "schemas": {
            "Address": {
                "type": "object",
                "required": [
                    "street",
                    "region",
                    "country",
                    "zip"
                ],
                "properties": {
                    "street": {
                        "type": "string"
                    },
                    "region": {
                        "type": "string"
                    },
                    "country": {
                        "type": "string"
                    },
                    "zip": {
                        "type": "string"
                    }
                }
            },
            "Root": {
                "type": "object",
                "required": [
                    "name",
                    "address"
                ],
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "address": {
                        "$ref": "#/components/schemas/Address"
                    }
                }
            }
        }
    }
}

[cueckoo]

Original reply by @khepin in cuelang/cue#663 (comment)

Updated with that. Much easier indeed. I'd completely missed that somehow.

[cueckoo]

Original reply by @myitcv in cuelang/cue#663 (comment)

I think you can even do this as a one-line with cmd/cue:

cue export --out openapi | cue import json: - | cue eval -e 'components.schemas.Root & components & {$schema: "http://json-schema.org/draft-04/schema#"}' - | cue export --out json -

The trick here being to import the exported JSONSchema as json (which overrides the detection of it as jsonschema), evaluate an expression, then re-export as json.

Untested, but it looks about right?

[cueckoo]

Original reply by @myitcv in cuelang/cue#663 (comment)

Note the starting point here was the following:

// schema.cue
package schema

#Root: {
	name:    string
	address: #Address
}

#Address: {
	street:  string
	region:  string
	country: string
	zip:     string
}

[cueckoo]

Original reply by @bfallik in cuelang/cue#663 (comment)

Neat. I admit I don't understand that one liner yet but I'll have to dig in and figure it out.

[cueckoo]

Original reply by @khepin in cuelang/cue#663 (comment)

That one liner works properly on this specific example but wouldn't work on more advanced example. For example if we change the region property of address to be: region: string | null, the final result would contain:

{
    "region": {
        "type": "string",
        "nullable": true
}

Which isn't valid jsonschema. The valid version would be:

{
    "region": {
        "type": [
            "string",
            "null"
        ]
    }
}

[cueckoo]

Original reply by @khepin in cuelang/cue#663 (comment)

That's why I needed a separate tool to do the conversion, there are divergences like that between openapi and jsonschema.

[cueckoo]

Original reply by @myitcv in cuelang/cue#663 (comment)

@khepin absolutely - I should have been more clear it was just for this case. Thank you for stressing that.

[cueckoo]

Original reply by @mpvl in cuelang/cue#663 (comment)

We do plan to add a native to jsonschema converter, but for for now the focus is on the v0.3.0 release (getting close!).

[cueckoo]

Original reply by @ying-jeanne in cuelang/cue#663 (comment)

Hi @mpvl and CUErs :),

I would have to start converting cue into Jsonschema with golang soon, would like to know whether we currently have a converter already? or I would have to do the cue export suggested above.

Thanks.

[cueckoo]

Original reply by @myitcv in cuelang/cue#663 (comment)

Hi @ying-jeanne - there is no further update to Marcel's comment in cuelang/cue#663 (comment)

I have opened cuelang/cue#929 to track this.

[cueckoo]

Original reply by @mpvl in cuelang/cue#663 (comment)

This is currently not implemented. So the OpenAPI workaround is indeed your best bet for now.

[RajasGujarathi]

Not everything is possible using the OpenAPI approach, do we have still this on the roadmap?

[justenstall]

@RajasGujarathi here is the corresponding issue, it's still open with some discussion but not much activity: #929