Correct usage of YAMLMapper when parsing nested key names with dot (.)

Jackson's YAMLMapper does not treat the dot (.) as a nested path separator by default; it strictly follows the YAML specification and treats `formatting.template` as a complete key name rather than a nested structure, so it needs to be matched with the correct JSON Pointer path (such as `/formatting.template`) to accurately locate it.

When using Jackson's YAMLMapper to parse YAML configuration, a common misunderstanding is that the period (.) in YAML naturally represents nesting levels (for example, formatting.template.fields is equivalent to formatting: template: fields:). But YAML itself doesn't treat . as a syntactic separator - it's just an ordinary character. Only when frameworks such as Spring Boot convert YAML into a Properties structure internally, will the unescaped period be interpreted as a level separator.

So when you write the following YAML:

 formatting.template:
  fields:
    - name: birthdate
      type: java.lang.String
      subType: java.util.Date
      length: 10

YAML parsers (including YAMLMapper) will parse it into a single-layer mapping , whose key is the string "formatting.template" and value is an object containing fields. At this point, if you still use JSON Pointer /formatting/template (the intention is "enter formatting object → enter template object"), a MismatchedInputException or No content to map due to end-of-input will be triggered due to path mismatch - because there is no field named formatting in the actual root object.

✅ The correct approach is to keep the YAML key name as it is and use a JSON Pointer that strictly matches it :

 return mapper.readerFor(FormattingConfigurationProperties.class)
             .at("/formatting.template") // ← Key: The path must contain dots and quotes (JSON Pointer specification)
             .readValue(inputStream);

⚠️ Notes:

• If the path in JSON Pointer contains special characters (such as ., /, ~), it must be escaped according to the RFC 6901 specification: . → ~1, ~ → ~0. However, the at() method of YAMLMapper can usually directly support simple dots (no need to escape to ~1). It is recommended to try /formatting.template first; if it fails, try /formatting~1template again.
• @ConfigurationProperties In the Spring Boot scenario, the .yml file is automatically converted into a flat PropertySource by Spring. At this time, formatting.template.fields[0].name can be bound directly without manually calling YAMLMapper . This article discusses pure Jackson YAMLMapper manual parsing scenarios .
• If you want to keep the semantics clear and avoid ambiguity, it is more recommended to use the standard nested format (i.e. newline and indentation) :

 formatting:
  template:
    fields:
      - name: birthdate
        type: java.lang.String
        subType: java.util.Date
        length: 10

The corresponding code remains unchanged (/formatting/template is still used), with clear semantics, strong compatibility, and less error-prone.

Summary: The dot in YAML is not a grammatical symbol, but a part of the key name; Jackson does not do automatic "dot splitting", so the JSON Pointer path must be completely consistent with the actual structure of YAML. Understanding this difference can completely avoid MismatchedInputException.

The above is the detailed content of Correct usage of YAMLMapper when parsing nested key names with dot (.). For more information, please follow other related articles on the PHP Chinese website!