docs: adds a json schema namespace

[baywet]

follow up to #85, #86, #88, #87, #84, #89, #97, #96, #95, #94, #93, #92, #91, #90

[handrews]

Can we make a note that, strictly speaking, x- prefixes are only required in 3.0 or earlier? For 3.1+, OAD authors should check their tool documentation to find out whether they support x- schema keywords or some other mechanism for accessing keywords from later drafts (which, IIRC, some JSON Schema implementations do, at least for some keywords).

[mikekistler]

@handrews are you suggesting that we also reserve the jsonschema namespace (with no "x-")? I suppose we could do that, but I think that would mean that extensions in that namespace could only be used in OpenAPI 3.1 or later, and I don't think any of the extensions currently proposed or approved fall in to this category.

[handrews]

@mikekistler no, I mean tht some JSON Schema implementations will just allow, say, propertyNames with draft-04 even though it wasn't introduced until later.

Although come to think of it, this wouldn't be a problem in 3.1+ unless you had already set jsonSchemaDialect to something like draft-04, and if you wanted to use later keywords you wouldn't do that, so... yeah, never mind.

I see some extension entries say something like "used when targeting OpenAPI versions prior to 3.2", so I think this whole namespace should have "used when targeting OpenAPI versions prior to 3.1" on it, and that would be sufficient. Ignore all the rest of what I said.

[baywet]

Suggested change

	The `x-{{page.slug}}-` prefix is reserved for OpenAPI Specification Extensions that mirror JSON Schema keywords when targeting OpenAPI versions or JSON Schema dialects where those keywords are not directly available.
	Extensions in this namespace are registered in the [OpenAPI Extension Registry](../extension/), like the `x-oai-` and `x-oas-` namespaces.
	{% endcapture %}
	The `x-{{page.slug}}-` prefix is reserved for OpenAPI Specification Extensions that mirror JSON Schema keywords when targeting OpenAPI versions prior to 3.1 or JSON Schema dialects where those keywords are not directly available.
	Extensions in this namespace are registered in the [OpenAPI Extension Registry](../extension/), like the `x-oai-` and `x-oas-` namespaces.
	{% endcapture %}

does that work?

[mikekistler]

I see some extension entries say something like "used when targeting OpenAPI versions prior to 3.2",

I'd like to propose this way of expressing this:

in OpenAPI descriptions where the keyword is not directly available in the associated JSON Schema dialect

Suggested change

	The `x-{{page.slug}}-` prefix is reserved for OpenAPI Specification Extensions that mirror JSON Schema keywords when targeting OpenAPI versions or JSON Schema dialects where those keywords are not directly available.
	Extensions in this namespace are registered in the [OpenAPI Extension Registry](../extension/), like the `x-oai-` and `x-oas-` namespaces.
	{% endcapture %}
	The `x-{{page.slug}}-` prefix is reserved for OpenAPI Specification Extensions that mirror JSON Schema keywords in OpenAPI descriptions where the keyword is not directly available in the associated JSON Schema dialect.
	Extensions in this namespace are registered in the [OpenAPI Extension Registry](../extension/), like the `x-oai-` and `x-oas-` namespaces.
	{% endcapture %}

[handrews]

@baywet Are there tools that require or benefit from the x- approach in OAS 3.1+? I'm trying to get this out of hand-waving and hypotheticals and into what is actually, verifiably needed.

Additionally, from looking at a description, it makes it easier to tell "this is a property that's fully supported in the current version of OpenAPI"

All JSON Schema keywords/properties are supported in OAS 3.1. Anything you can possibly do with JSON Schema is supported in OAS 3.1 (although tool support matters more than theoretical support- again, point me to tools that support one thing and not the other and I'll be very interested in that).

[handrews]

@baywet @mikekistler to try to make this a little more focused, IIRC @lornajane noted that she'd seen OAS 3.1 documents using jsonSchemaDialect: https://json-schema.org/draft-07/schema with early 3.1 adopters who had access to draft-07 tooling but not 2020-12 tooling as that was not mature yet. So that's a concrete example where, in theory, someone could have wanted a JSON Schema keyword that was in draft 2020-12 but they were generally using draft-07 with OAS 3.1.

So the question is: If such a user wanted to selective "import" 2020-12 keywords from the future, how did they do it, and what tools supported it? That is the question we need to answer.

I am against fracturing the JSON Schema ecosystem with x- prefixes that are alien to it unless there is a clear, concrete, implementation-driven need for such a thing. The whole point of the 3.1 Schema Object was to completely delegate it to JSON Schema. So it should act like JSON Schema.

[baywet]

To be clear, I started all of that for 3.0, not 3.1+

I'm also struggling to see why would anybody downgrade their schema version in 3.1 and need the extensions

[handrews]

@baywet

To be clear, I started all of that for 3.0, not 3.1+

Yes. No one is disputing this for 3.0. But the language around "JSON Schema dialects" can only ever apply to 3.1+, which is why I'm pushing on it.

I'm also struggling to see why would anybody downgrade their schema version in 3.1 and need the extensions.

Exactly! This is my entire point! So why should we confuse people with language about "JSON Schema dialects" in either this namespace registration or the individual extensions. Just say it's for 3.0 and leave it at that!

[baywet]

@handrews would this edit work for you?#110 (comment)

@mkistler are you ok with letting go of the dialect scenario?

[mikekistler]

Looks good. 👍