From 8906d5c1c9318a1c9057bafb5791ebceb0733e0d Mon Sep 17 00:00:00 2001 From: Christoph Kappestein Date: Thu, 24 Aug 2017 22:02:05 +0200 Subject: [PATCH 1/8] initial commit --- code-generation/Makefile | 25 + code-generation/jsonschema-code.xml | 1121 +++++++++++++++++++++++++++ 2 files changed, 1146 insertions(+) create mode 100644 code-generation/Makefile create mode 100644 code-generation/jsonschema-code.xml diff --git a/code-generation/Makefile b/code-generation/Makefile new file mode 100644 index 0000000..464e748 --- /dev/null +++ b/code-generation/Makefile @@ -0,0 +1,25 @@ +XML2RFC=xml2rfc + +OUT = \ + jsonschema-code.html jsonschema-code.txt + + +all: $(OUT) + +%.txt: %.xml + $(XML2RFC) --text $< -o $@ + +%.html: %.xml + $(XML2RFC) --html $< -o $@ + +json-schema.tar.gz: $(OUT) + mkdir json-schema + git clone . json-schema + (cd json-schema && make) + tar -czf json-schema.tar.gz --exclude '.*' json-schema + rm -rf json-schema + +clean: + rm -f $(OUT) json-schema.tar.gz + +.PHONY: clean diff --git a/code-generation/jsonschema-code.xml b/code-generation/jsonschema-code.xml new file mode 100644 index 0000000..c0b40a6 --- /dev/null +++ b/code-generation/jsonschema-code.xml @@ -0,0 +1,1121 @@ + + + + + + + +]> + + + + + + + + + + + JSON Schema Code: JSON Schema rules to simplify code generation + +
+ christoph.kappestein@gmail.com +
+ + + Internet Engineering Task Force + JSON + Schema + Code Generation + + + JSON Schema provides many ways to describe a JSON structure. The + price of this flexibility is that it is difficult for code generators + to understand a JSON Schema. This specification restricts the JSON Schema + keywords to a subset with a deterministic behaviour. + + + + +
+ + This vocabulary restricts the JSON Schema Validation keywords to a clear + subset which removes ambiguities and inherent invalid schemas. + + + If a JSON Schema follows these rules it is easier for processor and + code generators to consume. This leads to better results and + maintainability of a schema. + + + This specification should be seen as extension to the JSON Schema + draft-wright-json-schema-validation-00 specification. + + + This specification has the following goals: + + + + + To not introduce new keywords so that all existing schema + processors also work with this specification. + + + To build a JSON Schema standard which can also be used in + the OpenAPI specification where code generation is a big concern. + + + Not to build a JSON Schema to describe every possible JSON + structure. Instead to focus on the 80% use case and describe + these structures in a clean way. + + + +
+
+ + + + The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", + "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be + interpreted as described in RFC 2119. + + + + The terms "JSON", "JSON text", "JSON value", "member", "element", "object", "array", + "number", "string", "boolean", "true", "false", and "null" in this document are to + be interpreted as defined in RFC 7159. + +
+
+ + This document describes the JSON Schema restriction rules and all available + validation keywords and their corresponding behaviour. It contains + also a JSON Schema to validate whether a JSON Schema complies to these + rules. + +
+
+ + The specification distinguishes between three schema types: Definition, + Combination and Reference. + + + The distinction is made based on the used keywords. + +
+ + A definition schema is a schema which describes a concrete type. + It must follow the rules: + + + + + Every schema MUST have a "type" keyword. The type must be one of: + "object", "array", "boolean", "number", "integer" or "string" + + + Every schema of type "object" MUST have a "title" keyword. + + + Every schema of type "object" is either a struct (MUST have + a "properties" keyword) or a map (MUST have a "additionalProperties" + keyword) + + + Every schema of type "array" MUST have an "items" keyword. + The items can only contain definition ("object", "boolean", + "number", "string") or reference schemas. + + + The "patternProperties" keyword is not supported. + + + +
+
+ + A combination schema combines multiple schemas in a specific way. + It must follow the rules: + + + + + Every schema MUST have one of the following keywords: + "allOf", "anyOf" or "oneOf" + + + The value must be an array which can contain only definition + (of type "object") or reference schemas. + + + +
+
+ + A reference schema makes a reference to another schema. + It must follow the rules: + + + + + Every schema MUST have the keyword "$ref". + + + A reference schema MUST follow the same rules as a + definition schema. That means i.e. if a reference is used + inside the "allOf" keyword it MUST only reference object + types. + + + +
+
+
+ + JSON Schema validators are implemented in a way that they validate json data alongside + the data and validate this data according to the keywords which are available. So it is + possible to decide which validation keywords should be used depending on the actual data. + + + If a schema follows the rules defined in this specification it can be used independently + of the actual data. This means that it is possible to generate i.e. a class representation + of the JSON Schema only based on the schema. + + + Because of this critical design change the schema keywords must have some restrictions. + The following section describes the behaviour of each keyword. + +
+ + The following keywords can be used to describe a definition schema. + +
+ + The following keywords can be used in any definition schema. + +
+ + The value of this keyword MUST be a string. Should only + contain the characters "A-Z", "a-z" and "_" + + + Should be a distinct word which represents this schema, + may be used to generate i.e. class names or other identifiers. + + + Schemas with the same title should represent the same constraints + since a processor could merge multiple schemas and thus + remove duplicate schemas. + +
+
+ + The value of this keyword MUST be a string. + + + Contains a general description of this property. Should only + contain simple text and no line breaks since the description + is may be used in code comments or other contexts. + +
+
+ + The value of this keyword MUST be a string. + + + String values MUST be one of the six primitive types + ("boolean", "object", "array", "number", or "string"), + or "integer" which matches any number with a zero fractional part. + + + An instance validates if and only if the instance is in any of the sets listed + for this keyword. + +
+
+ + The value of this keyword MUST be boolean. + + + Allows sending a null value for the defined schema. + Default value is false. + +
+
+ + The value of this keyword MUST be boolean. + + + Specifies that a property is deprecated and SHOULD be + transitioned out of usage. Default value is false. + +
+
+
+ + If a schema has a "type" keyword which is "object" the following validation + keywords can be used. + + + An object must be either a struct or map type. A struct object contains + a set of fixed properties and a map object contains variable key value + entries. + + + Each object type MUST have also a "title" keyword. The title may be used by a + generator to determine a class name for a schema. + +
+ + The value of this keyword MUST be an array. + Elements of this array, if any, MUST be strings, and MUST be unique. + + + An object instance is valid against this keyword if every item in the array is + the name of a property in the instance. + + + Omitting this keyword has the same behavior as an empty array. + +
+
+ + A struct is an object which MUST have at least a "type", + "title" and "properties" keyword. + +
+ + + +
+
+ + The value of "properties" MUST be an object. + Each value of this object MUST be a valid JSON Schema. + + + This keyword determines how child instances validate for objects, + and does not directly validate the immediate instance itself. + + + Validation succeeds if, for each name that appears in both + the instance and as a name within this keyword's value, the child + instance for that name successfully validates against the + corresponding schema. + + + Omitting this keyword has the same behavior as an empty object. + +
+
+
+ + A map is an object which MUST have at least a "type", + "title" and "additionalProperties" keyword. + +
+ + + +
+
+ + The value of "additionalProperties" MUST be a valid JSON Schema. + + + This keyword determines how child instances validate for objects, + and does not directly validate the immediate instance itself. + + + For all such properties, validation succeeds if the child instance + validates against the "additionalProperties" schema. + + + Omitting this keyword has the same behavior as an empty schema. + +
+
+ + The value of this keyword MUST be a non-negative integer. + + + An object instance is valid against "maxProperties" if its + number of properties is less than, or equal to, the value of this + keyword. + +
+
+ + The value of this keyword MUST be a non-negative integer. + + + An object instance is valid against "minProperties" if its + number of properties is greater than, or equal to, the value of this + keyword. + + + Omitting this keyword has the same behavior as a value of 0. + +
+
+
+
+ + If a schema has a "type" keyword which is "array" the following validation + keywords can be used. + +
+ + The value of "items" MUST be an object. It MUST contain only + "object", "number", "integer" or "string" schemas. + + + This keyword determines how child instances validate for arrays, + and does not directly validate the immediate instance itself. + + + Omitting this keyword has the same behavior as an empty schema. + +
+
+ + The value of this keyword MUST be a non-negative integer. + + + An array instance is valid against "maxItems" if its size is + less than, or equal to, the value of this keyword. + +
+
+ + The value of this keyword MUST be a non-negative integer. + + + An array instance is valid against "minItems" if its size is + greater than, or equal to, the value of this keyword. + + + Omitting this keyword has the same behavior as a value of 0. + +
+
+ + The value of this keyword MUST be a boolean. + + + If this keyword has boolean value false, the instance validates + successfully. If it has boolean value true, the instance validates + successfully if all of its elements are unique. + + + Omitting this keyword has the same behavior as a value of false. + +
+
+
+ + If a schema has a "type" keyword which is either "boolean", "number" or "string" the + following validation keywords can be used. + +
+ + Primitives have an optional modifier keyword "format". There are several + known formats to define in fine detail the data type being used. + + + + int32 (signed 32 bits) + int64 (signed 64 bits) + float + double + byte (base64 encoded characters) + binary (any sequence of octets) + date (as defined by full-date RFC 3339) + date-time (as defined by date-time RFC 3339) + + + + However, to support documentation needs, the format property is an open + string-valued property, and can have any value. Formats such as "email", + "uuid", and so on, MAY be used even though undefined by this specification. + + + Types that are not accompanied by a format property follow the type definition + in the JSON Schema. Tools that do not recognize a specific format MAY default + back to the type alone, as if the format is not specified. + +
+
+ + The value of this keyword MUST be an array. This array SHOULD have at + least one element. Elements in the array SHOULD be unique. + + + An instance validates successfully against this keyword if its value is + equal to one of the elements in this keyword's array value. + + + Elements in the array must contain only string or number values. + +
+
+ + If a schema has a "type" keyword which is "boolean" no validation keywords + are available. + +
+
+ + If a schema has a "type" keyword which is either "number" or "integer" the + following validation keywords can be used. + +
+ + The value of "multipleOf" MUST be a number, strictly greater than 0. + + + A numeric instance is valid only if division by this keyword's value results in + an integer. + +
+
+ + The value of "maximum" MUST be a number, representing an inclusive upper limit + for a numeric instance. + + + If the instance is a number, then this keyword validates only if the instance is + less than or exactly equal to "maximum". + +
+
+ + The value of "exclusiveMaximum" MUST be number, representing an exclusive upper + limit for a numeric instance. + + + If the instance is a number, then the instance is valid only if it has a value + strictly less than (not equal to) "exclusiveMaximum". + +
+
+ + The value of "minimum" MUST be a number, representing an inclusive lower limit + for a numeric instance. + + + If the instance is a number, then this keyword validates only if the instance is + greater than or exactly equal to "minimum". + +
+
+ + The value of "exclusiveMinimum" MUST be number, representing an exclusive lower + limit for a numeric instance. + + + If the instance is a number, then the instance is valid only if it has a value + strictly greater than (not equal to) "exclusiveMinimum". + +
+
+
+ + If a schema has a "type" keyword which is "string" the following validation + keywords can be used. + +
+ + The value of this keyword MUST be a non-negative integer. + + A string instance is valid against this keyword if its + length is less than, or equal to, the value of this keyword. + + + The length of a string instance is defined as the number of its + characters as defined by RFC 7159. + +
+
+ + The value of this keyword MUST be a non-negative integer. + + + A string instance is valid against this keyword if its + length is greater than, or equal to, the value of this keyword. + + + + The length of a string instance is defined as the number of its + characters as defined by RFC 7159. + + + Omitting this keyword has the same behavior as a value of 0. + +
+
+ + The value of this keyword MUST be a string. This string SHOULD be a + valid regular expression, according to the ECMA 262 regular expression + dialect. + + + A string instance is considered valid if the regular + expression matches the instance successfully. Recall: regular + expressions are not implicitly anchored. + +
+
+
+
+
+ + The following keywords can be used to describe a combination schema. + +
+ + This keyword's value MUST be a non-empty array. + Each item of the array MUST be a valid object. + + + An instance validates successfully against this keyword if it validates + successfully against all schemas defined by this keyword's value. + + + The all of array should be used to express inheritance. The array + should list the most generic definition at the first position of + the array and the most specific definition at the bottom. + + + Through this code generators could implement inheritance alongside + the array. + + + Also it is possible to aggregate all schemas into a single schema. Since the + all of array can only contain schemas of type "object" it is clear that + the result is also always an schema of type "object". + +
+ + + +
+
+
+ + This keyword's value MUST be a non-empty array. + Each item of the array MUST be a valid object. + + + An instance validates successfully against this keyword if it validates + successfully against at least one schema defined by this keyword's value. + +
+
+ + This keyword's value MUST be a non-empty array. + Each item of the array MUST be a valid object. + + + An instance validates successfully against this keyword if it validates + successfully against exactly one schema defined by this keyword's value. + +
+
+ + The value of this keyword MUST be an object. + + + The keyword MUST be only used in combination with the "oneOf" keyword. + +
+
+
+ + The following keywords can be used to describe a reference schema. + +
+ + The "$ref" keyword is used to reference a schema, and provides the ability to + validate recursive structures through self-reference. + + + An object schema with a "$ref" property MUST be interpreted as a "$ref" reference. + The value of the "$ref" property MUST be a URI Reference. + Resolved against the current URI base, it identifies the URI of a schema to use. + All other properties in a "$ref" object MUST be ignored. + + + The URI is not a network locator, only an identifier. A schema need not be + downloadable from the address if it is a network-addressable URL, and + implementations SHOULD NOT assume they should perform a network operation when they + encounter a network-addressable URI. + + + A schema MUST NOT be run into an infinite loop against a schema. For example, if two + schemas "#alice" and "#bob" both have an "allOf" property that refers to the other, + a naive validator might get stuck in an infinite recursive loop trying to validate + the instance. + Schemas SHOULD NOT make use of infinite recursive nesting like this; the behavior is + undefined. + +
+
+
+
+ + The following JSON Schema can be used to validate whether a + JSON Schema follows these rules. + +
+ + + +
+
+ + + + + &RFC2119; + &RFC3339; + &RFC3986; + &RFC6901; + &RFC7159; + + + &RFC7231; + + + JSON Schema Validation: A Vocabulary for Structural Validation of JSON + + + + + + + + + + + +
+ + Thanks to the JSON Schema and OpenAPI team and contributors. + +
+
+ + This section to be removed before leaving Internet-Draft status. + + + + + + Initial creation + + + + +
+ + From d169de5b5f7a3d9d52d73feb481fb277aac129f4 Mon Sep 17 00:00:00 2001 From: Christoph Kappestein Date: Sun, 27 Aug 2017 18:14:05 +0200 Subject: [PATCH 2/8] update introduction --- code-generation/jsonschema-code.xml | 28 ++++++---------------------- 1 file changed, 6 insertions(+), 22 deletions(-) diff --git a/code-generation/jsonschema-code.xml b/code-generation/jsonschema-code.xml index c0b40a6..c3cd042 100644 --- a/code-generation/jsonschema-code.xml +++ b/code-generation/jsonschema-code.xml @@ -40,8 +40,8 @@
- This vocabulary restricts the JSON Schema Validation keywords to a clear - subset which removes ambiguities and inherent invalid schemas. + This vocabulary restricts the JSON Schema Validation keywords to + a clear subset which removes ambiguities and inherent invalid schemas. If a JSON Schema follows these rules it is easier for processor and @@ -49,28 +49,12 @@ maintainability of a schema. - This specification should be seen as extension to the JSON Schema - draft-wright-json-schema-validation-00 specification. - - - This specification has the following goals: + It includes also some new keywords from the OpenAPI v3 specification + which are dedicated to code generation. - - - To not introduce new keywords so that all existing schema - processors also work with this specification. - - - To build a JSON Schema standard which can also be used in - the OpenAPI specification where code generation is a big concern. - - - Not to build a JSON Schema to describe every possible JSON - structure. Instead to focus on the 80% use case and describe - these structures in a clean way. - - + This specification should be seen as extension to the JSON Schema + draft-wright-json-schema-validation-00 specification.
From 97c429856dcde5ed74ae9a1dba2eaa02f7ead2bd Mon Sep 17 00:00:00 2001 From: Christoph Kappestein Date: Sun, 27 Aug 2017 18:18:55 +0200 Subject: [PATCH 3/8] update name --- code-generation/jsonschema-code.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code-generation/jsonschema-code.xml b/code-generation/jsonschema-code.xml index c3cd042..ef64aaf 100644 --- a/code-generation/jsonschema-code.xml +++ b/code-generation/jsonschema-code.xml @@ -1093,7 +1093,7 @@ - + Initial creation From 72565eeec386b93b3b24d8d437d2553cb312bfa3 Mon Sep 17 00:00:00 2001 From: Christoph Kappestein Date: Mon, 28 Aug 2017 22:59:16 +0200 Subject: [PATCH 4/8] improve wording and reference schema --- code-generation/jsonschema-code.xml | 423 ++++++++-------------------- 1 file changed, 121 insertions(+), 302 deletions(-) diff --git a/code-generation/jsonschema-code.xml b/code-generation/jsonschema-code.xml index ef64aaf..fd1fc0c 100644 --- a/code-generation/jsonschema-code.xml +++ b/code-generation/jsonschema-code.xml @@ -81,13 +81,18 @@ rules.
-
+
- The specification distinguishes between three schema types: Definition, - Combination and Reference. + In the JSON Schema core specification all keywords are optional and + are applied in context with the actual data. The idea of this specification + is to build schemas which have a distinct meaning independent of + the actual data and which can be used to generate i.e. class representations. + Because of this we must restrict and require some specific keywords. - The distinction is made based on the used keywords. + In this specification every schema is exactly assigned to a specific + type of schema: Definition, Combination or Reference. The distinction + is made based on the used keywords.
@@ -101,7 +106,9 @@ "object", "array", "boolean", "number", "integer" or "string" - Every schema of type "object" MUST have a "title" keyword. + Every schema of type "object" MUST have a "title" keyword. This + is required so that code generators can build class names or other + identifiers based on this title. Every schema of type "object" is either a struct (MUST have @@ -114,7 +121,8 @@ "number", "string") or reference schemas. - The "patternProperties" keyword is not supported. + It is not possible to mix multiple constraints i.e. a schema + of type "string" can only use the keywords "minLength", etc. @@ -157,20 +165,50 @@
-
+ +
+ + The following keywords are not supported. Not supported means that + they have no special meaning in this specification and code generators + may simply ignore those keywords. + + + + + The "patternProperties" keyword is not supported. + + + The "type" keyword MUST be a string. The array notation + is not supported. + + + The "null" type is not supported + + + The "not" keyword is not supported + + + The "dependencies" keyword is not supported + + + The "additionalItems" keywords is nt supported + + + +
+ +
- JSON Schema validators are implemented in a way that they validate json data alongside - the data and validate this data according to the keywords which are available. So it is - possible to decide which validation keywords should be used depending on the actual data. + This specification restricts the usage of the validation keywords. + Which keywords are allowed depends on the schema type. - If a schema follows the rules defined in this specification it can be used independently - of the actual data. This means that it is possible to generate i.e. a class representation - of the JSON Schema only based on the schema. + The following chapter lists all available keywords and describes + the concrete behaviour. - Because of this critical design change the schema keywords must have some restrictions. - The following section describes the behaviour of each keyword. + If not otherwise noted the behaviour of a keyword is identical + to the JSON Schema validation specification.
@@ -178,7 +216,16 @@
- The following keywords can be used in any definition schema. + The following keywords can be used in any definition schema: + + + + title + description + type + nullable + deprecated +
@@ -214,10 +261,6 @@ ("boolean", "object", "array", "number", or "string"), or "integer" which matches any number with a zero fractional part. - - An instance validates if and only if the instance is in any of the sets listed - for this keyword. -
@@ -241,7 +284,16 @@
If a schema has a "type" keyword which is "object" the following validation - keywords can be used. + keywords can be used: + + + + required + properties + additionalProperties + maxProperties + minProperties + An object must be either a struct or map type. A struct object contains @@ -252,19 +304,6 @@ Each object type MUST have also a "title" keyword. The title may be used by a generator to determine a class name for a schema. -
- - The value of this keyword MUST be an array. - Elements of this array, if any, MUST be strings, and MUST be unique. - - - An object instance is valid against this keyword if every item in the array is - the name of a property in the instance. - - - Omitting this keyword has the same behavior as an empty array. - -
A struct is an object which MUST have at least a "type", @@ -288,25 +327,6 @@ ]]> -
- - The value of "properties" MUST be an object. - Each value of this object MUST be a valid JSON Schema. - - - This keyword determines how child instances validate for objects, - and does not directly validate the immediate instance itself. - - - Validation succeeds if, for each name that appears in both - the instance and as a name within this keyword's value, the child - instance for that name successfully validates against the - corresponding schema. - - - Omitting this keyword has the same behavior as an empty object. - -
@@ -326,104 +346,32 @@ ]]> -
- - The value of "additionalProperties" MUST be a valid JSON Schema. - - - This keyword determines how child instances validate for objects, - and does not directly validate the immediate instance itself. - - - For all such properties, validation succeeds if the child instance - validates against the "additionalProperties" schema. - - - Omitting this keyword has the same behavior as an empty schema. - -
-
- - The value of this keyword MUST be a non-negative integer. - - - An object instance is valid against "maxProperties" if its - number of properties is less than, or equal to, the value of this - keyword. - -
-
- - The value of this keyword MUST be a non-negative integer. - - - An object instance is valid against "minProperties" if its - number of properties is greater than, or equal to, the value of this - keyword. - - - Omitting this keyword has the same behavior as a value of 0. - -
If a schema has a "type" keyword which is "array" the following validation - keywords can be used. + keywords can be used: + + + + items + maxItems + minItems + uniqueItems + -
- - The value of "items" MUST be an object. It MUST contain only - "object", "number", "integer" or "string" schemas. - - - This keyword determines how child instances validate for arrays, - and does not directly validate the immediate instance itself. - - - Omitting this keyword has the same behavior as an empty schema. - -
-
- - The value of this keyword MUST be a non-negative integer. - - - An array instance is valid against "maxItems" if its size is - less than, or equal to, the value of this keyword. - -
-
- - The value of this keyword MUST be a non-negative integer. - - - An array instance is valid against "minItems" if its size is - greater than, or equal to, the value of this keyword. - - - Omitting this keyword has the same behavior as a value of 0. - -
-
- - The value of this keyword MUST be a boolean. - - - If this keyword has boolean value false, the instance validates - successfully. If it has boolean value true, the instance validates - successfully if all of its elements are unique. - - - Omitting this keyword has the same behavior as a value of false. - -
If a schema has a "type" keyword which is either "boolean", "number" or "string" the - following validation keywords can be used. + following validation keywords can be used: + + + + format + enum +
@@ -453,19 +401,6 @@ back to the type alone, as if the format is not specified.
-
- - The value of this keyword MUST be an array. This array SHOULD have at - least one element. Elements in the array SHOULD be unique. - - - An instance validates successfully against this keyword if its value is - equal to one of the elements in this keyword's array value. - - - Elements in the array must contain only string or number values. - -
If a schema has a "type" keyword which is "boolean" no validation keywords @@ -475,120 +410,45 @@
If a schema has a "type" keyword which is either "number" or "integer" the - following validation keywords can be used. + following validation keywords can be used: + + + + multipleOf + maximum + exclusiveMaximum + minimum + exclusiveMinimum + -
- - The value of "multipleOf" MUST be a number, strictly greater than 0. - - - A numeric instance is valid only if division by this keyword's value results in - an integer. - -
-
- - The value of "maximum" MUST be a number, representing an inclusive upper limit - for a numeric instance. - - - If the instance is a number, then this keyword validates only if the instance is - less than or exactly equal to "maximum". - -
-
- - The value of "exclusiveMaximum" MUST be number, representing an exclusive upper - limit for a numeric instance. - - - If the instance is a number, then the instance is valid only if it has a value - strictly less than (not equal to) "exclusiveMaximum". - -
-
- - The value of "minimum" MUST be a number, representing an inclusive lower limit - for a numeric instance. - - - If the instance is a number, then this keyword validates only if the instance is - greater than or exactly equal to "minimum". - -
-
- - The value of "exclusiveMinimum" MUST be number, representing an exclusive lower - limit for a numeric instance. - - - If the instance is a number, then the instance is valid only if it has a value - strictly greater than (not equal to) "exclusiveMinimum". - -
If a schema has a "type" keyword which is "string" the following validation - keywords can be used. + keywords can be used: + + + + maxLength + minLength + pattern + -
- - The value of this keyword MUST be a non-negative integer. - - A string instance is valid against this keyword if its - length is less than, or equal to, the value of this keyword. - - - The length of a string instance is defined as the number of its - characters as defined by RFC 7159. - -
-
- - The value of this keyword MUST be a non-negative integer. - - - A string instance is valid against this keyword if its - length is greater than, or equal to, the value of this keyword. - - - - The length of a string instance is defined as the number of its - characters as defined by RFC 7159. - - - Omitting this keyword has the same behavior as a value of 0. - -
-
- - The value of this keyword MUST be a string. This string SHOULD be a - valid regular expression, according to the ECMA 262 regular expression - dialect. - - - A string instance is considered valid if the regular - expression matches the instance successfully. Recall: regular - expressions are not implicitly anchored. - -
- The following keywords can be used to describe a combination schema. + The following keywords can be used to describe a combination schema: + + + + allOf + anyOf + oneOf +
- - This keyword's value MUST be a non-empty array. - Each item of the array MUST be a valid object. - - - An instance validates successfully against this keyword if it validates - successfully against all schemas defined by this keyword's value. - The all of array should be used to express inheritance. The array should list the most generic definition at the first position of @@ -623,26 +483,6 @@
-
- - This keyword's value MUST be a non-empty array. - Each item of the array MUST be a valid object. - - - An instance validates successfully against this keyword if it validates - successfully against at least one schema defined by this keyword's value. - -
-
- - This keyword's value MUST be a non-empty array. - Each item of the array MUST be a valid object. - - - An instance validates successfully against this keyword if it validates - successfully against exactly one schema defined by this keyword's value. - -
The value of this keyword MUST be an object. @@ -654,34 +494,13 @@
- The following keywords can be used to describe a reference schema. + The following keywords can be used to describe a reference schema: + + + + $ref + -
- - The "$ref" keyword is used to reference a schema, and provides the ability to - validate recursive structures through self-reference. - - - An object schema with a "$ref" property MUST be interpreted as a "$ref" reference. - The value of the "$ref" property MUST be a URI Reference. - Resolved against the current URI base, it identifies the URI of a schema to use. - All other properties in a "$ref" object MUST be ignored. - - - The URI is not a network locator, only an identifier. A schema need not be - downloadable from the address if it is a network-addressable URL, and - implementations SHOULD NOT assume they should perform a network operation when they - encounter a network-addressable URI. - - - A schema MUST NOT be run into an infinite loop against a schema. For example, if two - schemas "#alice" and "#bob" both have an "allOf" property that refers to the other, - a naive validator might get stuck in an infinite recursive loop trying to validate - the instance. - Schemas SHOULD NOT make use of infinite recursive nesting like this; the behavior is - undefined. - -
From 5fd37740ef7222e2db9906c512130f6dfb1751be Mon Sep 17 00:00:00 2001 From: Christoph Kappestein Date: Tue, 29 Aug 2017 22:27:35 +0200 Subject: [PATCH 5/8] fix typo --- code-generation/jsonschema-code.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/code-generation/jsonschema-code.xml b/code-generation/jsonschema-code.xml index fd1fc0c..08b9b82 100644 --- a/code-generation/jsonschema-code.xml +++ b/code-generation/jsonschema-code.xml @@ -191,7 +191,7 @@ The "dependencies" keyword is not supported - The "additionalItems" keywords is nt supported + The "additionalItems" keyword is not supported From 324dc563304f973efa20f6a7eee21ccad0ffb393 Mon Sep 17 00:00:00 2001 From: Christoph Kappestein Date: Sun, 3 Sep 2017 11:37:30 +0200 Subject: [PATCH 6/8] removed openapi keywords --- code-generation/jsonschema-code.xml | 34 +---------------------------- 1 file changed, 1 insertion(+), 33 deletions(-) diff --git a/code-generation/jsonschema-code.xml b/code-generation/jsonschema-code.xml index 08b9b82..aee51a7 100644 --- a/code-generation/jsonschema-code.xml +++ b/code-generation/jsonschema-code.xml @@ -44,14 +44,10 @@ a clear subset which removes ambiguities and inherent invalid schemas. - If a JSON Schema follows these rules it is easier for processor and + If a JSON Schema follows these rules it is easier for processors and code generators to consume. This leads to better results and maintainability of a schema. - - It includes also some new keywords from the OpenAPI v3 specification - which are dedicated to code generation. - This specification should be seen as extension to the JSON Schema draft-wright-json-schema-validation-00 specification. @@ -223,8 +219,6 @@ title description type - nullable - deprecated
@@ -262,24 +256,6 @@ or "integer" which matches any number with a zero fractional part.
-
- - The value of this keyword MUST be boolean. - - - Allows sending a null value for the defined schema. - Default value is false. - -
-
- - The value of this keyword MUST be boolean. - - - Specifies that a property is deprecated and SHOULD be - transitioned out of usage. Default value is false. - -
@@ -483,14 +459,6 @@
-
- - The value of this keyword MUST be an object. - - - The keyword MUST be only used in combination with the "oneOf" keyword. - -
From fce96c7256604da2f40ba86c5fafb6f7bac5e4c3 Mon Sep 17 00:00:00 2001 From: Christoph Kappestein Date: Sun, 3 Sep 2017 11:53:55 +0200 Subject: [PATCH 7/8] rephrase format keyword usage --- code-generation/jsonschema-code.xml | 19 +++++++------------ 1 file changed, 7 insertions(+), 12 deletions(-) diff --git a/code-generation/jsonschema-code.xml b/code-generation/jsonschema-code.xml index aee51a7..a5632ec 100644 --- a/code-generation/jsonschema-code.xml +++ b/code-generation/jsonschema-code.xml @@ -351,8 +351,13 @@
- Primitives have an optional modifier keyword "format". There are several - known formats to define in fine detail the data type being used. + In the context of code generation the "format" keyword gives a hint + about the concrete data type of a property. While the JSON schema + validation specification defines many formats this specification + supports only the formats which are usable in the context of code + generation. I.e. if the format is "date-time" a code generator + could utilize the standard date class of the target programming language. + A code generator should consider the following formats: @@ -366,16 +371,6 @@ date-time (as defined by date-time RFC 3339) - - However, to support documentation needs, the format property is an open - string-valued property, and can have any value. Formats such as "email", - "uuid", and so on, MAY be used even though undefined by this specification. - - - Types that are not accompanied by a format property follow the type definition - in the JSON Schema. Tools that do not recognize a specific format MAY default - back to the type alone, as if the format is not specified. -
From 578c59fd4991cb5c5eff05a81b5c829ac83796de Mon Sep 17 00:00:00 2001 From: Christoph Kappestein Date: Sun, 17 Sep 2017 22:50:07 +0200 Subject: [PATCH 8/8] clarify wording and fix punctuation --- code-generation/jsonschema-code.xml | 30 ++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/code-generation/jsonschema-code.xml b/code-generation/jsonschema-code.xml index a5632ec..f3fb540 100644 --- a/code-generation/jsonschema-code.xml +++ b/code-generation/jsonschema-code.xml @@ -82,8 +82,10 @@ In the JSON Schema core specification all keywords are optional and are applied in context with the actual data. The idea of this specification is to build schemas which have a distinct meaning independent of - the actual data and which can be used to generate i.e. class representations. - Because of this we must restrict and require some specific keywords. + the actual data and which can be used to generate different representations + i.e. model classes of a specific programming language. Because of + this we must restrict existing keywords and must make specific keywords + mandatory depending on the context. In this specification every schema is exactly assigned to a specific @@ -109,7 +111,7 @@ Every schema of type "object" is either a struct (MUST have a "properties" keyword) or a map (MUST have a "additionalProperties" - keyword) + keyword). Every schema of type "array" MUST have an "items" keyword. @@ -118,7 +120,8 @@ It is not possible to mix multiple constraints i.e. a schema - of type "string" can only use the keywords "minLength", etc. + of type "string" can only use string specific validation + keywords i.e. "minLength". @@ -132,11 +135,11 @@ Every schema MUST have one of the following keywords: - "allOf", "anyOf" or "oneOf" + "allOf", "anyOf" or "oneOf". The value must be an array which can contain only definition - (of type "object") or reference schemas. + or reference schemas. These schemas MUST be of type "object". @@ -166,7 +169,7 @@ The following keywords are not supported. Not supported means that they have no special meaning in this specification and code generators - may simply ignore those keywords. + should ignore those keywords. @@ -178,16 +181,16 @@ is not supported. - The "null" type is not supported + The "null" type is not supported. - The "not" keyword is not supported + The "not" keyword is not supported. - The "dependencies" keyword is not supported + The "dependencies" keyword is not supported. - The "additionalItems" keyword is not supported + The "additionalItems" keyword is not supported. @@ -224,7 +227,7 @@
The value of this keyword MUST be a string. Should only - contain the characters "A-Z", "a-z" and "_" + contain the characters "A-Z", "a-z" and "_". Should be a distinct word which represents this schema, @@ -243,7 +246,8 @@ Contains a general description of this property. Should only contain simple text and no line breaks since the description - is may be used in code comments or other contexts. + is may be used in code comments or other character sensitive + environments.