Define syntax for escaping declarative config env var substitution

specification/configuration/data-model.md

@@ -57,7 +57,7 @@ Configuration files support environment variables substitution for references
 which match the following PCRE2 regular expression:
 
 ```regexp
-\$\{(?:env:)?(?<ENV_NAME>[a-zA-Z_][a-zA-Z0-9_]*)(:-(?<DEFAULT_VALUE>[^\n]*))?\}
+\${1,2}\{(?:env:)?(?<ENV_NAME>[a-zA-Z_][a-zA-Z0-9_]*)(:-(?<DEFAULT_VALUE>[^\n]*))?\}
 ```
 
 The `ENV_NAME` MUST start with an alphabetic or `_` character, and is followed
@@ -69,6 +69,10 @@ and `${API_$KEY}` are invalid.
 Environment variable substitution MUST only apply to scalar values. Mapping keys
 are not candidates for substitution.
 
+`$$` at the start of an environment variable substitution reference indicates
+that the reference is escaped and MUST not be substituted. For
+example `$${API_KEY}` resolves to `${API_KEY}`.
+
 The `DEFAULT_VALUE` is an optional fallback value which is substituted
 if `ENV_NAME` is null, empty, or undefined. `DEFAULT_VALUE` consists of 0 or
 more non line break characters (i.e. any character except `\n`). If a referenced
@@ -125,24 +129,28 @@ undefined_key: ${UNDEFINED_KEY}                       # Invalid reference, UNDEF
 ${STRING_VALUE}: value                                # Invalid reference, substitution is not valid in mapping keys and reference is ignored
 recursive_key: ${REPLACE_ME}                          # Valid reference to REPLACE_ME
 # invalid_identifier_key: ${STRING_VALUE:?error}      # If uncommented, this is an invalid identifier, it would fail to parse
+escaped_key: $${STRING_VALUE}                         # Escaped reference, remove initial "$" and do not perform substitution
+escaped_key_with_default: $${STRING_VALUE:-fallback}  # Escaped reference, remove initial "$" and do not perform substitution
 ```
 
 Environment variable substitution results in the following YAML:
 
 ```yaml
-string_key: value                              # Interpreted as type string, tag URI tag:yaml.org,2002:str
-env_string_key: value                          # Interpreted as type string, tag URI tag:yaml.org,2002:str
-other_string_key: "value"                      # Interpreted as type string, tag URI tag:yaml.org,2002:str
-another_string_key: "true"                     # Interpreted as type string, tag URI tag:yaml.org,2002:str
-string_key_with_quoted_hex_value: "0xdeadbeef" # Interpreted as type string, tag URI tag:yaml.org,2002:str
-yet_another_string_key: "value\nkey:value"     # Interpreted as type string, tag URI tag:yaml.org,2002:str
-bool_key: true                                 # Interpreted as type bool, tag URI tag:yaml.org,2002:bool
-int_key: 1                                     # Interpreted as type int, tag URI tag:yaml.org,2002:int
-int_key_with_unquoted_hex_value: 3735928559    # Interpreted as type int, tag URI tag:yaml.org,2002:int
-float_key: 1.1                                 # Interpreted as type float, tag URI tag:yaml.org,2002:float
-combo_string_key: foo value 1.1                # Interpreted as type string, tag URI tag:yaml.org,2002:str
-string_key_with_default: fallback              # Interpreted as type string, tag URI tag:yaml.org,2002:str
-undefined_key:                                 # Interpreted as type null, tag URI tag:yaml.org,2002:null
-${STRING_VALUE}: value                         # Interpreted as type string, tag URI tag:yaml.org,2002:str
-recursive_key: ${DO_NOT_REPLACE_ME}            # Interpreted as type string, tag URI tag:yaml.org,2002:str
+string_key: value                                   # Interpreted as type string, tag URI tag:yaml.org,2002:str
+env_string_key: value                               # Interpreted as type string, tag URI tag:yaml.org,2002:str
+other_string_key: "value"                           # Interpreted as type string, tag URI tag:yaml.org,2002:str
+another_string_key: "true"                          # Interpreted as type string, tag URI tag:yaml.org,2002:str
+string_key_with_quoted_hex_value: "0xdeadbeef"      # Interpreted as type string, tag URI tag:yaml.org,2002:str
+yet_another_string_key: "value\nkey:value"          # Interpreted as type string, tag URI tag:yaml.org,2002:str
+bool_key: true                                      # Interpreted as type bool, tag URI tag:yaml.org,2002:bool
+int_key: 1                                          # Interpreted as type int, tag URI tag:yaml.org,2002:int
+int_key_with_unquoted_hex_value: 3735928559         # Interpreted as type int, tag URI tag:yaml.org,2002:int
+float_key: 1.1                                      # Interpreted as type float, tag URI tag:yaml.org,2002:float
+combo_string_key: foo value 1.1                     # Interpreted as type string, tag URI tag:yaml.org,2002:str
+string_key_with_default: fallback                   # Interpreted as type string, tag URI tag:yaml.org,2002:str
+undefined_key:                                      # Interpreted as type null, tag URI tag:yaml.org,2002:null
+${STRING_VALUE}: value                              # Interpreted as type string, tag URI tag:yaml.org,2002:str
+recursive_key: ${DO_NOT_REPLACE_ME}                 # Interpreted as type string, tag URI tag:yaml.org,2002:str
+escaped_key: ${STRING_VALUE}                        # Interpreted as type string, tag URI tag:yaml.org,2002:str
+escaped_key_with_default: ${STRING_VALUE:-fallback} # Interpreted as type string, tag URI tag:yaml.org,2002:str
 ```