From 05acf4ea14c29a5b740b76b630f5540d981e409e Mon Sep 17 00:00:00 2001 From: Agnivesh Chaubey Date: Sun, 31 Mar 2024 17:16:21 +0530 Subject: [PATCH 1/8] add description and examples for contentEncoding keyword --- .../2020-12/content/contentEncoding.markdown | 41 +++++++++++++++++++ layouts/shortcodes/instance-annotation.html | 6 +++ 2 files changed, 47 insertions(+) create mode 100644 layouts/shortcodes/instance-annotation.html diff --git a/content/2020-12/content/contentEncoding.markdown b/content/2020-12/content/contentEncoding.markdown index 0d5995d3..de9dbd2a 100644 --- a/content/2020-12/content/contentEncoding.markdown +++ b/content/2020-12/content/contentEncoding.markdown @@ -18,3 +18,44 @@ Annotations ----------- This keyword produces the content encoding name as the annotation value. + +## Explanation + +The `contentEncoding` keyword is an annotation used to specify the encoding used to store the contents of a string, particularly when it represents binary data. It indicates how the string value should be interpreted and decoded. This keyword is not directly involved in the validation process but provides metadata about the content. + +* The value of this property must be a string. +* `contentEncoding` doesn't enforce strict validation. However, it's recommended to use it correctly to ensure compatibility with applications that might interpret the encoding. +* It represents the type of binary encoding used for the string under question. Common encodings include base16, base32, and base64, as defined in [RFC 4648](https://www.rfc-editor.org/info/rfc4686). +* While the JSON Schema specification doesn't publish a predefined list of possible encodings, it's recommended to follow standard names such as those defined in [RFC 4648](https://www.rfc-editor.org/info/rfc4686). This ensures interoperability and clarity across implementations. + +## Examples + +{{}} +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "contentEncoding": "base64" +} +{{}} + +{{}} +"SGVsbG8gV29ybGQ=" // --> Hello World (base64 encoded) +{{}} + +{{}} +"eyJmb28iOi%iYmFyIn0K" +{{}} + +{{}} +[ "foo", "bar" ] +{{}} + +{{}} +{ + "valid": true, + "keywordLocation": "/", + "instanceLocation": "", + "annotations": { + "contentEncoding": "base64" + } +} +{{}} \ No newline at end of file diff --git a/layouts/shortcodes/instance-annotation.html b/layouts/shortcodes/instance-annotation.html new file mode 100644 index 00000000..4c3469fc --- /dev/null +++ b/layouts/shortcodes/instance-annotation.html @@ -0,0 +1,6 @@ +
+
+ Annotations +
+ {{ $code := trim .Inner "\n" }} {{ transform.Highlight ($code) "json" }} +
\ No newline at end of file From a8b51b650ed4e5c96f987c4546fcf44f2c3e101e Mon Sep 17 00:00:00 2001 From: Agnivesh Chaubey Date: Sun, 31 Mar 2024 17:48:30 +0530 Subject: [PATCH 2/8] add the proposed encoding formats --- content/2020-12/content/contentEncoding.markdown | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/content/2020-12/content/contentEncoding.markdown b/content/2020-12/content/contentEncoding.markdown index de9dbd2a..ff5eebce 100644 --- a/content/2020-12/content/contentEncoding.markdown +++ b/content/2020-12/content/contentEncoding.markdown @@ -19,6 +19,15 @@ Annotations This keyword produces the content encoding name as the annotation value. +## Proposed Content Encodings: + +| Encoding | Description | Reference | +|------------|-------------------------------------------------------------------------------------------------|-----------| +| `"base16"` | Encoding scheme for binary data using a 16-character hexadecimal alphabet | [RFC 4648 §8](https://datatracker.ietf.org/doc/html/rfc4648#section-8) | +| `"base32"` | Encoding scheme for binary data using a 32-character alphabet | [RFC 4648 §6](https://datatracker.ietf.org/doc/html/rfc4648#section-6) | +| `"base64"` | Common encoding scheme for representing binary data as a sequence of printable ASCII characters | [RFC 4648 §4](https://datatracker.ietf.org/doc/html/rfc4648#section-4) | + + ## Explanation The `contentEncoding` keyword is an annotation used to specify the encoding used to store the contents of a string, particularly when it represents binary data. It indicates how the string value should be interpreted and decoded. This keyword is not directly involved in the validation process but provides metadata about the content. @@ -42,7 +51,7 @@ The `contentEncoding` keyword is an annotation used to specify the encoding used {{}} {{}} -"eyJmb28iOi%iYmFyIn0K" +"This is not base64 encoded!" {{}} {{}} From c9e976a6142c3cb145479550e0d243f3115c1726 Mon Sep 17 00:00:00 2001 From: Agnivesh Chaubey Date: Sun, 31 Mar 2024 18:18:01 +0530 Subject: [PATCH 3/8] add title to schema --- content/2020-12/content/contentEncoding.markdown | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/2020-12/content/contentEncoding.markdown b/content/2020-12/content/contentEncoding.markdown index ff5eebce..9a402c71 100644 --- a/content/2020-12/content/contentEncoding.markdown +++ b/content/2020-12/content/contentEncoding.markdown @@ -39,7 +39,7 @@ The `contentEncoding` keyword is an annotation used to specify the encoding used ## Examples -{{}} +{{}} { "$schema": "https://json-schema.org/draft/2020-12/schema", "contentEncoding": "base64" From 78b368560879c4677e8f29c47c033194be7ac3a2 Mon Sep 17 00:00:00 2001 From: Agnivesh Chaubey Date: Thu, 18 Apr 2024 23:02:43 +0530 Subject: [PATCH 4/8] format the annotation output --- .../2020-12/content/contentEncoding.markdown | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/content/2020-12/content/contentEncoding.markdown b/content/2020-12/content/contentEncoding.markdown index 9a402c71..f9167e5c 100644 --- a/content/2020-12/content/contentEncoding.markdown +++ b/content/2020-12/content/contentEncoding.markdown @@ -59,12 +59,14 @@ The `contentEncoding` keyword is an annotation used to specify the encoding used {{}} {{}} -{ - "valid": true, - "keywordLocation": "/", - "instanceLocation": "", - "annotations": { - "contentEncoding": "base64" - } -} +[ + // ... + { + "valid": true, + "keywordLocation": "/contentEncoding", + "instanceLocation": "", + "annotation": "base64" + }, + // ... +] {{}} \ No newline at end of file From b410b08d998c3890c62693c3743cf7f3be4a9706 Mon Sep 17 00:00:00 2001 From: Agnivesh Chaubey Date: Thu, 18 Apr 2024 23:13:03 +0530 Subject: [PATCH 5/8] temp commit --- layouts/shortcodes/instance-annotation.html | 6 ------ 1 file changed, 6 deletions(-) delete mode 100644 layouts/shortcodes/instance-annotation.html diff --git a/layouts/shortcodes/instance-annotation.html b/layouts/shortcodes/instance-annotation.html deleted file mode 100644 index 4c3469fc..00000000 --- a/layouts/shortcodes/instance-annotation.html +++ /dev/null @@ -1,6 +0,0 @@ -
-
- Annotations -
- {{ $code := trim .Inner "\n" }} {{ transform.Highlight ($code) "json" }} -
\ No newline at end of file From 4ad4034bf107cb292f3c9a79215de3f24cfafb26 Mon Sep 17 00:00:00 2001 From: Agnivesh Chaubey Date: Mon, 22 Apr 2024 16:32:00 +0530 Subject: [PATCH 6/8] address the suggested changes --- content/2020-12/content/contentEncoding.markdown | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/content/2020-12/content/contentEncoding.markdown b/content/2020-12/content/contentEncoding.markdown index f9167e5c..b0ce5db5 100644 --- a/content/2020-12/content/contentEncoding.markdown +++ b/content/2020-12/content/contentEncoding.markdown @@ -19,13 +19,13 @@ Annotations This keyword produces the content encoding name as the annotation value. -## Proposed Content Encodings: +## Common Encodings | Encoding | Description | Reference | |------------|-------------------------------------------------------------------------------------------------|-----------| | `"base16"` | Encoding scheme for binary data using a 16-character hexadecimal alphabet | [RFC 4648 §8](https://datatracker.ietf.org/doc/html/rfc4648#section-8) | -| `"base32"` | Encoding scheme for binary data using a 32-character alphabet | [RFC 4648 §6](https://datatracker.ietf.org/doc/html/rfc4648#section-6) | -| `"base64"` | Common encoding scheme for representing binary data as a sequence of printable ASCII characters | [RFC 4648 §4](https://datatracker.ietf.org/doc/html/rfc4648#section-4) | +| `"base32"` | Encoding scheme for binary data using a 32-character hexadecimal alphabet | [RFC 4648 §6](https://datatracker.ietf.org/doc/html/rfc4648#section-6) | +| `"base64"` | Encoding scheme for binary data using a 64-character hexadecimal alphabet | [RFC 4648 §4](https://datatracker.ietf.org/doc/html/rfc4648#section-4) | ## Explanation @@ -34,7 +34,7 @@ The `contentEncoding` keyword is an annotation used to specify the encoding used * The value of this property must be a string. * `contentEncoding` doesn't enforce strict validation. However, it's recommended to use it correctly to ensure compatibility with applications that might interpret the encoding. -* It represents the type of binary encoding used for the string under question. Common encodings include base16, base32, and base64, as defined in [RFC 4648](https://www.rfc-editor.org/info/rfc4686). +* It represents the type of binary encoding used for the string under question. Some of the common encodings are listed [here](#common-encodings). * While the JSON Schema specification doesn't publish a predefined list of possible encodings, it's recommended to follow standard names such as those defined in [RFC 4648](https://www.rfc-editor.org/info/rfc4686). This ensures interoperability and clarity across implementations. ## Examples From 105ab477e4d62d1b717734dec03fd1c5f87f71d0 Mon Sep 17 00:00:00 2001 From: Agnivesh Chaubey Date: Thu, 30 May 2024 12:13:34 +0530 Subject: [PATCH 7/8] shortcode for creating keyword link --- layouts/shortcodes/keyword-link.html | 15 +++++++++++++++ 1 file changed, 15 insertions(+) create mode 100644 layouts/shortcodes/keyword-link.html diff --git a/layouts/shortcodes/keyword-link.html b/layouts/shortcodes/keyword-link.html new file mode 100644 index 00000000..2c54e5f8 --- /dev/null +++ b/layouts/shortcodes/keyword-link.html @@ -0,0 +1,15 @@ +{{- $keyword := .Get "name" -}} +{{- $keywordMap := dict -}} +{{- range $.Site.RegularPages -}} + {{- $dialect := .Section -}} + {{- $vocabulary := .Parent.Title -}} + {{- $keywordParam := .Params.keyword -}} + {{- $url := .Permalink -}} + {{- $keywordMap = $keywordMap | merge (dict $keywordParam $url) -}} +{{- end -}} +{{- $url := index $keywordMap $keyword -}} +{{- if $url -}} + {{ $keyword }} +{{- else -}} + {{ $keyword }} +{{- end -}} \ No newline at end of file From 446d7fba18d3246c90ce17aeff2bee299734838e Mon Sep 17 00:00:00 2001 From: Agnivesh Chaubey Date: Thu, 30 May 2024 12:24:15 +0530 Subject: [PATCH 8/8] add link to the keywords using shortcode --- .../2020-12/applicator/additionalProperties.markdown | 12 ++++++------ content/2020-12/applicator/allOf.markdown | 4 ++-- content/2020-12/applicator/anyOf.markdown | 12 ++++++------ content/2020-12/applicator/contains.markdown | 8 ++++---- content/2020-12/applicator/dependentSchemas.markdown | 2 +- 5 files changed, 19 insertions(+), 19 deletions(-) diff --git a/content/2020-12/applicator/additionalProperties.markdown b/content/2020-12/applicator/additionalProperties.markdown index 5c05d931..429d5179 100644 --- a/content/2020-12/applicator/additionalProperties.markdown +++ b/content/2020-12/applicator/additionalProperties.markdown @@ -41,9 +41,9 @@ related: keyword: unevaluatedProperties --- -The `additionalProperties` keyword is used to control the handling of properties whose names are not listed in the `properties` keyword or match any of the regular expressions in the `patternProperties` keyword. By default any additional properties are allowed. +The {{}} keyword is used to control the handling of properties whose names are not listed in the {{}} keyword or match any of the regular expressions in the {{}} keyword. By default any additional properties are allowed. -The behavior of this keyword depends on the presence and annotation results of `properties` and `patternProperties` within the same schema object. Validation with `additionalProperties` applies only to the child values of instance names that do not appear in the annotation results of either `properties` or `patternProperties`. +The behavior of this keyword depends on the presence and annotation results of {{}} and {{}} within the same schema object. Validation with {{}} applies only to the child values of instance names that do not appear in the annotation results of either {{}} or {{}}. ## Examples @@ -68,7 +68,7 @@ The behavior of this keyword depends on the presence and annotation results of ` {{}} { "foo": "foo", "bar": "bar" } {{}} -* _When `additionalProperties` is set to false, all the instance properties must either be present in the `properties` or match any regex within `patternProperties`; otherwise, the validaion will fail._ +* _When {{}} is set to false, all the instance properties must either be present in the {{}} or match any regex within {{}}; otherwise, the validaion will fail._ {{}} { @@ -94,7 +94,7 @@ The behavior of this keyword depends on the presence and annotation results of ` {{}} { "name": "John Doe", "age": "21" } {{}} -* _The value of `additionalProperties` can either be a boolean schema or an object schema._ +* _The value of {{}} can either be a boolean schema or an object schema._ {{}} { @@ -131,7 +131,7 @@ The behavior of this keyword depends on the presence and annotation results of ` { "keyword": "/patternProperties", "instance": "", "value": [ "Age" ] } { "keyword": "/additionalProperties", "instance": "", "value": [ "email" ] } {{}} -* _Instance properties (keys) not present in `properties` or not matching any regex within `patternProperties` are evaluated against `additionalProperties`._ +* _Instance properties (keys) not present in {{}} or not matching any regex within {{}} are evaluated against {{}}._ {{}} { @@ -175,4 +175,4 @@ The behavior of this keyword depends on the presence and annotation results of ` { "keyword": "/patternProperties", "instance": "", "value": [ "Age" ] } {{}} - _**Note:** JSON Schema is a constraint language and if you don't limit keywords like this, then more keywords than what you defined in `properties`, etc would be allowed. If you don't define a property using `properties` or `patternProperties`, but don't disallow it with `additionalProperties`, it would still be valid with any value._ + _**Note:** JSON Schema is a constraint language and if you don't limit keywords like this, then more keywords than what you defined in {{}}, etc would be allowed. If you don't define a property using {{}} or {{}}, but don't disallow it with {{}}, it would still be valid with any value._ diff --git a/content/2020-12/applicator/allOf.markdown b/content/2020-12/applicator/allOf.markdown index dce1789d..1728e13c 100644 --- a/content/2020-12/applicator/allOf.markdown +++ b/content/2020-12/applicator/allOf.markdown @@ -28,7 +28,7 @@ related: keyword: not --- -The `allOf` keyword is used to specify that a given instance must validate against all of the subschemas provided within an array. It's essentially a logical "AND" operation where all conditions must be met for validation to pass. +The {{}} keyword is used to specify that a given instance must validate against all of the subschemas provided within an array. It's essentially a logical "AND" operation where all conditions must be met for validation to pass. ## Examples @@ -129,7 +129,7 @@ The `allOf` keyword is used to specify that a given instance must validate again {{}} { "foo": "foo" } {{}} -* _Remember, if any subschema within the `allOf` keyword fails validation or has a boolean `false` value, the entire validation will always fail._ +* _Remember, if any subschema within the {{}} keyword fails validation or has a boolean `false` value, the entire validation will always fail._ {{}} { diff --git a/content/2020-12/applicator/anyOf.markdown b/content/2020-12/applicator/anyOf.markdown index bd9382df..e3d81d96 100644 --- a/content/2020-12/applicator/anyOf.markdown +++ b/content/2020-12/applicator/anyOf.markdown @@ -28,7 +28,7 @@ related: keyword: not --- -The `anyOf` keyword in JSON Schema is used to specify that an instance must validate against at least one of the schemas provided in an array. It allows you to define multiple schemas, and if the data validates against any one of them, the validation passes. +The {{}} keyword in JSON Schema is used to specify that an instance must validate against at least one of the schemas provided in an array. It allows you to define multiple schemas, and if the data validates against any one of them, the validation passes. ## Examples @@ -133,7 +133,7 @@ The `anyOf` keyword in JSON Schema is used to specify that an instance must vali {{}} { "foo": true } {{}} -* _Remember, if any subschema within the `anyOf` keyword passes validation or has a boolean `true` value, the overall result of `anyOf` is considered valid._ +* _Remember, if any subschema within the {{}} keyword passes validation or has a boolean `true` value, the overall result of {{}} is considered valid._ {{}} { @@ -160,15 +160,15 @@ The `anyOf` keyword in JSON Schema is used to specify that an instance must vali {{}} 10 {{}} -* _For the first instance above, validation passes against the first subschema within `anyOf`, thereby making the `anyOf` keyword valid, regardless of the validation result against the second subschema._ +* _For the first instance above, validation passes against the first subschema within {{}}, thereby making the {{}} keyword valid, regardless of the validation result against the second subschema._ -* _Similarly, for the second instance above, validation passes against the first subschema within `anyOf`. Even though the instance does not conform to the second subschema, validation does not proceed to validate against it, as it has already been successfully validated against the first subschema. Thus, the validation stops at that point, rendering the `anyOf` valid, despite the instance not conforming to the second subschema within the `anyOf`._ +* _Similarly, for the second instance above, validation passes against the first subschema within {{}}. Even though the instance does not conform to the second subschema, validation does not proceed to validate against it, as it has already been successfully validated against the first subschema. Thus, the validation stops at that point, rendering the {{}} valid, despite the instance not conforming to the second subschema within the {{}}._ {{}} Important note on performance and annotations: -* When running validation only, a JSON Schema implementation may stop validating `anyOf` when it encounters a successful one. However, when collecting annotations, it must evaluate all of them. -* The process of collecting annotations can impact runtime performance. For instance, if you collect annotations on a JSON Schema utilizing the `anyOf` applicator, the implementation is forced to evaluate the instance against every disjunction in the `anyOf` applicator. Conversely, if annotations are not collected, implementations may stop evaluation as soon as one `anyOf` subschema successfully validates against the instance. +* When running validation only, a JSON Schema implementation may stop validating {{}} when it encounters a successful one. However, when collecting annotations, it must evaluate all of them. +* The process of collecting annotations can impact runtime performance. For instance, if you collect annotations on a JSON Schema utilizing the {{}} applicator, the implementation is forced to evaluate the instance against every disjunction in the {{}} applicator. Conversely, if annotations are not collected, implementations may stop evaluation as soon as one {{}} subschema successfully validates against the instance. * In the interest of runtime efficiency, we recommend collecting annotations only if your specific use case demands it. {{}} diff --git a/content/2020-12/applicator/contains.markdown b/content/2020-12/applicator/contains.markdown index 1a6b169e..00b4da79 100644 --- a/content/2020-12/applicator/contains.markdown +++ b/content/2020-12/applicator/contains.markdown @@ -35,13 +35,13 @@ related: keyword: unevaluatedItems --- -The `contains` keyword is used to check if at least one element in an array instance validates against a specified sub-schema. It offers flexibility compared to `items`, which requires all elements to adhere to a single schema. +The {{}} keyword is used to check if at least one element in an array instance validates against a specified sub-schema. It offers flexibility compared to {{}}, which requires all elements to adhere to a single schema. -An array instance is valid against `contains` if at least one of its elements is valid against the given schema, except when `minContains` is present and has a value of 0, in which case an array instance must be considered valid against the `contains` keyword, even if none of its elements is valid against the given schema. +An array instance is valid against {{}} if at least one of its elements is valid against the given schema, except when {{}} is present and has a value of 0, in which case an array instance must be considered valid against the {{}} keyword, even if none of its elements is valid against the given schema. -Similarly, if `maxContains` is present alongside `contains`, the instance will be considered valid as long as the number of elements successfully validating against the `contains` subschema does not exceed the specified limit defined by `maxContains`. +Similarly, if {{}} is present alongside {{}}, the instance will be considered valid as long as the number of elements successfully validating against the {{}} subschema does not exceed the specified limit defined by {{}}. -* For data validation, `items` validates all array elements against a single schema, `prefixItems` validates a fixed-length sequence at the array's beginning, and `contains` checks for at least one element matching a schema anywhere in the array. +* For data validation, {{}} validates all array elements against a single schema, {{}} validates a fixed-length sequence at the array's beginning, and {{}} checks for at least one element matching a schema anywhere in the array. * The subschema must be applied to every array element, even after the first match has been found, to collect annotations for use by other keywords. ## Examples diff --git a/content/2020-12/applicator/dependentSchemas.markdown b/content/2020-12/applicator/dependentSchemas.markdown index fba10ce3..aec2f0f1 100644 --- a/content/2020-12/applicator/dependentSchemas.markdown +++ b/content/2020-12/applicator/dependentSchemas.markdown @@ -20,7 +20,7 @@ related: keyword: dependentRequired --- -The `dependentSchemas` keyword allows you to define dependencies between properties based on the presence of other properties within an instance. It extends the functionality of the `dependentRequired` keyword by allowing you to pass in a full schema. The instance will be considered valid only if the dependent properties adhere to the `dependentSchemas` schema. +The {{}} keyword allows you to define dependencies between properties based on the presence of other properties within an instance. It extends the functionality of the {{}} keyword by allowing you to pass in a full schema. The instance will be considered valid only if the dependent properties adhere to the {{}} schema. * Each key in the object represents a property name. * Instance is valid if the associated property is present and conforms to the subschema.