Re: [httpapi] OpenAPI media type

[Henry Andrews <[e-mail]>]

 I would think that as long as the OpenAPI media type describes the "handoff" to the schema format (whether that is OAS 3.0's modified JSON Schema, or OAS 3.1's fully compatible usage), that should be sufficient for the full stack to be interoperable if/when a JSON Schema media type is registered.
I think there are basically two aspects of the hand-off:
Status of embedded schema objects:
Deciding whether Schema Objects are simply part of the OAS content or are their own resources embedded in the OAS resource, with the base URI determined according to RFC 3986 section 5.1.2 "Base URI from the Encapsulating Entity"; using the 5.1.2 approach provides a clear hand-off to the "initial base URI" section of the JSON Schema spec, and avoids requiring OAS 3.1 and later to get specific about things like the "$id" keyword.
Meta-schema determination:
Ensuring that in OAS 3.1+, the mechanism for determining the meta-schema in the absence of "$schema" (for an embedded schema object) or the absence of both "$schema" and other mechanisms such as media type parameters (for a separate schema resource) is clear.  I think there is currently an ambiguity around external schema resources with no meta-schema information.  When such resources are reached from an OAS reference.
Regular JSON Schema usage does not have a standards-based overarching context such as OAS that sets a default meta-schema from outside of JSON Schema itself, although IIRC nothing in the spec prevents an enclosing spec from doing so.  But the order of precedence needs to be clear (with JSON Schema's mechanisms overriding the OAS mechanisms when both are present) .  I think it would make sense for the OAS 3.1+ default meta-schema control to apply to resources reached from OAS references, in the absence of JSON Schema's own meta-schema determination mechanisms (which can be left vague and deferred to future standardization).
  There is also the scenario where the OAS 3.1-compliant document has a default meta-schema (either set explicitly, or the default-default), an embedded schema object uses "$id" + "$schema" to change the meta-schema for that object, and then a "$ref" points to an external schema resource without any "$schema" or media type parameters.  To summarize with an example:
* the OAS 3.1 document does not override the default metaschema* the embedded schema object has something like "$schema": "https://example.com/my/custom/metaschema" (alongside an "$id" as "$schema" is ignored otherwise)* the embedded object references "$ref": "https://example.com/some/other/schema/document" which does not have a "$schema", and does not come with a media type parameter (if a media type is available at all)
Should /some/other/schema/document be interpreted according to /my/custom/metaschema or the OAS 3.1 default?  What if /some/other/schema/document is refrenced from two locations, which would imply different meta-schemas if the meta-schema of the referencing schema is assumed?  Is that an error?  Would it be better to always use the OAS 3.1-determined default to keep things consistent?
Alternative schemas:
As the topic of alternative schema options within OAS has come up from time to time, and the direction of OAS 4 is still emerging, it might be good to address how to tell whether a given schema object is a JSON Schema or not.
Media type parameters for default meta-schema or alternative schema formats?
Finally, does it make sense to mirror JSON Schema usage and allow setting any of these things with media type parameters (which would be overridden by any settings within the document or schema object).  Being able to express "OAS 3.1, but with JSON Schema 2024" might be useful, and having this general extension point to help OAS 4 flexibility might be good future-proofing.
I think those are the ambiguities present in the hand-off, but I think they can all be nailed down from the OAS side up to a clean transition to the schema specification, whatever it ends up being.
cheers,-henry

    On Friday, July 14, 2023 at 12:41:10 AM PDT, Roberto Polli <[e-mail]> wrote:  
 
 Hi Darrel,



Il ven 14 lug 2023, 04:49 Darrel Miller <[e-mail]> ha scritto:

 there are still some challenges to resolve for the JSON Schema media type.  How would you feel if we were to split the OpenAPI media type registration from the JSON Schema?  I believe the only open issue for OpenAPI is the missing security considerations.

That depends on our objectives. If we just want to register a label, I think that's ok.
If we want to ensure the interoperability of all the stack, including the relationship with JSON Schema, I think we need some more discussion.
My 2c,R


Do you think that it would be worth splitting so that we can move forward with the OpenAPI media type?
Darrel
-- 
httpapi mailing list
[e-mail]
https://www.ietf.org/mailman/listinfo/httpapi