You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Currently, we have the following schema document $ids for OAS 3.1 (shown relative to a base URI of https://https://spec.openapis.org/oas/3.1/, and without the trailing date segment that all schemas need to support updates:
schema # Validates everything except the Schema Object, which is only validated against type: [boolean, object]
schema-base # Extends schema to validate Schema Objects against dialect/baseand require both $schema and jsonSchemaDialect to be set to schema's $id if they are present
dialect/base # A dialect equivalent to the default 2020-12 dialect plus the OAS extensions
meta/base # The vocabulary metaschema for the OAS extensions
schema-base was named to indicate that it incorporates dialect/base. No one is certain why the dialect and vocabulary are referred to as "base", but they are called that in the OAS text as well. I vaguely recall discussing the dialect as a base for further OAS-relevant extensions? Perhaps that is what the intent was.
AFAICT, the advantage of schema is that it's self-contained. But giving it that name means that it is the schema that most people assume is what they want, yet it really does not produce the behavior they'd expect.
schema-base is closer to what people would expect, but is (in my view) overly restrictive in locking $schema to dialect/base, as it is valid to switch metaschemas if $schema appears alongside $id, and conforming JSON Schema implementations know to treat $id-containing subschemas as embedded resources and check for a changed metaschema. However, this does not make schema-base wrong: Users might indeed want to enforce using onlydialect/base, and this is the correct way to do that.
On the other hand (and contrary to some of my comments earlier on Slack), schema-base locking jsonSchemaDialect to dialect/base is probably correct. If you want to set jsonSchemaDialect to something else, you would want a schema that validates Scheam Objects accordingly by default.
We probably shouldn't change how schema behaves, but we should make it more obvious that it is incomplete. We should also come up with some sort of intuitive name for a schema that is like schema-base but does not restrict $schema. This name needs to convey that most users will want this new schema, and not the plainschema.
Ideally, I'd prefer to make copies of the vocabulary and dialect and give them the URIs dialect/oas and meta/oas (3.1 is already present earlier in the URI), but that is probably more trouble than it is worth given that I imagine very few people pay attention to those other than to just load them correctly when using schema-base.
The important thing is to have an intuitively-named schema that performs the default accepted Schema Object validation but still allows switching metaschemas on embedded resources. That is the default behavior of the OAS, and it's not currently provided.
The text was updated successfully, but these errors were encountered:
Currently, we have the following schema document
$id
s for OAS 3.1 (shown relative to a base URI ofhttps://https://spec.openapis.org/oas/3.1/
, and without the trailing date segment that all schemas need to support updates:schema
# Validates everything except the Schema Object, which is only validated againsttype: [boolean, object]
schema-base
# Extendsschema
to validate Schema Objects againstdialect/base
and require both$schema
andjsonSchemaDialect
to be set toschema
's$id
if they are presentdialect/base
# A dialect equivalent to the default 2020-12 dialect plus the OAS extensionsmeta/base
# The vocabulary metaschema for the OAS extensionsschema-base
was named to indicate that it incorporatesdialect/base
. No one is certain why the dialect and vocabulary are referred to as "base", but they are called that in the OAS text as well. I vaguely recall discussing the dialect as a base for further OAS-relevant extensions? Perhaps that is what the intent was.AFAICT, the advantage of
schema
is that it's self-contained. But giving it that name means that it is the schema that most people assume is what they want, yet it really does not produce the behavior they'd expect.schema-base
is closer to what people would expect, but is (in my view) overly restrictive in locking$schema
todialect/base
, as it is valid to switch metaschemas if$schema
appears alongside$id
, and conforming JSON Schema implementations know to treat$id
-containing subschemas as embedded resources and check for a changed metaschema. However, this does not makeschema-base
wrong: Users might indeed want to enforce using onlydialect/base
, and this is the correct way to do that.On the other hand (and contrary to some of my comments earlier on Slack),
schema-base
lockingjsonSchemaDialect
todialect/base
is probably correct. If you want to setjsonSchemaDialect
to something else, you would want a schema that validates Scheam Objects accordingly by default.We probably shouldn't change how
schema
behaves, but we should make it more obvious that it is incomplete. We should also come up with some sort of intuitive name for a schema that is likeschema-base
but does not restrict$schema
. This name needs to convey that most users will want this new schema, and not the plainschema
.Ideally, I'd prefer to make copies of the vocabulary and dialect and give them the URIs
dialect/oas
andmeta/oas
(3.1
is already present earlier in the URI), but that is probably more trouble than it is worth given that I imagine very few people pay attention to those other than to just load them correctly when usingschema-base
.The important thing is to have an intuitively-named schema that performs the default accepted Schema Object validation but still allows switching metaschemas on embedded resources. That is the default behavior of the OAS, and it's not currently provided.
The text was updated successfully, but these errors were encountered: