add the $descriptions object

README.md

@@ -1,22 +1,21 @@
 # JSON X-Types
 
-This document aims to define a data type format that can be used to describe JSON-like structures in a simple and natural way.
+This document aims to define a data type format for describing JSON-like structures in a simple and natural way.
 Any [valid JSON](https://www.json.org/) could be validated against a **JSON X-Type** definition.
 
 ## Reserved Keywords
 
-There are several reserved words in **JSON X-Types** which could be used either as keys or values:
-
-| Keyword   | Description                                              | Usage      |
-| --------- | -------------------------------------------------------- | ---------- |
-| string    | String type.                                             | key, value |
-| number    | Number type.                                             | value      |
-| boolean   | Boolean type.                                            | value      |
-| null      | The `null` value.                                        | value      |
-| undefined | Value is not set (the corresponding key is not present). | value      |
-| array     | Array generic.                                           | key        |
-| any       | Any value (not validated).                               | value      |
-| $and      | Refers to the intersection of an array members.          | key        |
+| Keyword       | Description                                               | Usage      |
+| ------------- | --------------------------------------------------------- | ---------- |
+| string        | String type.                                              | key, value |
+| number        | Number type.                                              | value      |
+| boolean       | Boolean type.                                             | value      |
+| null          | The `null` value.                                         | value      |
+| undefined     | Value is not set (the corresponding key is not present).  | value      |
+| array         | Array generic.                                            | key        |
+| any           | Any value (not validated).                                | value      |
+| $and          | Refers to the intersection of an array members.           | key        |
+| $descriptions | Object with descriptions of the fields at the same level. | key        |
 
 ## Prefixes
 

applications/__tests__/__snapshots__/e2e.test.js.snap

@@ -135,6 +135,110 @@ components:
 "
 `;
 
+exports[`bundle > descriptions in x-types 1`] = `
+"openapi: 3.1.0
+info:
+  title: Test
+  version: 1.0.0
+paths:
+  /test:
+    get:
+      responses:
+        '200':
+          description: Root response description.
+          content:
+            application/json:
+              x-type:
+                Plain: string
+                Complex:
+                  array:
+                    string: boolean
+                    $literal:string:
+                      - $literal:number
+                      - $literal:string
+                    $descriptions:
+                      string: |
+                        An example of using literals.
+                Conditional:
+                  - az
+                  - undefined
+                $literal:$descriptions: $descriptions
+                Referenced: string
+                NestedReferenced:
+                  ReferencedAgain:
+                    $ref: '#/components/x-types/Referenced'
+                  $descriptions:
+                    ReferencedAgain: Referenced inside the ref.
+                $descriptions:
+                  Plain: A plain string field.
+                  Complex: An array of boolean records with the fixed 'string' property.
+                  Conditional: A conditional field.
+                  $descriptions: Literal $descriptions field.
+                  Referenced: A referenced property.
+                  NestedReferenced: A reference with nested references.
+              schema:
+                type: object
+                properties:
+                  Plain:
+                    type: string
+                    description: A plain string field.
+                  Complex:
+                    type: array
+                    items:
+                      type: object
+                      properties:
+                        string:
+                          type: string
+                          enum:
+                            - number
+                            - string
+                          description: |
+                            An example of using literals.
+                      required:
+                        - string
+                      additionalProperties:
+                        type: boolean
+                    description: An array of boolean records with the fixed 'string' property.
+                  Conditional:
+                    type: string
+                    enum:
+                      - az
+                    description: A conditional field.
+                  $descriptions:
+                    type: string
+                    enum:
+                      - $descriptions
+                    description: Literal $descriptions field.
+                  Referenced:
+                    type: string
+                    description: A referenced property.
+                  NestedReferenced:
+                    type: object
+                    properties:
+                      ReferencedAgain:
+                        type: string
+                        description: Referenced inside the ref.
+                    required:
+                      - ReferencedAgain
+                    additionalProperties: false
+                    description: A reference with nested references.
+                required:
+                  - Plain
+                  - Complex
+                  - $descriptions
+                  - Referenced
+                  - NestedReferenced
+                additionalProperties: false
+components:
+  x-types:
+    Referenced: string
+    NestedReferenced:
+      ReferencedAgain: string
+      $descriptions:
+        ReferencedAgain: Referenced inside the ref.
+"
+`;
+
 exports[`bundle > distributivity in x-types 1`] = `
 "openapi: 3.1.0
 info:

applications/__tests__/e2e.test.js

@@ -97,6 +97,13 @@ describe("bundle", () => {
     )
     expect(preserved).toMatchSnapshot()
   })
+
+  test("descriptions in x-types", () => {
+    const {stdout} = runCommand(
+      "redocly bundle applications/resources/openapi-with-descriptions.yaml --config=applications/x-redocly.yaml"
+    )
+    expect(stdout).toMatchSnapshot()
+  })
 })
 
 describe("lint", () => {

applications/resources/openapi-with-descriptions.yaml

@@ -0,0 +1,47 @@
+openapi: 3.1.0
+info:
+  title: Test
+  version: 1.0.0
+paths:
+  /test:
+    get:
+      responses:
+        200:
+          description: Root response description.
+          content:
+            application/json:
+              x-type:
+                Plain: string
+                Complex:
+                  array:
+                    string: boolean # cannot have description
+                    $literal:string:
+                      - $literal:number
+                      - $literal:string
+                    $descriptions:
+                      string: |
+                        An example of using literals.
+                Conditional:
+                  - az
+                  - undefined
+                $literal:$descriptions: $descriptions
+                Referenced:
+                  $ref: "#/components/x-types/Referenced"
+                NestedReferenced:
+                  $ref: "#/components/x-types/NestedReferenced"
+                $descriptions:
+                  Plain: A plain string field.
+                  Complex: An array of boolean records with the fixed 'string' property.
+                  Conditional: A conditional field.
+                  $descriptions: Literal $descriptions field.
+                  Referenced: A referenced property.
+                  NestedReferenced: A reference with nested references.
+
+components:
+  x-types:
+    Referenced: string
+    NestedReferenced:
+      ReferencedAgain:
+        $ref: "#/components/x-types/Referenced"
+      $descriptions:
+        ReferencedAgain: Referenced inside the ref.

applications/x-types-adapter.js

@@ -111,7 +111,7 @@ const translateXTypeToSchema = xType => {
   if (isObject(xType)) {
     let properties = {}
     let required = []
-    const {string, ...props} = xType
+    const {string, $descriptions, ...props} = xType
     const additionalProperties =
       typeof string === "undefined" ? false : translateXTypeToSchema(string)
 
@@ -129,6 +129,12 @@ const translateXTypeToSchema = xType => {
       }
     }
 
+    // All fields at this level could have descriptions defined inside the $description field.
+    for (const describedPropertyKey in $descriptions) {
+      properties[describedPropertyKey].description =
+        $descriptions[describedPropertyKey]
+    }
+
     return {type: "object", properties, required, additionalProperties}
   }