@asyncapi/specs - npm Package Compare versions

Comparing version 5.0.1 to 5.1.0

definitions/2.6.0/apiKey.json

@@ -10,2 +10,3 @@ {
       "type": "string",
+      "description": "The type of the security scheme.",
       "enum": [
@@ -17,2 +18,3 @@ "apiKey"
       "type": "string",
+      "description": "The location of the API key. ",
       "enum": [
@@ -24,3 +26,4 @@ "user",
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     }
@@ -33,2 +36,5 @@ },
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/apiKey.json"
+  },
   "additionalProperties": false,
@@ -35,0 +41,0 @@ "$schema": "http://json-schema.org/draft-07/schema#",

definitions/2.6.0/APIKeyHTTPSecurityScheme.json

@@ -11,2 +11,3 @@ {
       "type": "string",
+      "description": "The type of the security scheme. ",
       "enum": [
@@ -17,6 +18,8 @@ "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": [
@@ -29,3 +32,4 @@ "header",
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     }
@@ -38,2 +42,5 @@ },
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/APIKeyHTTPSecurityScheme.json"
+  },
   "additionalProperties": false,
@@ -40,0 +47,0 @@ "$schema": "http://json-schema.org/draft-07/schema#",

definitions/2.6.0/asymmetricEncryption.json

@@ -9,2 +9,3 @@ {
       "type": "string",
+      "description": "The type of the security scheme.",
       "enum": [
@@ -15,3 +16,4 @@ "asymmetricEncryption"
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     }
@@ -18,0 +20,0 @@ },

definitions/2.6.0/BearerHTTPSecurityScheme.json

@@ -10,2 +10,3 @@ {
       "type": "string",
+      "description": "The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235.",
       "enum": [
@@ -16,6 +17,8 @@ "bearer"
     "bearerFormat": {
-      "type": "string"
+      "type": "string",
+      "description": "A hint to the client to identify how the bearer token is formatted."
     },
     "type": {
       "type": "string",
+      "description": "The type of the security scheme. ",
       "enum": [
@@ -26,3 +29,4 @@ "http"
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     }
@@ -29,0 +33,0 @@ },

definitions/2.6.0/bindingsObject.json

 {
   "type": "object",
+  "description": "Map describing protocol-specific definitions for a server.",
   "additionalProperties": true,
@@ -4,0 +5,0 @@ "properties": {

definitions/2.6.0/channelItem.json

 {
   "type": "object",
+  "description": "Describes the operations available on a single channel.",
   "additionalProperties": false,
@@ -42,4 +43,7 @@ "patternProperties": {
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/channelItem.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/channelItem.json"
 }

definitions/2.6.0/channels.json

 {
   "type": "object",
+  "description": "Holds the relative paths to the individual channel and their operations. Channel paths are relative to servers.",
   "propertyNames": {
@@ -11,4 +12,7 @@ "type": "string",
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/channels.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/channels.json"
 }

definitions/2.6.0/components.json

 {
   "type": "object",
-  "description": "An object to hold a set of reusable objects for different aspects of the AsyncAPI Specification.",
+  "description": "Holds a set of reusable objects for different aspects of the AsyncAPI specification. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.",
   "additionalProperties": false,
@@ -96,4 +96,7 @@ "patternProperties": {
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/components.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/components.json"
 }

definitions/2.6.0/contact.json

 {
   "type": "object",
-  "description": "Contact information for the owners of the API.",
+  "description": "Contact information for the exposed API.",
   "additionalProperties": false,
@@ -26,4 +26,7 @@ "properties": {
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/contact.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/contact.json"
 }

definitions/2.6.0/correlationId.json

 {
   "type": "object",
+  "description": "An object that specifies an identifier at design time that can used for message tracing and correlation.",
   "required": [
@@ -23,4 +24,7 @@ "location"
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/correlationId.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/correlationId.json"
 }

definitions/2.6.0/externalDocs.json

 {
   "type": "object",
   "additionalProperties": false,
-  "description": "information about external documentation",
-  "required": [
-    "url"
-  ],
+  "description": "Allows referencing an external resource for extended documentation.",
+  "required": ["url"],
   "properties": {
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description of the target documentation."
     },
     "url": {
       "type": "string",
-      "format": "uri"
+      "format": "uri",
+      "description": "The URL for the target documentation. This MUST be in the form of an absolute URL."
     }
@@ -22,4 +22,7 @@ },
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/externalDocs.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/externalDocs.json"
 }

definitions/2.6.0/info.json

 {
   "type": "object",
-  "description": "General information about the API.",
+  "description": "The object provides metadata about the API. The metadata can be used by the clients if needed.",
   "required": [
@@ -39,4 +39,7 @@ "version",
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/info.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/info.json"
 }

definitions/2.6.0/license.json

@@ -6,2 +6,3 @@ {
   ],
+  "description": "License information for the exposed API.",
   "additionalProperties": false,
@@ -24,4 +25,7 @@ "properties": {
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/license.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/license.json"
 }

definitions/2.6.0/message.json

 {
+  "description": "Describes a message received on a given channel and operation.",
   "oneOf": [
@@ -96,2 +97,3 @@ {
               "type": "array",
+              "description": "List of examples.",
               "items": {
@@ -118,5 +120,8 @@ "type": "object",
                   "headers": {
-                    "type": "object"
+                    "type": "object",
+                    "description": "Schema definition of the application headers."
                   },
-                  "payload": {}
+                  "payload": {
+                    "description": "Definition of the message payload. It can be of any type"
+                  }
                 }
@@ -273,4 +278,7 @@ }
   ],
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/message.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/message.json"
 }

definitions/2.6.0/messageTrait.json

 {
   "type": "object",
+  "description": "Describes a trait that MAY be applied to a Message Object.",
   "additionalProperties": false,
@@ -11,8 +12,11 @@ "patternProperties": {
     "schemaFormat": {
-      "type": "string"
+      "type": "string",
+      "description": "A string containing the name of the schema format/language used to define the message payload."
     },
     "contentType": {
-      "type": "string"
+      "type": "string",
+      "description": "The content type to use when encoding/decoding a message's payload."
     },
     "headers": {
+      "description": "Schema definition of the application headers.",
       "allOf": [
@@ -32,5 +36,7 @@ {
     "messageId": {
-      "type": "string"
+      "type": "string",
+      "description": "Unique string used to identify the message. The id MUST be unique among all messages described in the API."
     },
     "correlationId": {
+      "description": "Definition of the correlation ID used for message tracing or matching.",
       "oneOf": [
@@ -47,2 +53,3 @@ {
       "type": "array",
+      "description": "A list of tags for logical grouping and categorization of messages.",
       "items": {
@@ -78,4 +85,31 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/tag.json"
       "type": "array",
+      "description": "List of examples.",
       "items": {
-        "type": "object"
+        "type": "object",
+        "additionalProperties": false,
+        "anyOf": [
+          {
+            "required": ["payload"]
+          },
+          {
+            "required": ["headers"]
+          }
+        ],
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Machine readable name of the message example."
+          },
+          "summary": {
+            "type": "string",
+            "description": "A brief summary of the message example."
+          },
+          "headers": {
+            "type": "object",
+            "description": "Schema definition of the application headers."
+          },
+          "payload": {
+            "description": "Definition of the message payload. It can be of any type"
+          }
+        }
       }
@@ -87,4 +121,7 @@ },
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/messageTrait.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/messageTrait.json"
-}
+}

definitions/2.6.0/NonBearerHTTPSecurityScheme.json

@@ -7,2 +7,3 @@ {
         "type": "string",
+        "description": "A short description for security scheme.",
         "enum": [
@@ -21,9 +22,12 @@ "bearer"
     "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": [
@@ -30,0 +34,0 @@ "http"

definitions/2.6.0/oauth2Flow.json

 {
   "type": "object",
+  "description": "Configuration details for a supported OAuth Flow",
   "properties": {
     "authorizationUrl": {
       "type": "string",
-      "format": "uri"
+      "format": "uri",
+      "description": "The authorization URL to be used for this flow. This MUST be in the form of an absolute URL."
     },
     "tokenUrl": {
       "type": "string",
-      "format": "uri"
+      "format": "uri",
+      "description": "The token URL to be used for this flow. This MUST be in the form of an absolute URL."
     },
     "refreshUrl": {
       "type": "string",
-      "format": "uri"
+      "format": "uri",
+      "description": "The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL."
     },
     "scopes": {
+      "description": "The available scopes for the OAuth2 security scheme. A map between the scope name and a short description for it.",
       "$ref": "http://asyncapi.com/definitions/2.6.0/oauth2Scopes.json"
@@ -26,4 +31,7 @@ }
   "additionalProperties": false,
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/oauth2Flow.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/oauth2Flow.json"
 }

definitions/2.6.0/oauth2Flows.json

 {
   "type": "object",
+  "description": "Allows configuration of the supported OAuth Flows.",
   "required": [
@@ -10,2 +11,3 @@ "type",
       "type": "string",
+      "description": "A short description for security scheme.",
       "enum": [
@@ -16,3 +18,4 @@ "oauth2"
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     },
@@ -23,2 +26,3 @@ "flows": {
         "implicit": {
+          "description": "Configuration for the OAuth Implicit flow.",
           "allOf": [
@@ -44,2 +48,3 @@ {
         "password": {
+          "description": "Configuration for the OAuth Resource Owner Protected Credentials flow.",
           "allOf": [
@@ -65,2 +70,3 @@ {
         "clientCredentials": {
+          "description": "Configuration for the OAuth Client Credentials flow.",
           "allOf": [
@@ -86,2 +92,3 @@ {
         "authorizationCode": {
+          "description": "Configuration for the OAuth Authorization Code flow.",
           "allOf": [
@@ -88,0 +95,0 @@ {

definitions/2.6.0/operation.json

 {
   "type": "object",
+  "description": "Describes a publish or a subscribe operation. This provides a place to document how and why messages are sent and received.",
   "additionalProperties": false,
@@ -12,2 +13,3 @@ "patternProperties": {
       "type": "array",
+      "description": "A list of traits to apply to the operation object.",
       "items": {
@@ -25,9 +27,12 @@ "oneOf": [
     "summary": {
-      "type": "string"
+      "type": "string",
+      "description": "A short summary of what the operation is about."
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A verbose explanation of the operation."
     },
     "security": {
       "type": "array",
+      "description": "A declaration of which security mechanisms are associated with this operation.",
       "items": {
@@ -39,2 +44,3 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/SecurityRequirement.json"
       "type": "array",
+      "description": "A list of tags for logical grouping and categorization of operations.",
       "items": {
@@ -58,4 +64,7 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/tag.json"
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/channels.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/operation.json"
 }

definitions/2.6.0/operationTrait.json

 {
   "type": "object",
+  "description": "Describes a trait that MAY be applied to an Operation Object.",
   "additionalProperties": false,
@@ -11,9 +12,12 @@ "patternProperties": {
     "summary": {
-      "type": "string"
+      "type": "string",
+      "description": "A short summary of what the operation is about."
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A verbose explanation of the operation."
     },
     "tags": {
       "type": "array",
+      "description": "A list of tags for logical grouping and categorization of operations.",
       "items": {
@@ -28,6 +32,8 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/tag.json"
     "operationId": {
-      "type": "string"
+      "type": "string",
+      "description": "Unique string used to identify the operation. The id MUST be unique among all operations described in the API."
     },
     "security": {
       "type": "array",
+      "description": "A declaration of which security mechanisms are associated with this operation. ",
       "items": {
@@ -41,4 +47,7 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/SecurityRequirement.json"
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/operationTrait.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/operationTrait.json"
 }

definitions/2.6.0/parameter.json

 {
+  "description": "Describes a parameter included in a channel name.",
   "additionalProperties": false,
@@ -22,4 +23,7 @@ "patternProperties": {
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/parameter.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/parameter.json"
 }

definitions/2.6.0/parameters.json

 {
   "type": "object",
+  "description": "JSON objects describing reusable channel parameters.",
   "additionalProperties": {
@@ -13,5 +14,7 @@ "oneOf": [
   },
-  "description": "JSON objects describing re-usable channel parameters.",
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/parameters.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/parameters.json"
 }

definitions/2.6.0/ReferenceObject.json

 {
   "type": "string",
+  "description": "A simple object to allow referencing other components in the specification, internally and externally.",
   "format": "uri-reference",
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/ReferenceObject.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/ReferenceObject.json"
 }

definitions/2.6.0/SaslGssapiSecurityScheme.json

@@ -9,2 +9,3 @@ {
       "type": "string",
+      "description": "The type of the security scheme.",
       "enum": [
@@ -15,3 +16,4 @@ "gssapi"
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     }
@@ -24,2 +26,5 @@ },
   },
+  "example": {
+    "$ref":  "http://asyncapi.com/examples/2.6.0/Sasl.json"
+  },
   "additionalProperties": false,
@@ -26,0 +31,0 @@ "$schema": "http://json-schema.org/draft-07/schema#",

definitions/2.6.0/SaslPlainSecurityScheme.json

@@ -9,2 +9,3 @@ {
       "type": "string",
+      "description": "The type of the security scheme. Valid values",
       "enum": [
@@ -15,3 +16,4 @@ "plain"
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     }
@@ -24,2 +26,5 @@ },
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/Sasl.json"
+  },
   "additionalProperties": false,
@@ -26,0 +31,0 @@ "$schema": "http://json-schema.org/draft-07/schema#",

definitions/2.6.0/SaslScramSecurityScheme.json

@@ -9,2 +9,3 @@ {
       "type": "string",
+      "description": "The type of the security scheme.",
       "enum": [
@@ -16,3 +17,4 @@ "scramSha256",
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     }
@@ -25,2 +27,5 @@ },
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/Sasl.json"
+  },
   "additionalProperties": false,
@@ -27,0 +32,0 @@ "$schema": "http://json-schema.org/draft-07/schema#",

definitions/2.6.0/schema.json

 {
+  "description": "The Schema Object allows the definition of input and output data types. These types can be objects, but also primitives and arrays.",
   "allOf": [
@@ -84,5 +85,7 @@ {
         "discriminator": {
-          "type": "string"
+          "type": "string",
+          "description": "Adds support for polymorphism. The discriminator is the schema property name that is used to differentiate between other schema that inherit this schema. "
         },
         "externalDocs": {
+          "description": "Additional external documentation for this schema.",
           "$ref": "http://asyncapi.com/definitions/2.6.0/externalDocs.json"
@@ -92,3 +95,4 @@ },
           "type": "boolean",
-          "default": false
+          "default": false,
+          "description": "Specifies that a schema is deprecated and SHOULD be transitioned out of usage"
         }
@@ -98,4 +102,7 @@ }
   ],
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/schema.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/schema.json"
 }

definitions/2.6.0/SecurityRequirement.json

 {
   "type": "object",
+  "description": "Lists of the required security schemes that can be used to execute an operation",
   "additionalProperties": {
@@ -10,4 +11,7 @@ "type": "array",
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/SecurityRequirement.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/SecurityRequirement.json"
 }

definitions/2.6.0/SecurityScheme.json

 {
+  "description": "Defines a security scheme that can be used by the operations.",
   "oneOf": [
@@ -31,4 +32,7 @@ {
   ],
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/SecurityScheme.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/SecurityScheme.json"
 }

definitions/2.6.0/server.json

 {
   "type": "object",
-  "description": "An object representing a Server.",
+  "description": "An object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data",
   "required": [
@@ -16,15 +16,19 @@ "url",
     "url": {
-      "type": "string"
+      "type": "string",
+      "description": "A URL to the target host. This URL supports Server Variables and MAY be relative, to indicate that the host location is relative to the location where the AsyncAPI document is being served."
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "An optional string describing the host designated by the URL. CommonMark syntax MAY be used for rich text representation."
     },
     "protocol": {
       "type": "string",
-      "description": "The transfer protocol."
+      "description": "The protocol this URL supports for connection. Supported protocol include, but are not limited to: amqp, amqps, http, https, ibmmq, jms, kafka, kafka-secure, anypointmq, mqtt, secure-mqtt, solace, stomp, stomps, ws, wss, mercure, googlepubsub."
     },
     "protocolVersion": {
-      "type": "string"
+      "type": "string",
+      "description": "The version of the protocol used for connection. For instance: AMQP 0.9.1, HTTP 2.0, Kafka 1.0.0, etc."
     },
     "variables": {
+      "description": "A map between a variable name and its value. The value is used for substitution in the server's URL template.",
       "$ref": "http://asyncapi.com/definitions/2.6.0/serverVariables.json"
@@ -34,2 +38,3 @@ },
       "type": "array",
+      "description": "A declaration of which security mechanisms can be used with this server. The list of values includes alternative security requirement objects that can be used. ",
       "items": {
@@ -40,2 +45,3 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/SecurityRequirement.json"
     "bindings": {
+      "description": "A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the server.",
       "$ref": "http://asyncapi.com/definitions/2.6.0/bindingsObject.json"
@@ -45,2 +51,3 @@ },
       "type": "array",
+      "description": "A list of tags for logical grouping and categorization of servers.",
       "items": {
@@ -52,4 +59,7 @@ "$ref": "http://asyncapi.com/definitions/2.6.0/tag.json"
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/server.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/server.json"
 }

definitions/2.6.0/servers.json

 {
-  "description": "An object representing multiple servers.",
+  "description": "The Servers Object is a map of Server Objects.",
   "type": "object",
@@ -14,4 +14,7 @@ "additionalProperties": {
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/servers.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/servers.json"
 }

definitions/2.6.0/serverVariable.json

@@ -13,2 +13,3 @@ {
       "type": "array",
+      "description": "An enumeration of string values to be used if the substitution options are from a limited set.",
       "items": {
@@ -20,9 +21,12 @@ "type": "string"
     "default": {
-      "type": "string"
+      "type": "string",
+      "description": "The default value to use for substitution, and to send, if an alternate value is not supplied."
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "An optional description for the server variable. "
     },
     "examples": {
       "type": "array",
+      "description": "An array of examples of the server variable.",
       "items": {
@@ -29,0 +33,0 @@ "type": "string"

definitions/2.6.0/serverVariables.json

 {
   "type": "object",
+  "description": "A map between a variable name and its value. The value is used for substitution in the server's URL template.",
   "additionalProperties": {
@@ -4,0 +5,0 @@ "oneOf": [

definitions/2.6.0/symmetricEncryption.json

@@ -9,2 +9,3 @@ {
       "type": "string",
+      "description": "The type of the security scheme.",
       "enum": [
@@ -15,3 +16,4 @@ "symmetricEncryption"
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     }
@@ -24,2 +26,5 @@ },
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/symmetricEncryption.json"
+  },
   "additionalProperties": false,
@@ -26,0 +31,0 @@ "$schema": "http://json-schema.org/draft-07/schema#",

definitions/2.6.0/tag.json

 {
   "type": "object",
+  "description": "Allows adding meta data to a single tag.",
   "additionalProperties": false,
@@ -9,8 +10,11 @@ "required": [
     "name": {
-      "type": "string"
+      "type": "string",
+      "description": "The name of the tag."
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for the tag."
     },
     "externalDocs": {
+      "description": "Additional external documentation for this tag.",
       "$ref": "http://asyncapi.com/definitions/2.6.0/externalDocs.json"
@@ -24,4 +28,7 @@ }
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/tag.json"
+  },
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "http://asyncapi.com/definitions/2.6.0/tag.json"
 }

definitions/2.6.0/userPassword.json

@@ -9,2 +9,3 @@ {
       "type": "string",
+      "description": "The type of the security scheme. ",
       "enum": [
@@ -15,3 +16,4 @@ "userPassword"
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     }
@@ -24,2 +26,5 @@ },
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/userPassword.json"
+  },
   "additionalProperties": false,
@@ -26,0 +31,0 @@ "$schema": "http://json-schema.org/draft-07/schema#",

definitions/2.6.0/X509.json

@@ -11,6 +11,8 @@ {
         "X509"
-      ]
+      ],
+      "description": "The type of the security scheme."
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "A short description for security scheme."
     }
@@ -23,2 +25,5 @@ },
   },
+  "example": {
+    "$ref": "http://asyncapi.com/examples/2.6.0/X509.json"
+  },
   "additionalProperties": false,
@@ -25,0 +30,0 @@ "$schema": "http://json-schema.org/draft-07/schema#",

package.json

 {
   "name": "@asyncapi/specs",
-  "version": "5.0.1",
+  "version": "5.1.0",
   "description": "AsyncAPI schema versions",
@@ -5,0 +5,0 @@ "main": "index.js",

README.md

@@ -117,2 +117,3 @@ ![npm](https://img.shields.io/npm/v/@asyncapi/specs?style=for-the-badge) ![npm](https://img.shields.io/npm/dt/@asyncapi/specs?style=for-the-badge)
 - [./definitions](./definitions) - contain all the individual schemas that will automatically be bundled together to provide the schemas in [./schemas](./schemas).
+- [./examples](./examples) - contain most individual definition examples that will automatically be bundled together to provide example for each definition in the schemas in [./schemas](./schemas).
 - [./tools/bundler](./tools/bundler) - is the tool that bundles all the individual schemas together.
@@ -144,2 +145,4 @@ - [./schemas](./schemas) - contain all automatically bundled and complete schemas for each AsyncAPI version. These schemas should **NOT** be manually changed as they are automatically generated. Any changes should be done in [./definitions](./definitions).
 1. Rename the folder to the new version (`x.x.x`).
+1. Duplicate the latest version (`y.y.y`) under examples (so we have the correct base to make changes from).
+1. Rename the folder to the new version (`x.x.x`).
 1. Search and replace in the new duplicated folder for `y.y.y` and replace it with `x.x.x`.
@@ -146,0 +149,0 @@

scripts/add-new-version.js

 /**
- * This script adds a new version of the spec, by copying the latest one as baseline.
+ * This script adds a new version of the spec with examples, by copying the latest one as baseline.
  */
@@ -28,2 +28,3 @@ const exec = require('child_process').exec;
   const newVersionDir = `./definitions/${newVersion}`;
+  const newExampleVersionDir = `./examples/${newVersion}`;
 
@@ -40,2 +41,6 @@ try {
 
+  const latestExampleVersion = (await execute('ls -d ./examples/* | sort -V -r | head -1 | xargs -n 1 basename')).trim();
+  await execute(`cp -R ./definitions/${latestVersion} ${newVersionDir}`);
+  await execute(`cp -R ./examples/${latestExampleVersion} ${newExampleVersionDir}`);
+  
   // Replace old version numbers with new
@@ -42,0 +47,0 @@ await execute(`find ${newVersionDir} -name '*.json' -exec sed -i '' "s+${latestVersion}+${newVersion}+g" {} +`);

tools/bundler/index.js

@@ -31,3 +31,14 @@ const path = require('path');
       for (const jsonFile of definitionJson) {
-        Bundler.add(jsonFile);
+        if (jsonFile.example) {
+          // Replaced the example property with the referenced example property
+          const examples = await loadRefProperties(jsonFile.example);
+          // Replacing example property with examples is because using example
+          // to pass an array of example properties is not valid in JSON Schema.
+          // So replacing it when bundling is the goto solution. 
+          jsonFile.examples = examples;
+          delete jsonFile.example;
+          Bundler.add(jsonFile);
+        } else {
+          Bundler.add(jsonFile);
+        }
       }
@@ -60,2 +71,19 @@ const filePathToBundle = `file://${versionDir}/asyncapi.json`;
 /**
+ * Extract file data from reference file path
+ */
+
+async function loadRefProperties(filePath) {
+  const schemaPath = filePath.$ref;
+  // first we need to turn the path to an absolute file path instead of a generic url
+  const versionPath = schemaPath.split('examples')[1];
+  // we append the extracted file path to the examples dir to read the file
+  try {
+    const data = await fs.promises.readFile(`../../examples${versionPath}`);
+    return JSON.parse(data);
+    }catch(e) {
+      throw new Error(e);
+    }
+  }
+
+/**
  * we first update definitions from URL to normal names
@@ -62,0 +90,0 @@ * than update refs to point to new definitions, always inline never remote

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

15407974

increased by0.62%

Number of package files

982

increased by3.04%

Lines of code

151842

increased by1.45%

Number of lines in readme file

200

increased by1.52%

No dependency changes