From ceadbe1b4eea41d5e4560f7526da188e34c2ea8e Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sat, 20 Apr 2024 12:06:35 -0700 Subject: [PATCH 1/4] Be more clear about `format` support Most 2020-12 validators do not validate it, which is a regular point of confusion worth highlighting. --- versions/3.1.1.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index e4423df5b2..847f1bcaf3 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -146,7 +146,8 @@ Data types in the OAS are based on the types supported by the [JSON Schema Speci Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. Models are defined using the [Schema Object](#schemaObject), which is a superset of JSON Schema Specification Draft 2020-12. -As defined by the [JSON Schema Validation vocabulary](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00#section-7.3), data types can have an optional modifier property: `format`. +As defined by the [JSON Schema Validation specification](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00#section-7.3), data types can have an optional modifier property: `format`. Note that by default, JSON Schema draft 2020-12 validators _do not_ validate `format`, but instead treat it as an annotation. Support for `format` validation, either in best-effort form with the default `format-annotation` vocabulary, or with the less-commonly-implemented `format-assertion` vocabulary, varies among JSON Schema implementations. + OAS defines additional formats to provide fine detail for primitive data types. The formats defined by the OAS are: From 0f800d5ae20ae701d194ed9272dcc43edddcb74a Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Mon, 22 Apr 2024 08:13:33 -0700 Subject: [PATCH 2/4] Link format vocabularies to JSON Schema spec sections --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 847f1bcaf3..590020e9d5 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -146,7 +146,7 @@ Data types in the OAS are based on the types supported by the [JSON Schema Speci Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. Models are defined using the [Schema Object](#schemaObject), which is a superset of JSON Schema Specification Draft 2020-12. -As defined by the [JSON Schema Validation specification](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00#section-7.3), data types can have an optional modifier property: `format`. Note that by default, JSON Schema draft 2020-12 validators _do not_ validate `format`, but instead treat it as an annotation. Support for `format` validation, either in best-effort form with the default `format-annotation` vocabulary, or with the less-commonly-implemented `format-assertion` vocabulary, varies among JSON Schema implementations. +As defined by the [JSON Schema Validation specification](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00#section-7.3), data types can have an optional modifier property: `format`. Note that by default, JSON Schema draft 2020-12 validators _do not_ validate `format`, but instead treat it as an annotation. Support for `format` validation, either in best-effort form with the [default `format-annotation` vocabulary](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-7.2.1), or with the less-commonly-implemented [`format-assertion` vocabulary](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-7.2.2), varies among JSON Schema implementations. OAS defines additional formats to provide fine detail for primitive data types. From 25d82a181ba38f7059d0bb7c32eadae79da0784e Mon Sep 17 00:00:00 2001 From: Henry Andrews Date: Tue, 23 Apr 2024 07:27:04 -0700 Subject: [PATCH 3/4] wording improvements from review Co-authored-by: Mike Kistler --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 590020e9d5..9bd1d9734b 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -146,7 +146,7 @@ Data types in the OAS are based on the types supported by the [JSON Schema Speci Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. Models are defined using the [Schema Object](#schemaObject), which is a superset of JSON Schema Specification Draft 2020-12. -As defined by the [JSON Schema Validation specification](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00#section-7.3), data types can have an optional modifier property: `format`. Note that by default, JSON Schema draft 2020-12 validators _do not_ validate `format`, but instead treat it as an annotation. Support for `format` validation, either in best-effort form with the [default `format-annotation` vocabulary](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-7.2.1), or with the less-commonly-implemented [`format-assertion` vocabulary](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-7.2.2), varies among JSON Schema implementations. +As defined by the [JSON Schema Validation specification](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00#section-7.3), data types can have an optional modifier property: `format`. Note that by default, JSON Schema draft 2020-12 validators _do not_ validate `format`, but instead treat it as an annotation. Support for `format` validation, either in best-effort form with the [default `format-annotation` vocabulary](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-7.2.1), or with the less-commonly-implemented [`format-assertion` vocabulary](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-7.2.2), varies among JSON Schema validator implementations. OAS defines additional formats to provide fine detail for primitive data types. From c48dd1ae226019011198a5bd30db42305e98c7f1 Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Wed, 24 Apr 2024 09:49:40 -0700 Subject: [PATCH 4/4] More minimal wording regarding "format" validation. --- versions/3.1.1.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/versions/3.1.1.md b/versions/3.1.1.md index 9bd1d9734b..b65276cf7e 100644 --- a/versions/3.1.1.md +++ b/versions/3.1.1.md @@ -146,7 +146,7 @@ Data types in the OAS are based on the types supported by the [JSON Schema Speci Note that `integer` as a type is also supported and is defined as a JSON number without a fraction or exponent part. Models are defined using the [Schema Object](#schemaObject), which is a superset of JSON Schema Specification Draft 2020-12. -As defined by the [JSON Schema Validation specification](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00#section-7.3), data types can have an optional modifier property: `format`. Note that by default, JSON Schema draft 2020-12 validators _do not_ validate `format`, but instead treat it as an annotation. Support for `format` validation, either in best-effort form with the [default `format-annotation` vocabulary](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-7.2.1), or with the less-commonly-implemented [`format-assertion` vocabulary](https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#section-7.2.2), varies among JSON Schema validator implementations. +As defined by the [JSON Schema Validation specification](https://tools.ietf.org/html/draft-bhutton-json-schema-validation-00#section-7.3), data types can have an optional modifier property: `format`. As described in that specification, `format` is treated as a non-validating annotation by default; the ability to validate `format` varies across implementations. OAS defines additional formats to provide fine detail for primitive data types.