What “flattened JSON” means

A structured YAML document represents nested objects. A flattened JSON document moves each leaf value to one top-level key and encodes its original path in that key. Local Dev Kit uses a dot between object segments and bracketed indexes for array items.

Structured YAML

service:
  name: catalog
  retries: 3
  regions:
    - us-east-1
    - ap-south-1

Flattened JSON

{
  "service.name": "catalog",
  "service.retries": 3,
  "service.regions[0]": "us-east-1",
  "service.regions[1]": "ap-south-1"
}

This shape is useful when a deployment system accepts a flat key/value map even though the application configuration is naturally hierarchical.

Choose types deliberately

YAML can represent strings, numbers, booleans, nulls, arrays, and objects. JSON can represent the same core types, but pipeline interfaces often turn every value into a string. Decide whether the destination expects typed JSON or string-safe deployment values.

  • Keep identifiers such as "00130" quoted if leading zeroes matter.
  • Keep version fragments and port-like values as strings when the consumer treats them as text.
  • Use Preserve for portable JSON types; use Strings when the receiving system expects string-only deployment values.
  • Review nulls and empty containers because a flat key/value format may not preserve them without a policy decision.

Watch for path collisions

A source key that already contains a dot can become indistinguishable from a nested path. For example, service.name at the root conflicts with service: { name: ... }. A safe converter must block that ambiguity instead of silently overwriting one value.

A repeatable CI/CD workflow

  1. Work from a reviewed copy of the source configuration and remove real secrets from examples.
  2. Select YAML as the source and JSON as the deployment target.
  3. Select Flattened shape and the value policy expected by the receiving platform.
  4. Convert locally, then open Conversion Impact and review every error or warning.
  5. Check arrays, quoted identifiers, nulls, empty containers, and keys containing dots or brackets.
  6. Copy or download only while the result is marked Current; a source edit makes the old result Out of date.
  7. Validate the artifact in a non-production pipeline before replacing the deployed configuration.

Limitations

Comments, anchors, aliases, custom YAML tags, and presentation choices are not equivalent to JSON data. Conversion produces a data representation, not a byte-for-byte round trip. The tool is limited to the displayed input-size boundary and intentionally performs no server upload or background source conversion while you type.