encoding/openapi: schema validation

[vikstrous2]

Is your feature request related to a problem? Please describe.
I would like to be able to validate that a given yaml file or cue config is a valid openapi schema.

Describe the solution you'd like
CUE can normally import protobuf or go code definitions, but in the case of openapi, I believe the spec is defined in a document, not in code, so there might not be an automatic way to import it. Maybe someone would have to transcribe the spec into hand crafted CUE definitions.

Describe alternatives you've considered
I haven't tried generating openapi schemas from cue with https://pkg.go.dev/cuelang.org/go/encoding/openapi. The first issue is that we use openapi v2 and this package supports only v3. The second is that it sounds like we wouldn't get the full flexibility of openapi if we used this method.

Additional context
Let me know if there's a directory of definitions for popular standards that I'm not aware of.

[myitcv]

Thanks for raising this @vikstrous2.

I would like to be able to validate that a given yaml file or cue config is a valid openapi schema.

There are potentially two parts to this. Can you clarify what you mean by validate that a given CUE config is a valid openapi schema? Because generally speaking, CUE itself is exported into an openapi format, and that process is validated. However, if you are talking about a straight CUE representation of an openapi schema, then validating such CUE is equivalent to validating the Yaml or JSON representation of that schema.

I'll assume you mean the latter. If so, via SchemaStore I've just stumbled across the OpenAPI specified as a JSON Schema. I think this satisfies what you're after?

Sadly, there is either a problem with that schema, or CUE: #1168

Regarding the use of encoding/openapi. I'm not entirely clear whether we validate that the input to an import of an OpenAPI specification is valid (we probably should), other than ensuring the fields we try and parse are of the correct type (the specific case I have in mind is whether we validate additional fields or not). However, if any field is of the incorrect type/inconsistent, the import will fail so that is one mechanism that could do what you need:

exec cue import openapi+yaml: schema.yaml
cmp schema.cue schema.cue.golden

-- schema.yaml --
components:
  schemas:
    Bar:
      properties:
        foo:
          $ref: '#/components/schemas/Foo'
      required:
      - foo
      type: object
    Foo:
      properties:
        a:
          type: integer
        b:
          exclusiveMaximum: 10
          minimum: 0
          type: integer
      required:
      - a
      - b
      type: object
info:
  title: My OpenAPI
  version: v1alpha1
openapi: false
paths: {}
-- schema.cue.golden --
// My OpenAPI

info: {
	title:   *"My OpenAPI" | string
	version: *"v1alpha1" | string
}

#Bar: {
	foo: #Foo
	...
}
#Foo: {
	a: int
	b: <10 & int & >=0
	...
}

[vikstrous2]

1. Yes, sorry for the confusion. I was thinking of "a straight CUE representation".
2. Thanks for the json schema for openapi link! It makes sense that there would be one.
3. I didn't know that there's a way to import openapi schemas. That's really interesting. Unfortunately, that works only with openapi v3. It fails on my schema when looking for "components", which is only part of the v3 spec.
4. I'm confused by your attempt to use cue import on a json schema. Does cue import automatically detect that this is a json schema and not just a json file? If importing json schema specs into cue is something that magically works and I didn't know about, you can close this issue and the best solution is probably getting cmd/cue: cannot import OpenAPI JSON Schema specification #1168 working.

In general, I see CUE as being able to fulfill a similar role to a json schema, so it would be really cool to have a similar "schema store", but that's off topic :)

[myitcv]

3. I didn't know that there's a way to import openapi schemas. That's really interesting. Unfortunately, that works only with openapi v3. It fails on my schema when looking for "components", which is only part of the v3 spec.

If you have a specific need for this, please do raise a request. We have, in the past, had many discussions about how to support different versions of different encoding, including different flavours (e.g. Yaml). Having specific examples/use cases will help to firm up those ideas.

4. Does cue import automatically detect that this is a json schema and not just a json file?

Yes it does. Although you can be specific about the encoding if you want/need (see cue help filetypes).

so it would be really cool to have a similar "schema store", but that's off topic :)

Absolutely not off-topic at all! It's very much the goal of #851. i.e. that CUE packages can be imported and used wherever. Perhaps note #851 (comment) in particular (which links to #438).

[vikstrous2]

I feel like validating and enhancing our openapi v2 spec with cue validation and a little bit of templating feels like a clear win. The blocker for that is #1168

I'm not as excited to just hand off the whole schema generation process to the cue export tool and have it magically produce openapi v2 specs for me. I worry that I would be exercising obscure code paths that not a lot of people use and as soon as I hit an edge case, the only solution would be to fix the cue export feature. I also worry that there might be certain openapi v2 schemas that cue can't produce or that I'd lose control of the details of the produced schema.

I don't feel like importing/exporting openapi v2 is the way to go for us, but there may be others interested in this, so I'll let someone else open that issue if they want it.