diff --git a/docs/source-1.0/spec/core/idl.rst b/docs/source-1.0/spec/core/idl.rst
index af66f425079..1e42b5c4870 100644
--- a/docs/source-1.0/spec/core/idl.rst
+++ b/docs/source-1.0/spec/core/idl.rst
@@ -385,6 +385,28 @@ The following example defines metadata in the model:
             }
         }
 
+Metadata is not defined within a namespace. Unquoted object property values
+are considered :ref:`syntactic shape IDs <syntactic-shape-ids>` and resolve
+to the prelude namespace, ``smithy.api``.
+
+The following Smithy IDL model:
+
+.. code-block:: smithy
+
+    $version: "1.0"
+    metadata exampleSyntacticShapeId = required
+
+Is equivalent to the following JSON AST model:
+
+.. code-block:: json
+
+    {
+        "smithy": "1.0",
+        "metadata": {
+            "exampleSyntacticShapeId": "smithy.api#required"
+        }
+    }
+
 
 -------------
 Shape section
diff --git a/docs/source-2.0/spec/idl.rst b/docs/source-2.0/spec/idl.rst
index bec7e288c64..38720b56c50 100644
--- a/docs/source-2.0/spec/idl.rst
+++ b/docs/source-2.0/spec/idl.rst
@@ -390,6 +390,7 @@ The following example defines metadata in the model:
 
     .. code-block:: smithy
 
+        $version: "2"
         metadata greeting = "hello"
         metadata "stringList" = ["a", "b", "c"]
 
@@ -405,6 +406,28 @@ The following example defines metadata in the model:
             }
         }
 
+Metadata is not defined within a namespace. Unquoted object property values
+are considered :ref:`syntactic shape IDs <syntactic-shape-ids>` and resolve
+to the prelude namespace, ``smithy.api``.
+
+The following Smithy IDL model:
+
+.. code-block:: smithy
+
+    $version: "2"
+    metadata exampleSyntacticShapeId = required
+
+Is equivalent to the following JSON AST model:
+
+.. code-block:: json
+
+    {
+        "smithy": "2",
+        "metadata": {
+            "exampleSyntacticShapeId": "smithy.api#required"
+        }
+    }
+
 
 -------------
 Shape section