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?)

[karenetheridge]

Adding new features on a trial basis using an extension keyword is what we have always recommended, when we're not quite sure how to formalize the behaviour or its syntax. Any work done in this direction would not be wasted and I see no reason not to encourage it.

Right now I am not quite sure what users want (and from other comments in this issue, I am not alone), so seeing something in action would help drive the discussion forward.

[handrews]

@karenetheridge All I am saying is that there has been disagreement over how to move forward so we should resolve that.

Right now I am not quite sure what users want (and from other comments in this issue, I am not alone), so seeing something in action would help drive the discussion forward.

Yes, we are all in agrement on that. We are not in agreement on how. As I acknowledged a few comments ago, I should not have spoken for the group suggesting implementing it as an overload. That was an oversight on my part for which I apologize.

But we still need to resolve this among all of the stakeholders, including folks who, AFAICT, agreed that it was not best served by an extension on the call.

At this moment, I am not taking a positon one way or the other, I am just saying that we need to resolve disagreement. What it feels like I am hearing from you is that we should disregard that and just do an extension, but that is the point of actual disagreement that we need to discuss. Not whether or not we need more information- everyone agrees on that part.

[karenetheridge]

we should disregard that and just do an extension

No, I was suggesting one possible avenue that a tooling implementor or contributor (not "we", the OpenAPI team) could take should they wish to forge ahead with an experiment. This is a technical opinion and suggestion about how that experiment could proceed, based on what I would do if I were to implement this, given my personal experience with implementing experimental features. This is just one option -- I think it is far too soon to rule in or out any particular direction until we have a better idea of user requirements, and also the technical restrictions imposed on us by CDDL/CBOR/etc.

It is in no way a directive or an instruction, as I have no such authority on such matters.

[handrews]

@karenetheridge thanks for the clarification. I will continue trying to understand your comments better as I know I've mis-perceived quite a few in recent months. Thank you for your patience.

[mikekistler]

Discussions are strange! Hard to know where to comment.

Sorry I had to drop halfway through today's meeting, so maybe this was clarified after I dropped, but I'm still not clear on what the requirement is. Is it:

• We want a way to better describe CBOR payloads, or
• We want a better way to describe payloads, whatever the content type is.

We did discuss in the meeting that CDDL could describe JSON ... @handrews linked to something that described that ... but that's not what the example above illustrates. In the example, as I understand it, CDDL describes CBOR and JSON Schema is still used to describe a JSON payload.

So I'd like more clarity on which of these we are trying to solve for.

[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.

[handrews]

@OR13 From today's TDC call, one thing we'll need is more context around what CBOR and CDDL and why people want to use them in OpenAPI. From what folks on the call knew, some of the use cases including an all-binary (CBOR over HTTP/2 or HTTP/3) performance upgrade, while I had some vague notion that it's used in the finance industry, particularly with COSE. Which would actually fit with our 3.x focus on security.

There is also interest in understanding use cases and level of demand for using CDDL with JSON vs CBOR. How much of a crossover is there? Are there cases where you would offer both CDDL and JSON Schema at the same time? When content-negotiating CBOR vs JSON? Or on other conditions?

I think we need to understand exactly who needs this and why, which will help us understand how to think about what "support" would mean here if we were to add it. We need to undersand the audience for this, and how it relates to the current, mostly JSON-over-HTTP, OpenAPI audience.