diff --git a/json/flags.json b/json/flags.json
index b440b36..82d16cc 100644
--- a/json/flags.json
+++ b/json/flags.json
@@ -49,6 +49,20 @@
           "$ref": "./targeting.json"
         }
       }
+    },
+    "metadata": {
+      "name": "Flag Set Metadata",
+      "description": "Metadata about the flag set, with keys of type string, and values of type boolean, string, or number.",
+      "properties": {
+        "flagSetId": {
+          "description": "The unique identifier for the flag set.",
+          "type": "string"
+        },
+        "version": {
+          "description": "The version of the flag set."
+        }
+      },
+      "$ref": "#/definitions/metadata"
     }
   },
   "definitions": {
@@ -72,6 +86,11 @@
         },
         "targeting": {
           "$ref": "./targeting.json"
+        },
+        "metadata": {
+          "title": "Flag Metadata",
+          "description": "Metadata about an individual feature flag, with keys of type string, and values of type boolean, string, or number.",
+          "$ref": "#/definitions/metadata"
         }
       },
       "required": [
@@ -179,6 +198,18 @@
           "$ref": "#/definitions/objectVariants"
         }
       ]
+    },
+    "metadata": {
+      "type": "object",
+      "additionalProperties": {
+        "description": "Any additional key/value pair with value of type boolean, string, or number.",
+        "type": [
+          "string",
+          "number",
+          "boolean"
+        ]
+      },
+      "required": null
     }
   }
 }
diff --git a/json/flags.yaml b/json/flags.yaml
index 04a3dc1..44783b5 100644
--- a/json/flags.yaml
+++ b/json/flags.yaml
@@ -36,6 +36,16 @@ properties:
         $comment: this relative ref means that targeting.json MUST be in the same
           dir, or available on the same HTTP path
         $ref: "./targeting.json"
+  metadata:
+    name: Flag Set Metadata
+    description: Metadata about the flag set, with keys of type string, and values of type boolean, string, or number.
+    properties:
+      flagSetId:
+        description: The unique identifier for the flag set.
+        type: string
+      version:
+        description: The version of the flag set.
+    $ref: "#/definitions/metadata"
 definitions:
   flag:
     $comment: base flag object; no title/description here, allows for better UX,
@@ -57,6 +67,10 @@ definitions:
         type: string
       targeting:
         $ref: "./targeting.json"
+      metadata:
+        title: Flag Metadata
+        description: Metadata about an individual feature flag, with keys of type string, and values of type boolean, string, or number.
+        $ref: "#/definitions/metadata"
     required:
     - state
     - defaultVariant
@@ -116,3 +130,13 @@ definitions:
     allOf:
     - $ref: "#/definitions/flag"
     - $ref: "#/definitions/objectVariants"
+  metadata:
+    type: object
+    additionalProperties:
+      description: Any additional key/value pair with value of type boolean, string, or number.
+      type:
+       - string
+       - number
+       - boolean
+    # Metadata is optional
+    required:
diff --git a/json/test/flags/negative/with-invalid-flag-metadata.json b/json/test/flags/negative/with-invalid-flag-metadata.json
new file mode 100644
index 0000000..bb5c393
--- /dev/null
+++ b/json/test/flags/negative/with-invalid-flag-metadata.json
@@ -0,0 +1,16 @@
+{
+  "$schema": "../../../flags.json",
+  "flags": {
+    "myBoolFlag": {
+      "state": "ENABLED",
+      "variants": {
+        "on": true,
+        "off": false
+      },
+      "defaultVariant": "on",
+      "metadata": {
+        "invalid": { "key": "value" }
+      }
+    }
+  }
+}
diff --git a/json/test/flags/negative/with-invalid-flag-set-metadata.json b/json/test/flags/negative/with-invalid-flag-set-metadata.json
new file mode 100644
index 0000000..7aae9a2
--- /dev/null
+++ b/json/test/flags/negative/with-invalid-flag-set-metadata.json
@@ -0,0 +1,16 @@
+{
+  "$schema": "../../../flags.json",
+  "flags": {
+    "myBoolFlag": {
+      "state": "ENABLED",
+      "variants": {
+        "on": true,
+        "off": false
+      },
+      "defaultVariant": "on"
+    }
+  },
+  "metadata": {
+    "invalid": { "key": "value" }
+  }
+}
diff --git a/json/test/flags/positive/with-metadata.json b/json/test/flags/positive/with-metadata.json
new file mode 100644
index 0000000..1889d91
--- /dev/null
+++ b/json/test/flags/positive/with-metadata.json
@@ -0,0 +1,30 @@
+{
+  "$schema": "../../../flags.json",
+  "flags": {
+    "headerColor": {
+      "variants": {
+        "red": "#FF0000",
+        "blue": "#0000FF",
+        "green": "#00FF00",
+        "yellow": "#FFFF00"
+      },
+      "defaultVariant": "red",
+      "state": "ENABLED",
+      "metadata": {
+        "flagSetId": "blah",
+        "boolean": true,
+        "string": "string",
+        "float": 1.23,
+        "int": 1
+      }
+    }
+  },
+  "metadata": {
+    "flagSetId": "sso/dev",
+    "version": "1.0.0",
+    "boolean": true,
+    "string": "string",
+    "float": 1.23,
+    "int": 1
+  }
+}