feat: add object descriptions and examples

definitions/3.0.0/APIKeyHTTPSecurityScheme.json

@@ -8,30 +8,37 @@
   "properties": {
     "type": {
       "type": "string",
+      "description": "The type of the security scheme.",
       "enum": [
         "httpApiKey"
       ]
     },
     "name": {
-      "type": "string"
+      "type": "string",
+      "description": "The name of the header, query or cookie parameter to be used."
     },
     "in": {
       "type": "string",
+      "description": "The location of the API key",
       "enum": [
         "header",
         "query",
         "cookie"
       ]
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme. CommonMark syntax MAY be used for rich text representation."
     }
   },
   "patternProperties": {
     "^x-[\\w\\d\\.\\x2d_]+$": {
       "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
     }
   },
+  "example": {
+		"$ref": "http://asyncapi.com/examples/3.0.0/APIKeyHTTPSecurityScheme.json"
+	},
   "additionalProperties": false,
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/3.0.0/APIKeyHTTPSecurityScheme.json"

definitions/3.0.0/BearerHTTPSecurityScheme.json

@@ -7,21 +7,25 @@
   "properties": {
     "scheme": {
       "type": "string",
+      "description": "The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235.",
       "enum": [
         "bearer"
       ]
     },
     "bearerFormat": {
-      "type": "string"
+      "type": "string",
+      "description": "A hint to the client to identify how the bearer token is formatted. Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes."
     },
     "type": {
       "type": "string",
+      "description": "The type of the security scheme.",
       "enum": [
         "http"
       ]
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme. CommonMark syntax MAY be used for rich text representation."
     }
   },
   "patternProperties": {

definitions/3.0.0/NonBearerHTTPSecurityScheme.json

@@ -4,6 +4,7 @@
     "properties": {
       "scheme": {
         "type": "string",
+        "description": "A short description for security scheme.",
         "enum": [
           "bearer"
         ]
@@ -17,13 +18,16 @@
   ],
   "properties": {
     "scheme": {
-      "type": "string"
+      "type": "string",
+      "description": "The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235."
     },
     "description": {
-      "type": "string"
-    },
+			"type": "string",
+			"description": "A short description for security scheme."
+		},
     "type": {
       "type": "string",
+      "description": "The type of the security scheme.",
       "enum": [
         "http"
       ]

definitions/3.0.0/Reference.json

@@ -1,13 +1,18 @@
 {
   "type": "object",
+  "description": "A simple object to allow referencing other components in the specification, internally and externally.",
   "required": [
     "$ref"
   ],
   "properties": {
     "$ref": {
+      "description": "The reference string.",
       "$ref": "http://asyncapi.com/definitions/3.0.0/ReferenceObject.json"
     }
   },
+	"example": {
+		"$ref": "http://asyncapi.com/examples/3.0.0/ReferenceObject.json"
+	},
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/3.0.0/Reference.json"
 }

definitions/3.0.0/SaslGssapiSecurityScheme.json

@@ -6,19 +6,24 @@
   "properties": {
     "type": {
       "type": "string",
+      "description": "The type of the security scheme.",
       "enum": [
         "gssapi"
       ]
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     }
   },
   "patternProperties": {
     "^x-[\\w\\d\\.\\x2d_]+$": {
       "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
     }
   },
+  "example": {
+    "$ref":  "http://asyncapi.com/examples/3.0.0/Sasl.json"
+  },
   "additionalProperties": false,
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/3.0.0/SaslGssapiSecurityScheme.json"

definitions/3.0.0/SaslPlainSecurityScheme.json

@@ -6,19 +6,24 @@
   "properties": {
     "type": {
       "type": "string",
+      "description": "The type of the security scheme. Valid values",
       "enum": [
         "plain"
       ]
     },
     "description": {
-      "type": "string"
-    }
+			"type": "string",
+			"description": "A short description for security scheme."
+		}
   },
   "patternProperties": {
     "^x-[\\w\\d\\.\\x2d_]+$": {
       "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
     }
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/3.0.0/Sasl.json"
+  },
   "additionalProperties": false,
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/3.0.0/SaslPlainSecurityScheme.json"

definitions/3.0.0/SaslScramSecurityScheme.json

@@ -6,20 +6,25 @@
   "properties": {
     "type": {
       "type": "string",
+      "description": "The type of the security scheme.",
       "enum": [
         "scramSha256",
         "scramSha512"
       ]
     },
     "description": {
-      "type": "string"
-    }
+			"type": "string",
+			"description": "A short description for security scheme."
+		}
   },
   "patternProperties": {
     "^x-[\\w\\d\\.\\x2d_]+$": {
       "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
     }
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/3.0.0/Sasl.json"
+  },
   "additionalProperties": false,
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/3.0.0/SaslScramSecurityScheme.json"

definitions/3.0.0/SecurityScheme.json

@@ -1,4 +1,5 @@
 {
+  "description": "Defines a security scheme that can be used by the operations.",
   "oneOf": [
     {
       "$ref": "http://asyncapi.com/definitions/3.0.0/userPassword.json"
@@ -28,6 +29,9 @@
       "$ref": "http://asyncapi.com/definitions/3.0.0/SaslSecurityScheme.json"
     }
   ],
+  "example": {
+    "$ref": "http://asyncapi.com/examples/3.0.0/SecurityScheme.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/3.0.0/SecurityScheme.json"
 }

definitions/3.0.0/X509.json

@@ -19,6 +19,9 @@
       "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
     }
   },
+  "example": {
+		"$ref": "http://asyncapi.com/examples/3.0.0/X509.json"
+	},
   "additionalProperties": false,
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/3.0.0/X509.json"

definitions/3.0.0/apiKey.json

@@ -7,26 +7,32 @@
   "properties": {
     "type": {
       "type": "string",
+      "description": "The type of the security scheme",
       "enum": [
         "apiKey"
       ]
     },
     "in": {
       "type": "string",
+      "description": " The location of the API key.",
       "enum": [
         "user",
         "password"
       ]
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme. CommonMark syntax MAY be used for rich text representation."
     }
   },
   "patternProperties": {
     "^x-[\\w\\d\\.\\x2d_]+$": {
       "$ref": "http://asyncapi.com/definitions/3.0.0/specificationExtension.json"
     }
   },
+	"example": {
+		"$ref": "http://asyncapi.com/examples/3.0.0/apiKey.json"
+	},
   "additionalProperties": false,
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/3.0.0/apiKey.json"

definitions/3.0.0/asymmetricEncryption.json

@@ -6,12 +6,14 @@
   "properties": {
     "type": {
       "type": "string",
+      "description": "The type of the security scheme.",
       "enum": [
         "asymmetricEncryption"
       ]
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     }
   },
   "patternProperties": {

definitions/3.0.0/asyncapi.json

@@ -31,7 +31,8 @@
       "$ref": "http://asyncapi.com/definitions/3.0.0/servers.json"
     },
     "defaultContentType": {
-      "type": "string"
+      "type": "string",
+      "description": "Default content type to use when encoding/decoding a message's payload."
     },
     "channels": {
       "$ref": "http://asyncapi.com/definitions/3.0.0/channels.json"