From d92b741b9b8ddcbb9af288827cadd3a52ddb7d5e Mon Sep 17 00:00:00 2001 From: Graham Esau Date: Sat, 7 Dec 2019 23:29:37 +0000 Subject: [PATCH] Get title/description from #[doc] on enum variants --- .../tests/expected/doc_comments_enum.json | 39 +++ .../tests/expected/doc_comments_struct.json | 35 +++ schemars/tests/expected/schema-openapi3.json | 222 ++++++++++++++++-- schemars/tests/expected/schema.json | 108 ++++++++- schemars_derive/src/lib.rs | 15 +- 5 files changed, 394 insertions(+), 25 deletions(-) create mode 100644 schemars/tests/expected/doc_comments_enum.json create mode 100644 schemars/tests/expected/doc_comments_struct.json diff --git a/schemars/tests/expected/doc_comments_enum.json b/schemars/tests/expected/doc_comments_enum.json new file mode 100644 index 0000000..559ffa6 --- /dev/null +++ b/schemars/tests/expected/doc_comments_enum.json @@ -0,0 +1,39 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "This is the enum's title", + "description": "This is the enum's description.", + "anyOf": [ + { + "enum": [ + "UndocumentedUnit", + "DocumentedUnit" + ] + }, + { + "title": "Complex variant", + "description": "This is a struct-like variant.", + "type": "object", + "required": [ + "Complex" + ], + "properties": { + "Complex": { + "type": "object", + "required": [ + "my_nullable_string" + ], + "properties": { + "my_nullable_string": { + "title": "A nullable string", + "description": "This field is a nullable string.\n\nThis is the second line!\n\nAnd this is the third!", + "type": [ + "string", + "null" + ] + } + } + } + } + } + ] +} \ No newline at end of file diff --git a/schemars/tests/expected/doc_comments_struct.json b/schemars/tests/expected/doc_comments_struct.json new file mode 100644 index 0000000..9f1b4bf --- /dev/null +++ b/schemars/tests/expected/doc_comments_struct.json @@ -0,0 +1,35 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "title": "This is the struct's title", + "description": "This is the struct's description.", + "type": "object", + "required": [ + "my_int", + "my_undocumented_bool", + "my_unit" + ], + "properties": { + "my_int": { + "title": "An integer", + "type": "integer", + "format": "int32" + }, + "my_undocumented_bool": { + "type": "boolean" + }, + "my_unit": { + "description": "A unit struct instance", + "allOf": [ + { + "$ref": "#/definitions/MyUnitStruct" + } + ] + } + }, + "definitions": { + "MyUnitStruct": { + "title": "A Unit", + "type": "null" + } + } +} \ No newline at end of file diff --git a/schemars/tests/expected/schema-openapi3.json b/schemars/tests/expected/schema-openapi3.json index 2746c84..b04b607 100644 --- a/schemars/tests/expected/schema-openapi3.json +++ b/schemars/tests/expected/schema-openapi3.json @@ -1,43 +1,62 @@ { "$schema": "https://spec.openapis.org/oas/3.0/schema/2019-04-02#/definitions/Schema", "title": "RootSchema", + "description": "The root object of a JSON Schema document.", "type": "object", "properties": { "$id": { + "description": "The `$id` keyword.\n\nSee [JSON Schema 8.2.2. The \"$id\" Keyword](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-8.2.2).", "type": "string", "nullable": true }, "$ref": { + "description": "The `$ref` keyword.\n\nSee [JSON Schema 8.2.4.1. Direct References with \"$ref\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-8.2.4.1).", "type": "string", "nullable": true }, "$schema": { + "description": "The `$schema` keyword.\n\nSee [JSON Schema 8.1.1. The \"$schema\" Keyword](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-8.1.1).", "type": "string", "nullable": true }, "additionalItems": { + "description": "The `additionalItems` keyword.\n\nSee [JSON Schema 9.3.1.2. \"additionalItems\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.1.2).", "anyOf": [ { + "description": "A trivial boolean JSON Schema.\n\nThe schema `true` matches everything (always passes validation), whereas the schema `false` matches nothing (always fails validation).", "type": "boolean" }, { - "$ref": "#/components/schemas/SchemaObject" + "description": "A JSON Schema object.", + "allOf": [ + { + "$ref": "#/components/schemas/SchemaObject" + } + ] } ], "nullable": true }, "additionalProperties": { + "description": "The `additionalProperties` keyword.\n\nSee [JSON Schema 9.3.2.3. \"additionalProperties\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.2.3).", "anyOf": [ { + "description": "A trivial boolean JSON Schema.\n\nThe schema `true` matches everything (always passes validation), whereas the schema `false` matches nothing (always fails validation).", "type": "boolean" }, { - "$ref": "#/components/schemas/SchemaObject" + "description": "A JSON Schema object.", + "allOf": [ + { + "$ref": "#/components/schemas/SchemaObject" + } + ] } ], "nullable": true }, "allOf": { + "description": "The `allOf` keyword.\n\nSee [JSON Schema 9.2.1.1. \"allOf\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.1.1).", "type": "array", "items": { "$ref": "#/components/schemas/Schema" @@ -45,6 +64,7 @@ "nullable": true }, "anyOf": { + "description": "The `anyOf` keyword.\n\nSee [JSON Schema 9.2.1.2. \"anyOf\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.1.2).", "type": "array", "items": { "$ref": "#/components/schemas/Schema" @@ -52,77 +72,108 @@ "nullable": true }, "const": { + "description": "The `const` keyword.\n\nSee [JSON Schema Validation 6.1.3. \"const\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.1.3)", "nullable": true }, "contains": { + "description": "The `contains` keyword.\n\nSee [JSON Schema 9.3.1.4. \"contains\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.1.4).", "anyOf": [ { + "description": "A trivial boolean JSON Schema.\n\nThe schema `true` matches everything (always passes validation), whereas the schema `false` matches nothing (always fails validation).", "type": "boolean" }, { - "$ref": "#/components/schemas/SchemaObject" + "description": "A JSON Schema object.", + "allOf": [ + { + "$ref": "#/components/schemas/SchemaObject" + } + ] } ], "nullable": true }, "default": { + "description": "The `default` keyword.\n\nSee [JSON Schema Validation 9.2. \"default\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.2).", "nullable": true }, "definitions": { + "description": "The `$defs` keyword.\n\nThis is currently serialized as `definitions` for backwards compatibility.\n\nSee [JSON Schema 8.2.5. Schema Re-Use With \"$defs\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-8.2.5).", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Schema" } }, "deprecated": { + "description": "The `deprecated` keyword.\n\nSee [JSON Schema Validation 9.3. \"deprecated\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.3).", "type": "boolean" }, "description": { + "description": "The `description` keyword.\n\nSee [JSON Schema Validation 9.1. \"title\" and \"description\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.1).", "type": "string", "nullable": true }, "else": { + "description": "The `else` keyword.\n\nSee [JSON Schema 9.2.2.3. \"else\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.2.3).", "anyOf": [ { + "description": "A trivial boolean JSON Schema.\n\nThe schema `true` matches everything (always passes validation), whereas the schema `false` matches nothing (always fails validation).", "type": "boolean" }, { - "$ref": "#/components/schemas/SchemaObject" + "description": "A JSON Schema object.", + "allOf": [ + { + "$ref": "#/components/schemas/SchemaObject" + } + ] } ], "nullable": true }, "enum": { + "description": "The `enum` keyword.\n\nSee [JSON Schema Validation 6.1.2. \"enum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.1.2)", "type": "array", "items": {}, "nullable": true }, "exclusiveMaximum": { + "description": "The `exclusiveMaximum` keyword.\n\nSee [JSON Schema Validation 6.2.3. \"exclusiveMaximum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.3).", "type": "number", "format": "double", "nullable": true }, "exclusiveMinimum": { + "description": "The `exclusiveMinimum` keyword.\n\nSee [JSON Schema Validation 6.2.5. \"exclusiveMinimum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.5).", "type": "number", "format": "double", "nullable": true }, "format": { + "description": "The `format` keyword.\n\nSee [JSON Schema Validation 7. A Vocabulary for Semantic Content With \"format\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-7).", "type": "string", "nullable": true }, "if": { + "description": "The `if` keyword.\n\nSee [JSON Schema 9.2.2.1. \"if\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.2.1).", "anyOf": [ { + "description": "A trivial boolean JSON Schema.\n\nThe schema `true` matches everything (always passes validation), whereas the schema `false` matches nothing (always fails validation).", "type": "boolean" }, { - "$ref": "#/components/schemas/SchemaObject" + "description": "A JSON Schema object.", + "allOf": [ + { + "$ref": "#/components/schemas/SchemaObject" + } + ] } ], "nullable": true }, "items": { + "description": "The `items` keyword.\n\nSee [JSON Schema 9.3.1.1. \"items\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.1.1).", "anyOf": [ { "$ref": "#/components/schemas/Schema" @@ -137,68 +188,85 @@ "nullable": true }, "maxItems": { + "description": "The `maxItems` keyword.\n\nSee [JSON Schema Validation 6.4.1. \"maxItems\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.4.1).", "type": "integer", "format": "uint32", "minimum": 0.0, "nullable": true }, "maxLength": { + "description": "The `maxLength` keyword.\n\nSee [JSON Schema Validation 6.3.1. \"maxLength\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.3.1).", "type": "integer", "format": "uint32", "minimum": 0.0, "nullable": true }, "maxProperties": { + "description": "The `maxProperties` keyword.\n\nSee [JSON Schema Validation 6.5.1. \"maxProperties\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.5.1).", "type": "integer", "format": "uint32", "minimum": 0.0, "nullable": true }, "maximum": { + "description": "The `maximum` keyword.\n\nSee [JSON Schema Validation 6.2.2. \"maximum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.2).", "type": "number", "format": "double", "nullable": true }, "minItems": { + "description": "The `minItems` keyword.\n\nSee [JSON Schema Validation 6.4.2. \"minItems\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.4.2).", "type": "integer", "format": "uint32", "minimum": 0.0, "nullable": true }, "minLength": { + "description": "The `minLength` keyword.\n\nSee [JSON Schema Validation 6.3.2. \"minLength\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.3.2).", "type": "integer", "format": "uint32", "minimum": 0.0, "nullable": true }, "minProperties": { + "description": "The `minProperties` keyword.\n\nSee [JSON Schema Validation 6.5.2. \"minProperties\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.5.2).", "type": "integer", "format": "uint32", "minimum": 0.0, "nullable": true }, "minimum": { + "description": "The `minimum` keyword.\n\nSee [JSON Schema Validation 6.2.4. \"minimum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.4).", "type": "number", "format": "double", "nullable": true }, "multipleOf": { + "description": "The `multipleOf` keyword.\n\nSee [JSON Schema Validation 6.2.1. \"multipleOf\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.1).", "type": "number", "format": "double", "nullable": true }, "not": { + "description": "The `not` keyword.\n\nSee [JSON Schema 9.2.1.4. \"not\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.1.4).", "anyOf": [ { + "description": "A trivial boolean JSON Schema.\n\nThe schema `true` matches everything (always passes validation), whereas the schema `false` matches nothing (always fails validation).", "type": "boolean" }, { - "$ref": "#/components/schemas/SchemaObject" + "description": "A JSON Schema object.", + "allOf": [ + { + "$ref": "#/components/schemas/SchemaObject" + } + ] } ], "nullable": true }, "oneOf": { + "description": "The `oneOf` keyword.\n\nSee [JSON Schema 9.2.1.3. \"oneOf\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.1.3).", "type": "array", "items": { "$ref": "#/components/schemas/Schema" @@ -206,57 +274,78 @@ "nullable": true }, "pattern": { + "description": "The `pattern` keyword.\n\nSee [JSON Schema Validation 6.3.3. \"pattern\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.3.3).", "type": "string", "nullable": true }, "patternProperties": { + "description": "The `patternProperties` keyword.\n\nSee [JSON Schema 9.3.2.2. \"patternProperties\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.2.2).", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Schema" } }, "properties": { + "description": "The `properties` keyword.\n\nSee [JSON Schema 9.3.2.1. \"properties\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.2.1).", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Schema" } }, "propertyNames": { + "description": "The `propertyNames` keyword.\n\nSee [JSON Schema 9.3.2.5. \"propertyNames\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.2.5).", "anyOf": [ { + "description": "A trivial boolean JSON Schema.\n\nThe schema `true` matches everything (always passes validation), whereas the schema `false` matches nothing (always fails validation).", "type": "boolean" }, { - "$ref": "#/components/schemas/SchemaObject" + "description": "A JSON Schema object.", + "allOf": [ + { + "$ref": "#/components/schemas/SchemaObject" + } + ] } ], "nullable": true }, "readOnly": { + "description": "The `readOnly` keyword.\n\nSee [JSON Schema Validation 9.4. \"readOnly\" and \"writeOnly\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.4).", "type": "boolean" }, "required": { + "description": "The `required` keyword.\n\nSee [JSON Schema Validation 6.5.3. \"required\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.5.3).", "type": "array", "items": { "type": "string" } }, "then": { + "description": "The `then` keyword.\n\nSee [JSON Schema 9.2.2.2. \"then\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.2.2).", "anyOf": [ { + "description": "A trivial boolean JSON Schema.\n\nThe schema `true` matches everything (always passes validation), whereas the schema `false` matches nothing (always fails validation).", "type": "boolean" }, { - "$ref": "#/components/schemas/SchemaObject" + "description": "A JSON Schema object.", + "allOf": [ + { + "$ref": "#/components/schemas/SchemaObject" + } + ] } ], "nullable": true }, "title": { + "description": "The `title` keyword.\n\nSee [JSON Schema Validation 9.1. \"title\" and \"description\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.1).", "type": "string", "nullable": true }, "type": { + "description": "The `type` keyword.\n\nSee [JSON Schema Validation 6.1.1. \"type\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.1.1) and [JSON Schema 4.2.1. Instance Data Model](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-4.2.1).", "anyOf": [ { "$ref": "#/components/schemas/InstanceType" @@ -271,16 +360,19 @@ "nullable": true }, "uniqueItems": { + "description": "The `uniqueItems` keyword.\n\nSee [JSON Schema Validation 6.4.3. \"uniqueItems\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.4.3).", "type": "boolean", "nullable": true }, "writeOnly": { + "description": "The `writeOnly` keyword.\n\nSee [JSON Schema Validation 9.4. \"readOnly\" and \"writeOnly\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.4).", "type": "boolean" } }, "additionalProperties": true, "definitions": { "InstanceType": { + "description": "The possible types of values in JSON Schema documents.\n\nSee [JSON Schema 4.2.1. Instance Data Model](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-4.2.1).", "enum": [ "null", "boolean", @@ -292,49 +384,74 @@ ] }, "Schema": { + "description": "A JSON Schema.", "anyOf": [ { + "description": "A trivial boolean JSON Schema.\n\nThe schema `true` matches everything (always passes validation), whereas the schema `false` matches nothing (always fails validation).", "type": "boolean" }, { - "$ref": "#/components/schemas/SchemaObject" + "description": "A JSON Schema object.", + "allOf": [ + { + "$ref": "#/components/schemas/SchemaObject" + } + ] } ] }, "SchemaObject": { + "description": "A JSON Schema object.", "type": "object", "properties": { "$id": { + "description": "The `$id` keyword.\n\nSee [JSON Schema 8.2.2. The \"$id\" Keyword](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-8.2.2).", "type": "string", "nullable": true }, "$ref": { + "description": "The `$ref` keyword.\n\nSee [JSON Schema 8.2.4.1. Direct References with \"$ref\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-8.2.4.1).", "type": "string", "nullable": true }, "additionalItems": { + "description": "The `additionalItems` keyword.\n\nSee [JSON Schema 9.3.1.2. \"additionalItems\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.1.2).", "anyOf": [ { + "description": "A trivial boolean JSON Schema.\n\nThe schema `true` matches everything (always passes validation), whereas the schema `false` matches nothing (always fails validation).", "type": "boolean" }, { - "$ref": "#/components/schemas/SchemaObject" + "description": "A JSON Schema object.", + "allOf": [ + { + "$ref": "#/components/schemas/SchemaObject" + } + ] } ], "nullable": true }, "additionalProperties": { + "description": "The `additionalProperties` keyword.\n\nSee [JSON Schema 9.3.2.3. \"additionalProperties\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.2.3).", "anyOf": [ { + "description": "A trivial boolean JSON Schema.\n\nThe schema `true` matches everything (always passes validation), whereas the schema `false` matches nothing (always fails validation).", "type": "boolean" }, { - "$ref": "#/components/schemas/SchemaObject" + "description": "A JSON Schema object.", + "allOf": [ + { + "$ref": "#/components/schemas/SchemaObject" + } + ] } ], "nullable": true }, "allOf": { + "description": "The `allOf` keyword.\n\nSee [JSON Schema 9.2.1.1. \"allOf\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.1.1).", "type": "array", "items": { "$ref": "#/components/schemas/Schema" @@ -342,6 +459,7 @@ "nullable": true }, "anyOf": { + "description": "The `anyOf` keyword.\n\nSee [JSON Schema 9.2.1.2. \"anyOf\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.1.2).", "type": "array", "items": { "$ref": "#/components/schemas/Schema" @@ -349,71 +467,101 @@ "nullable": true }, "const": { + "description": "The `const` keyword.\n\nSee [JSON Schema Validation 6.1.3. \"const\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.1.3)", "nullable": true }, "contains": { + "description": "The `contains` keyword.\n\nSee [JSON Schema 9.3.1.4. \"contains\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.1.4).", "anyOf": [ { + "description": "A trivial boolean JSON Schema.\n\nThe schema `true` matches everything (always passes validation), whereas the schema `false` matches nothing (always fails validation).", "type": "boolean" }, { - "$ref": "#/components/schemas/SchemaObject" + "description": "A JSON Schema object.", + "allOf": [ + { + "$ref": "#/components/schemas/SchemaObject" + } + ] } ], "nullable": true }, "default": { + "description": "The `default` keyword.\n\nSee [JSON Schema Validation 9.2. \"default\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.2).", "nullable": true }, "deprecated": { + "description": "The `deprecated` keyword.\n\nSee [JSON Schema Validation 9.3. \"deprecated\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.3).", "type": "boolean" }, "description": { + "description": "The `description` keyword.\n\nSee [JSON Schema Validation 9.1. \"title\" and \"description\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.1).", "type": "string", "nullable": true }, "else": { + "description": "The `else` keyword.\n\nSee [JSON Schema 9.2.2.3. \"else\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.2.3).", "anyOf": [ { + "description": "A trivial boolean JSON Schema.\n\nThe schema `true` matches everything (always passes validation), whereas the schema `false` matches nothing (always fails validation).", "type": "boolean" }, { - "$ref": "#/components/schemas/SchemaObject" + "description": "A JSON Schema object.", + "allOf": [ + { + "$ref": "#/components/schemas/SchemaObject" + } + ] } ], "nullable": true }, "enum": { + "description": "The `enum` keyword.\n\nSee [JSON Schema Validation 6.1.2. \"enum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.1.2)", "type": "array", "items": {}, "nullable": true }, "exclusiveMaximum": { + "description": "The `exclusiveMaximum` keyword.\n\nSee [JSON Schema Validation 6.2.3. \"exclusiveMaximum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.3).", "type": "number", "format": "double", "nullable": true }, "exclusiveMinimum": { + "description": "The `exclusiveMinimum` keyword.\n\nSee [JSON Schema Validation 6.2.5. \"exclusiveMinimum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.5).", "type": "number", "format": "double", "nullable": true }, "format": { + "description": "The `format` keyword.\n\nSee [JSON Schema Validation 7. A Vocabulary for Semantic Content With \"format\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-7).", "type": "string", "nullable": true }, "if": { + "description": "The `if` keyword.\n\nSee [JSON Schema 9.2.2.1. \"if\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.2.1).", "anyOf": [ { + "description": "A trivial boolean JSON Schema.\n\nThe schema `true` matches everything (always passes validation), whereas the schema `false` matches nothing (always fails validation).", "type": "boolean" }, { - "$ref": "#/components/schemas/SchemaObject" + "description": "A JSON Schema object.", + "allOf": [ + { + "$ref": "#/components/schemas/SchemaObject" + } + ] } ], "nullable": true }, "items": { + "description": "The `items` keyword.\n\nSee [JSON Schema 9.3.1.1. \"items\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.1.1).", "anyOf": [ { "$ref": "#/components/schemas/Schema" @@ -428,68 +576,85 @@ "nullable": true }, "maxItems": { + "description": "The `maxItems` keyword.\n\nSee [JSON Schema Validation 6.4.1. \"maxItems\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.4.1).", "type": "integer", "format": "uint32", "minimum": 0.0, "nullable": true }, "maxLength": { + "description": "The `maxLength` keyword.\n\nSee [JSON Schema Validation 6.3.1. \"maxLength\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.3.1).", "type": "integer", "format": "uint32", "minimum": 0.0, "nullable": true }, "maxProperties": { + "description": "The `maxProperties` keyword.\n\nSee [JSON Schema Validation 6.5.1. \"maxProperties\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.5.1).", "type": "integer", "format": "uint32", "minimum": 0.0, "nullable": true }, "maximum": { + "description": "The `maximum` keyword.\n\nSee [JSON Schema Validation 6.2.2. \"maximum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.2).", "type": "number", "format": "double", "nullable": true }, "minItems": { + "description": "The `minItems` keyword.\n\nSee [JSON Schema Validation 6.4.2. \"minItems\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.4.2).", "type": "integer", "format": "uint32", "minimum": 0.0, "nullable": true }, "minLength": { + "description": "The `minLength` keyword.\n\nSee [JSON Schema Validation 6.3.2. \"minLength\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.3.2).", "type": "integer", "format": "uint32", "minimum": 0.0, "nullable": true }, "minProperties": { + "description": "The `minProperties` keyword.\n\nSee [JSON Schema Validation 6.5.2. \"minProperties\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.5.2).", "type": "integer", "format": "uint32", "minimum": 0.0, "nullable": true }, "minimum": { + "description": "The `minimum` keyword.\n\nSee [JSON Schema Validation 6.2.4. \"minimum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.4).", "type": "number", "format": "double", "nullable": true }, "multipleOf": { + "description": "The `multipleOf` keyword.\n\nSee [JSON Schema Validation 6.2.1. \"multipleOf\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.1).", "type": "number", "format": "double", "nullable": true }, "not": { + "description": "The `not` keyword.\n\nSee [JSON Schema 9.2.1.4. \"not\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.1.4).", "anyOf": [ { + "description": "A trivial boolean JSON Schema.\n\nThe schema `true` matches everything (always passes validation), whereas the schema `false` matches nothing (always fails validation).", "type": "boolean" }, { - "$ref": "#/components/schemas/SchemaObject" + "description": "A JSON Schema object.", + "allOf": [ + { + "$ref": "#/components/schemas/SchemaObject" + } + ] } ], "nullable": true }, "oneOf": { + "description": "The `oneOf` keyword.\n\nSee [JSON Schema 9.2.1.3. \"oneOf\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.1.3).", "type": "array", "items": { "$ref": "#/components/schemas/Schema" @@ -497,57 +662,78 @@ "nullable": true }, "pattern": { + "description": "The `pattern` keyword.\n\nSee [JSON Schema Validation 6.3.3. \"pattern\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.3.3).", "type": "string", "nullable": true }, "patternProperties": { + "description": "The `patternProperties` keyword.\n\nSee [JSON Schema 9.3.2.2. \"patternProperties\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.2.2).", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Schema" } }, "properties": { + "description": "The `properties` keyword.\n\nSee [JSON Schema 9.3.2.1. \"properties\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.2.1).", "type": "object", "additionalProperties": { "$ref": "#/components/schemas/Schema" } }, "propertyNames": { + "description": "The `propertyNames` keyword.\n\nSee [JSON Schema 9.3.2.5. \"propertyNames\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.2.5).", "anyOf": [ { + "description": "A trivial boolean JSON Schema.\n\nThe schema `true` matches everything (always passes validation), whereas the schema `false` matches nothing (always fails validation).", "type": "boolean" }, { - "$ref": "#/components/schemas/SchemaObject" + "description": "A JSON Schema object.", + "allOf": [ + { + "$ref": "#/components/schemas/SchemaObject" + } + ] } ], "nullable": true }, "readOnly": { + "description": "The `readOnly` keyword.\n\nSee [JSON Schema Validation 9.4. \"readOnly\" and \"writeOnly\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.4).", "type": "boolean" }, "required": { + "description": "The `required` keyword.\n\nSee [JSON Schema Validation 6.5.3. \"required\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.5.3).", "type": "array", "items": { "type": "string" } }, "then": { + "description": "The `then` keyword.\n\nSee [JSON Schema 9.2.2.2. \"then\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.2.2).", "anyOf": [ { + "description": "A trivial boolean JSON Schema.\n\nThe schema `true` matches everything (always passes validation), whereas the schema `false` matches nothing (always fails validation).", "type": "boolean" }, { - "$ref": "#/components/schemas/SchemaObject" + "description": "A JSON Schema object.", + "allOf": [ + { + "$ref": "#/components/schemas/SchemaObject" + } + ] } ], "nullable": true }, "title": { + "description": "The `title` keyword.\n\nSee [JSON Schema Validation 9.1. \"title\" and \"description\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.1).", "type": "string", "nullable": true }, "type": { + "description": "The `type` keyword.\n\nSee [JSON Schema Validation 6.1.1. \"type\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.1.1) and [JSON Schema 4.2.1. Instance Data Model](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-4.2.1).", "anyOf": [ { "$ref": "#/components/schemas/InstanceType" @@ -562,10 +748,12 @@ "nullable": true }, "uniqueItems": { + "description": "The `uniqueItems` keyword.\n\nSee [JSON Schema Validation 6.4.3. \"uniqueItems\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.4.3).", "type": "boolean", "nullable": true }, "writeOnly": { + "description": "The `writeOnly` keyword.\n\nSee [JSON Schema Validation 9.4. \"readOnly\" and \"writeOnly\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.4).", "type": "boolean" } }, diff --git a/schemars/tests/expected/schema.json b/schemars/tests/expected/schema.json index 9ba6963..4982d5a 100644 --- a/schemars/tests/expected/schema.json +++ b/schemars/tests/expected/schema.json @@ -1,27 +1,32 @@ { "$schema": "http://json-schema.org/draft-07/schema#", "title": "RootSchema", + "description": "The root object of a JSON Schema document.", "type": "object", "properties": { "$id": { + "description": "The `$id` keyword.\n\nSee [JSON Schema 8.2.2. The \"$id\" Keyword](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-8.2.2).", "type": [ "string", "null" ] }, "$ref": { + "description": "The `$ref` keyword.\n\nSee [JSON Schema 8.2.4.1. Direct References with \"$ref\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-8.2.4.1).", "type": [ "string", "null" ] }, "$schema": { + "description": "The `$schema` keyword.\n\nSee [JSON Schema 8.1.1. The \"$schema\" Keyword](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-8.1.1).", "type": [ "string", "null" ] }, "additionalItems": { + "description": "The `additionalItems` keyword.\n\nSee [JSON Schema 9.3.1.2. \"additionalItems\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.1.2).", "anyOf": [ { "$ref": "#/definitions/Schema" @@ -32,6 +37,7 @@ ] }, "additionalProperties": { + "description": "The `additionalProperties` keyword.\n\nSee [JSON Schema 9.3.2.3. \"additionalProperties\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.2.3).", "anyOf": [ { "$ref": "#/definitions/Schema" @@ -42,6 +48,7 @@ ] }, "allOf": { + "description": "The `allOf` keyword.\n\nSee [JSON Schema 9.2.1.1. \"allOf\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.1.1).", "type": [ "array", "null" @@ -51,6 +58,7 @@ } }, "anyOf": { + "description": "The `anyOf` keyword.\n\nSee [JSON Schema 9.2.1.2. \"anyOf\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.1.2).", "type": [ "array", "null" @@ -59,8 +67,11 @@ "$ref": "#/definitions/Schema" } }, - "const": true, + "const": { + "description": "The `const` keyword.\n\nSee [JSON Schema Validation 6.1.3. \"const\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.1.3)" + }, "contains": { + "description": "The `contains` keyword.\n\nSee [JSON Schema 9.3.1.4. \"contains\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.1.4).", "anyOf": [ { "$ref": "#/definitions/Schema" @@ -70,23 +81,29 @@ } ] }, - "default": true, + "default": { + "description": "The `default` keyword.\n\nSee [JSON Schema Validation 9.2. \"default\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.2)." + }, "definitions": { + "description": "The `$defs` keyword.\n\nThis is currently serialized as `definitions` for backwards compatibility.\n\nSee [JSON Schema 8.2.5. Schema Re-Use With \"$defs\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-8.2.5).", "type": "object", "additionalProperties": { "$ref": "#/definitions/Schema" } }, "deprecated": { + "description": "The `deprecated` keyword.\n\nSee [JSON Schema Validation 9.3. \"deprecated\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.3).", "type": "boolean" }, "description": { + "description": "The `description` keyword.\n\nSee [JSON Schema Validation 9.1. \"title\" and \"description\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.1).", "type": [ "string", "null" ] }, "else": { + "description": "The `else` keyword.\n\nSee [JSON Schema 9.2.2.3. \"else\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.2.3).", "anyOf": [ { "$ref": "#/definitions/Schema" @@ -97,6 +114,7 @@ ] }, "enum": { + "description": "The `enum` keyword.\n\nSee [JSON Schema Validation 6.1.2. \"enum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.1.2)", "type": [ "array", "null" @@ -104,6 +122,7 @@ "items": true }, "exclusiveMaximum": { + "description": "The `exclusiveMaximum` keyword.\n\nSee [JSON Schema Validation 6.2.3. \"exclusiveMaximum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.3).", "type": [ "number", "null" @@ -111,6 +130,7 @@ "format": "double" }, "exclusiveMinimum": { + "description": "The `exclusiveMinimum` keyword.\n\nSee [JSON Schema Validation 6.2.5. \"exclusiveMinimum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.5).", "type": [ "number", "null" @@ -118,12 +138,14 @@ "format": "double" }, "format": { + "description": "The `format` keyword.\n\nSee [JSON Schema Validation 7. A Vocabulary for Semantic Content With \"format\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-7).", "type": [ "string", "null" ] }, "if": { + "description": "The `if` keyword.\n\nSee [JSON Schema 9.2.2.1. \"if\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.2.1).", "anyOf": [ { "$ref": "#/definitions/Schema" @@ -134,6 +156,7 @@ ] }, "items": { + "description": "The `items` keyword.\n\nSee [JSON Schema 9.3.1.1. \"items\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.1.1).", "anyOf": [ { "$ref": "#/definitions/SingleOrVec_for_Schema" @@ -144,6 +167,7 @@ ] }, "maxItems": { + "description": "The `maxItems` keyword.\n\nSee [JSON Schema Validation 6.4.1. \"maxItems\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.4.1).", "type": [ "integer", "null" @@ -152,6 +176,7 @@ "minimum": 0.0 }, "maxLength": { + "description": "The `maxLength` keyword.\n\nSee [JSON Schema Validation 6.3.1. \"maxLength\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.3.1).", "type": [ "integer", "null" @@ -160,6 +185,7 @@ "minimum": 0.0 }, "maxProperties": { + "description": "The `maxProperties` keyword.\n\nSee [JSON Schema Validation 6.5.1. \"maxProperties\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.5.1).", "type": [ "integer", "null" @@ -168,6 +194,7 @@ "minimum": 0.0 }, "maximum": { + "description": "The `maximum` keyword.\n\nSee [JSON Schema Validation 6.2.2. \"maximum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.2).", "type": [ "number", "null" @@ -175,6 +202,7 @@ "format": "double" }, "minItems": { + "description": "The `minItems` keyword.\n\nSee [JSON Schema Validation 6.4.2. \"minItems\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.4.2).", "type": [ "integer", "null" @@ -183,6 +211,7 @@ "minimum": 0.0 }, "minLength": { + "description": "The `minLength` keyword.\n\nSee [JSON Schema Validation 6.3.2. \"minLength\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.3.2).", "type": [ "integer", "null" @@ -191,6 +220,7 @@ "minimum": 0.0 }, "minProperties": { + "description": "The `minProperties` keyword.\n\nSee [JSON Schema Validation 6.5.2. \"minProperties\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.5.2).", "type": [ "integer", "null" @@ -199,6 +229,7 @@ "minimum": 0.0 }, "minimum": { + "description": "The `minimum` keyword.\n\nSee [JSON Schema Validation 6.2.4. \"minimum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.4).", "type": [ "number", "null" @@ -206,6 +237,7 @@ "format": "double" }, "multipleOf": { + "description": "The `multipleOf` keyword.\n\nSee [JSON Schema Validation 6.2.1. \"multipleOf\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.1).", "type": [ "number", "null" @@ -213,6 +245,7 @@ "format": "double" }, "not": { + "description": "The `not` keyword.\n\nSee [JSON Schema 9.2.1.4. \"not\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.1.4).", "anyOf": [ { "$ref": "#/definitions/Schema" @@ -223,6 +256,7 @@ ] }, "oneOf": { + "description": "The `oneOf` keyword.\n\nSee [JSON Schema 9.2.1.3. \"oneOf\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.1.3).", "type": [ "array", "null" @@ -232,24 +266,28 @@ } }, "pattern": { + "description": "The `pattern` keyword.\n\nSee [JSON Schema Validation 6.3.3. \"pattern\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.3.3).", "type": [ "string", "null" ] }, "patternProperties": { + "description": "The `patternProperties` keyword.\n\nSee [JSON Schema 9.3.2.2. \"patternProperties\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.2.2).", "type": "object", "additionalProperties": { "$ref": "#/definitions/Schema" } }, "properties": { + "description": "The `properties` keyword.\n\nSee [JSON Schema 9.3.2.1. \"properties\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.2.1).", "type": "object", "additionalProperties": { "$ref": "#/definitions/Schema" } }, "propertyNames": { + "description": "The `propertyNames` keyword.\n\nSee [JSON Schema 9.3.2.5. \"propertyNames\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.2.5).", "anyOf": [ { "$ref": "#/definitions/Schema" @@ -260,15 +298,18 @@ ] }, "readOnly": { + "description": "The `readOnly` keyword.\n\nSee [JSON Schema Validation 9.4. \"readOnly\" and \"writeOnly\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.4).", "type": "boolean" }, "required": { + "description": "The `required` keyword.\n\nSee [JSON Schema Validation 6.5.3. \"required\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.5.3).", "type": "array", "items": { "type": "string" } }, "then": { + "description": "The `then` keyword.\n\nSee [JSON Schema 9.2.2.2. \"then\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.2.2).", "anyOf": [ { "$ref": "#/definitions/Schema" @@ -279,12 +320,14 @@ ] }, "title": { + "description": "The `title` keyword.\n\nSee [JSON Schema Validation 9.1. \"title\" and \"description\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.1).", "type": [ "string", "null" ] }, "type": { + "description": "The `type` keyword.\n\nSee [JSON Schema Validation 6.1.1. \"type\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.1.1) and [JSON Schema 4.2.1. Instance Data Model](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-4.2.1).", "anyOf": [ { "$ref": "#/definitions/SingleOrVec_for_InstanceType" @@ -295,18 +338,21 @@ ] }, "uniqueItems": { + "description": "The `uniqueItems` keyword.\n\nSee [JSON Schema Validation 6.4.3. \"uniqueItems\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.4.3).", "type": [ "boolean", "null" ] }, "writeOnly": { + "description": "The `writeOnly` keyword.\n\nSee [JSON Schema Validation 9.4. \"readOnly\" and \"writeOnly\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.4).", "type": "boolean" } }, "additionalProperties": true, "definitions": { "InstanceType": { + "description": "The possible types of values in JSON Schema documents.\n\nSee [JSON Schema 4.2.1. Instance Data Model](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-4.2.1).", "enum": [ "null", "boolean", @@ -318,31 +364,42 @@ ] }, "Schema": { + "description": "A JSON Schema.", "anyOf": [ { + "description": "A trivial boolean JSON Schema.\n\nThe schema `true` matches everything (always passes validation), whereas the schema `false` matches nothing (always fails validation).", "type": "boolean" }, { - "$ref": "#/definitions/SchemaObject" + "description": "A JSON Schema object.", + "allOf": [ + { + "$ref": "#/definitions/SchemaObject" + } + ] } ] }, "SchemaObject": { + "description": "A JSON Schema object.", "type": "object", "properties": { "$id": { + "description": "The `$id` keyword.\n\nSee [JSON Schema 8.2.2. The \"$id\" Keyword](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-8.2.2).", "type": [ "string", "null" ] }, "$ref": { + "description": "The `$ref` keyword.\n\nSee [JSON Schema 8.2.4.1. Direct References with \"$ref\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-8.2.4.1).", "type": [ "string", "null" ] }, "additionalItems": { + "description": "The `additionalItems` keyword.\n\nSee [JSON Schema 9.3.1.2. \"additionalItems\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.1.2).", "anyOf": [ { "$ref": "#/definitions/Schema" @@ -353,6 +410,7 @@ ] }, "additionalProperties": { + "description": "The `additionalProperties` keyword.\n\nSee [JSON Schema 9.3.2.3. \"additionalProperties\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.2.3).", "anyOf": [ { "$ref": "#/definitions/Schema" @@ -363,6 +421,7 @@ ] }, "allOf": { + "description": "The `allOf` keyword.\n\nSee [JSON Schema 9.2.1.1. \"allOf\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.1.1).", "type": [ "array", "null" @@ -372,6 +431,7 @@ } }, "anyOf": { + "description": "The `anyOf` keyword.\n\nSee [JSON Schema 9.2.1.2. \"anyOf\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.1.2).", "type": [ "array", "null" @@ -380,8 +440,11 @@ "$ref": "#/definitions/Schema" } }, - "const": true, + "const": { + "description": "The `const` keyword.\n\nSee [JSON Schema Validation 6.1.3. \"const\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.1.3)" + }, "contains": { + "description": "The `contains` keyword.\n\nSee [JSON Schema 9.3.1.4. \"contains\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.1.4).", "anyOf": [ { "$ref": "#/definitions/Schema" @@ -391,17 +454,22 @@ } ] }, - "default": true, + "default": { + "description": "The `default` keyword.\n\nSee [JSON Schema Validation 9.2. \"default\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.2)." + }, "deprecated": { + "description": "The `deprecated` keyword.\n\nSee [JSON Schema Validation 9.3. \"deprecated\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.3).", "type": "boolean" }, "description": { + "description": "The `description` keyword.\n\nSee [JSON Schema Validation 9.1. \"title\" and \"description\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.1).", "type": [ "string", "null" ] }, "else": { + "description": "The `else` keyword.\n\nSee [JSON Schema 9.2.2.3. \"else\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.2.3).", "anyOf": [ { "$ref": "#/definitions/Schema" @@ -412,6 +480,7 @@ ] }, "enum": { + "description": "The `enum` keyword.\n\nSee [JSON Schema Validation 6.1.2. \"enum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.1.2)", "type": [ "array", "null" @@ -419,6 +488,7 @@ "items": true }, "exclusiveMaximum": { + "description": "The `exclusiveMaximum` keyword.\n\nSee [JSON Schema Validation 6.2.3. \"exclusiveMaximum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.3).", "type": [ "number", "null" @@ -426,6 +496,7 @@ "format": "double" }, "exclusiveMinimum": { + "description": "The `exclusiveMinimum` keyword.\n\nSee [JSON Schema Validation 6.2.5. \"exclusiveMinimum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.5).", "type": [ "number", "null" @@ -433,12 +504,14 @@ "format": "double" }, "format": { + "description": "The `format` keyword.\n\nSee [JSON Schema Validation 7. A Vocabulary for Semantic Content With \"format\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-7).", "type": [ "string", "null" ] }, "if": { + "description": "The `if` keyword.\n\nSee [JSON Schema 9.2.2.1. \"if\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.2.1).", "anyOf": [ { "$ref": "#/definitions/Schema" @@ -449,6 +522,7 @@ ] }, "items": { + "description": "The `items` keyword.\n\nSee [JSON Schema 9.3.1.1. \"items\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.1.1).", "anyOf": [ { "$ref": "#/definitions/SingleOrVec_for_Schema" @@ -459,6 +533,7 @@ ] }, "maxItems": { + "description": "The `maxItems` keyword.\n\nSee [JSON Schema Validation 6.4.1. \"maxItems\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.4.1).", "type": [ "integer", "null" @@ -467,6 +542,7 @@ "minimum": 0.0 }, "maxLength": { + "description": "The `maxLength` keyword.\n\nSee [JSON Schema Validation 6.3.1. \"maxLength\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.3.1).", "type": [ "integer", "null" @@ -475,6 +551,7 @@ "minimum": 0.0 }, "maxProperties": { + "description": "The `maxProperties` keyword.\n\nSee [JSON Schema Validation 6.5.1. \"maxProperties\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.5.1).", "type": [ "integer", "null" @@ -483,6 +560,7 @@ "minimum": 0.0 }, "maximum": { + "description": "The `maximum` keyword.\n\nSee [JSON Schema Validation 6.2.2. \"maximum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.2).", "type": [ "number", "null" @@ -490,6 +568,7 @@ "format": "double" }, "minItems": { + "description": "The `minItems` keyword.\n\nSee [JSON Schema Validation 6.4.2. \"minItems\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.4.2).", "type": [ "integer", "null" @@ -498,6 +577,7 @@ "minimum": 0.0 }, "minLength": { + "description": "The `minLength` keyword.\n\nSee [JSON Schema Validation 6.3.2. \"minLength\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.3.2).", "type": [ "integer", "null" @@ -506,6 +586,7 @@ "minimum": 0.0 }, "minProperties": { + "description": "The `minProperties` keyword.\n\nSee [JSON Schema Validation 6.5.2. \"minProperties\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.5.2).", "type": [ "integer", "null" @@ -514,6 +595,7 @@ "minimum": 0.0 }, "minimum": { + "description": "The `minimum` keyword.\n\nSee [JSON Schema Validation 6.2.4. \"minimum\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.4).", "type": [ "number", "null" @@ -521,6 +603,7 @@ "format": "double" }, "multipleOf": { + "description": "The `multipleOf` keyword.\n\nSee [JSON Schema Validation 6.2.1. \"multipleOf\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.2.1).", "type": [ "number", "null" @@ -528,6 +611,7 @@ "format": "double" }, "not": { + "description": "The `not` keyword.\n\nSee [JSON Schema 9.2.1.4. \"not\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.1.4).", "anyOf": [ { "$ref": "#/definitions/Schema" @@ -538,6 +622,7 @@ ] }, "oneOf": { + "description": "The `oneOf` keyword.\n\nSee [JSON Schema 9.2.1.3. \"oneOf\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.1.3).", "type": [ "array", "null" @@ -547,24 +632,28 @@ } }, "pattern": { + "description": "The `pattern` keyword.\n\nSee [JSON Schema Validation 6.3.3. \"pattern\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.3.3).", "type": [ "string", "null" ] }, "patternProperties": { + "description": "The `patternProperties` keyword.\n\nSee [JSON Schema 9.3.2.2. \"patternProperties\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.2.2).", "type": "object", "additionalProperties": { "$ref": "#/definitions/Schema" } }, "properties": { + "description": "The `properties` keyword.\n\nSee [JSON Schema 9.3.2.1. \"properties\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.2.1).", "type": "object", "additionalProperties": { "$ref": "#/definitions/Schema" } }, "propertyNames": { + "description": "The `propertyNames` keyword.\n\nSee [JSON Schema 9.3.2.5. \"propertyNames\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.3.2.5).", "anyOf": [ { "$ref": "#/definitions/Schema" @@ -575,15 +664,18 @@ ] }, "readOnly": { + "description": "The `readOnly` keyword.\n\nSee [JSON Schema Validation 9.4. \"readOnly\" and \"writeOnly\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.4).", "type": "boolean" }, "required": { + "description": "The `required` keyword.\n\nSee [JSON Schema Validation 6.5.3. \"required\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.5.3).", "type": "array", "items": { "type": "string" } }, "then": { + "description": "The `then` keyword.\n\nSee [JSON Schema 9.2.2.2. \"then\"](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-9.2.2.2).", "anyOf": [ { "$ref": "#/definitions/Schema" @@ -594,12 +686,14 @@ ] }, "title": { + "description": "The `title` keyword.\n\nSee [JSON Schema Validation 9.1. \"title\" and \"description\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.1).", "type": [ "string", "null" ] }, "type": { + "description": "The `type` keyword.\n\nSee [JSON Schema Validation 6.1.1. \"type\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.1.1) and [JSON Schema 4.2.1. Instance Data Model](https://tools.ietf.org/html/draft-handrews-json-schema-02#section-4.2.1).", "anyOf": [ { "$ref": "#/definitions/SingleOrVec_for_InstanceType" @@ -610,18 +704,21 @@ ] }, "uniqueItems": { + "description": "The `uniqueItems` keyword.\n\nSee [JSON Schema Validation 6.4.3. \"uniqueItems\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-6.4.3).", "type": [ "boolean", "null" ] }, "writeOnly": { + "description": "The `writeOnly` keyword.\n\nSee [JSON Schema Validation 9.4. \"readOnly\" and \"writeOnly\"](https://tools.ietf.org/html/draft-handrews-json-schema-validation-02#section-9.4).", "type": "boolean" } }, "additionalProperties": true }, "SingleOrVec_for_InstanceType": { + "description": "A type which can be serialized as a single item, or multiple items.\n\nIn some contexts, a `Single` may be semantically distinct from a `Vec` containing only item.", "anyOf": [ { "$ref": "#/definitions/InstanceType" @@ -635,6 +732,7 @@ ] }, "SingleOrVec_for_Schema": { + "description": "A type which can be serialized as a single item, or multiple items.\n\nIn some contexts, a `Single` may be semantically distinct from a `Vec` containing only item.", "anyOf": [ { "$ref": "#/definitions/Schema" diff --git a/schemars_derive/src/lib.rs b/schemars_derive/src/lib.rs index 901a974..8d886b9 100644 --- a/schemars_derive/src/lib.rs +++ b/schemars_derive/src/lib.rs @@ -143,7 +143,7 @@ fn schema_for_external_tagged_enum<'a>( schemas.extend(complex_variants.into_iter().map(|variant| { let name = variant.attrs.name().deserialize_name(); let sub_schema = schema_for_untagged_enum_variant(variant, cattrs); - wrap_schema_fields(quote! { + let schema_expr = wrap_schema_fields(quote! { instance_type: Some(schemars::schema::InstanceType::Object.into()), object: Some(Box::new(schemars::schema::ObjectValidation { properties: { @@ -158,7 +158,8 @@ fn schema_for_external_tagged_enum<'a>( }, ..Default::default() })), - }) + }); + metadata::set_metadata_on_schema_from_docs(schema_expr, &variant.original.attrs) })); wrap_schema_fields(quote! { @@ -180,6 +181,7 @@ fn schema_for_internal_tagged_enum<'a>( instance_type: Some(schemars::schema::InstanceType::String.into()), enum_values: Some(vec![#name.into()]), }); + let tag_schema = wrap_schema_fields(quote! { instance_type: Some(schemars::schema::InstanceType::Object.into()), object: Some(Box::new(schemars::schema::ObjectValidation { @@ -196,6 +198,8 @@ fn schema_for_internal_tagged_enum<'a>( ..Default::default() })), }); + let tag_schema = metadata::set_metadata_on_schema_from_docs(tag_schema, &variant.original.attrs); + let variant_schema = match variant.style { Style::Unit => return tag_schema, Style::Newtype => { @@ -225,7 +229,10 @@ fn schema_for_untagged_enum<'a>( variants: impl Iterator>, cattrs: &attr::Container, ) -> TokenStream { - let schemas = variants.map(|v| schema_for_untagged_enum_variant(v, cattrs)); + let schemas = variants.map(|variant| { + let schema_expr = schema_for_untagged_enum_variant(variant, cattrs); + metadata::set_metadata_on_schema_from_docs(schema_expr, &variant.original.attrs) + }); wrap_schema_fields(quote! { subschemas: Some(Box::new(schemars::schema::SubschemaValidation { @@ -251,6 +258,7 @@ fn schema_for_unit_struct() -> TokenStream { } fn schema_for_newtype_struct(field: &Field) -> TokenStream { + // TODO metadata from docs? let ty = get_json_schema_type(field); quote_spanned! {field.original.span()=> gen.subschema_for::<#ty>() @@ -258,6 +266,7 @@ fn schema_for_newtype_struct(field: &Field) -> TokenStream { } fn schema_for_tuple_struct(fields: &[Field]) -> TokenStream { + // TODO metadata from docs? let types = fields .iter() .filter(|f| !f.attrs.skip_deserializing())