Clarify that metadata has no namespace

Closes #1352
smithy-lang · Dec 1, 2022 · 7d540f6 · 7d540f6
1 parent af5ad4e
commit 7d540f6
Show file tree

Hide file tree

Showing 2 changed files with 45 additions and 0 deletions.
diff --git 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
@@ -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