DOCSP-11928: [KAFKA] Add support for dotted field names

Author: steveren

source/kafka-sink-data-formats.txt

@@ -169,11 +169,6 @@ Nested Field Schema Example
 The converter handles schemas with nested key or value structures.
 The following is an example AVRO schema with nested fields:
 
-Note the use of :manual:`dot notation </core/document/index.html#dot-notation>`
-in the ``address.city`` and ``address.country`` fields. Dot notation allows
-you to specify nested fields without writing separate lines for the top-level
-document and its sub-documents.
-
 .. code-block:: json
 
    {
@@ -194,11 +189,21 @@ document and its sub-documents.
          "type": "boolean"
        },
        {
-         "name": "address.city",
-         "type": "string"
-       { 
-         "name": "address.country",
-         "type": string"
+         "name": "address",
+         "type": {
+           "type": "record",
+           "name": "AddressRecord",
+           "fields": [
+             {
+               "name": "city",
+               "type": "string"
+             },
+             {
+               "name": "country",
+               "type": "string"
+             }
+           ]
+         }
        },
        {
          "name": "food",
@@ -241,6 +246,26 @@ document and its sub-documents.
      ]
    }
 
+Dot Notation for Nested Fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In the above schema example, the ``address`` field is a document with two
+sub-fields, ``city`` and ``country``. It's also possible to specify those
+fields with dot notation:
+
+.. code-block:: json
+
+   {
+     "name": "address.city",
+     "type": "string"
+   },
+   { 
+     "name": "address.country",
+     "type": string"
+   }
+
+Dot notation allows you to specify nested fields without using separate
+lines for the top-level document and its sub-documents.
 
 .. _avro-logical-types-example: