Skip to content

docs: adds a json schema namespace #110

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
baywet wants to merge 3 commits into
base: main
Choose a base branch
from
+15 −0
Open

docs: adds a json schema namespace #110

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
d0b2901
docs: adds a json schema namespace
baywet Jul 8, 2026
addd47c
fix: update owner to OAI
baywet Jul 8, 2026
0238ac1
Update registries/_namespace/jsonschema.md
baywet Jul 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions registries/_namespace/jsonschema.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
---
owner: OAI
issue:
description: JSON Schema keywords exposed as OpenAPI Specification Extensions for versions that do not directly support them.
layout: default
Comment thread
baywet marked this conversation as resolved.
registry: ../extension/index.html
---

{% capture summary %}
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 %}
Comment on lines +10 to +13

@handrews handrews Jul 9, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 mikekistler Jul 9, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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 handrews Jul 9, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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 baywet Jul 10, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 mikekistler Jul 11, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 handrews Jul 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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 handrews Jul 13, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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 baywet Jul 13, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 handrews Jul 13, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@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 baywet Jul 13, 2026

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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


{% include namespace-entry.md summary=summary %}