Support for CDDL

[OR13]

I would like to see support for CDDL.

Here is a straw-man:

openapi: 3.1.0
$self: https://example.com/schema.cddl
info:
  title: API
  version: 1.0.0
paths:
  /example:
    post:
      requestBody:
        content:
          application/cbor:
            schema: 
              $id: RequestInCbor
          application/json:
            schema: 
              $id: RequestInJson
      responses:
        '200':
          description: OK
          content:
            application/cbor:
              schema: 
                $id: ResponseInCbor
            application/json:
              schema: 
                $id: https://example.com/schema.cddl#ResponseInJson

This could be useful for other data definition languages.

[karenetheridge]

Could you describe what new behaviour you're expecting to see?

(And the $id on the last line of your example is invalid -- perhaps you meant to use $ref instead, and $anchor instead of $id on the other lines?)

[OR13]

Similar to how json schema should validate a given request or response in JSON.
Using CDDL it should be possible to validate a given request or response in CBOR (or JSON, as CDDL can validate both).

The intention of the strawman was to cover cases where schema by reference could be extended to schema languages other than JSON.

The cases that should be considered are generally:

• By relative reference against a base url.
• By absolute reference
• By value.

I observe that by value is tricky for existing "schema" because it expects an object, so my hope was to simply use enough of existing JSON Schema properties to point to other schema files, and perhaps avoid the need to embedded CDDL by value, since that would have to be a string.

[handrews]

@OR13 there are a couple of things here (and let me note that I have floated CBOR/CDDL support as something worth exploring in the past, but we have not gotten around to to thinking about it more deeply):

1. We would probably want to figure out how to support CBOR as a media type as part of this. As you note, it's not strictly necessary as CDDL can apply to JSON, but it would seem odd to support CDDL but not CBOR. That has been previously requested at Support for CBOR #3108 (prior to us moving feature requests to Discussions).
2. We've considered supporting alternate schema systems before, and it kind-of fizzled around the time of 3.1 as we added full JSON Schema support. But IIRC it was never outright rejected, just left in a "we're already asking a lot from implementors here, let's put this on hold" state. You can still see the old proposal, and the registry was put up (but not advertised? I'm honestly not sure what is going on there as there's no OAS field that lets you use the registry unless it's something like x-alternative-schema). Which brings us to...
3. The tooling ecosystem still hasn't entirely implemented JSON Schema draft 2020-12 support. Most have caught up, but a few seem stuck. It's unclear that thrown a huge new requirement for another modeling/validating system would work. Would all tools be expected to support it? You would need that for true interoperability. Would it make sense to make it optional in some way, and if so how would that work? This is also relevant regarding things like XML Schema, which continue to come up as well.

[OR13]

It seems likely that many implementers might never use CDDL or CBOR.

Imo, it should be possible to ignore what you don't understand as much as possible.

In terms of next steps, perhaps some prototype code could help demonstrate the desirable outcome.

[handrews]

@OR13 I think the behavior is fairly well-understood, the trick is figuring out the support story. As you note, many implementers/users might never use CDDL or CBOR. Do we make support for it optional? What does that mean for interoperability? Is there "OAS-for-CBOR" distinct from "OAS-for-JSON"? Of course it's not the simple because you can use CDDL with JSON.

These are exactly the questions that caused the old alternative schemas proposal to get shelved, IIRC, and we still need to answer them.

Once answered, putting something in the spec is straightforward, as it is just another syntax for the same conceptual behavior as the current Schema Object (same if we wanted to support XSD).

[OR13]

Make support for CDDL optional.
Allow CDDL for CBOR or JSON.