Block-style YAML vs Flow-style YAML

Photo by Markus Spiske on Unsplash

So while updating the YAML for a gitlab configuration, I pushed in a YAML that looked like this (just a sample YAML for example only):

default:
  image: nginx
  before_script:
    - echo "hello"
    - echo "world"
stages:
  - test
.env_vars:
  variables:
    ENV: $CI_ENVIRONMENT_NAME
.test:
  stage: test
  when: always
  allow_failure: false
  artifacts:
    paths:
      - envs/${ENV}/builds
      - envs/${ENV}/caches
    expire_in: 30 minutes
  script: ./scripts/run_test.sh
dev_test:
  environment: { name: dev }
  extends: [ .env_vars, .test ]

As you can see above, the entire YAML was following block-style YAML (strict indented syntax) for lists & objects. However, the last dev_test: section suddenly used flow-style YAML (flexible json-isque syntax).

To which, one of my peers raised a concern while reviewing the code: “Can we follow a single style of block syntax only and not mix the two?”

He proposed the dev_test: portion above be revised to the following:

dev_test:
  environment:
    name: dev
  extends:
    - .env_vars
    - .test

So what’s happening here?

• 3 lines are becoming 6 lines
• but the entire file is following a single YAML style - the block style.

Then I thought over this:

• Is this really necessary?
• What happens if we do mix the 2 styles?
• Does it make the YAMLs hard-to-read?
• Is flow-syntax a dirty syntax that should be avoided from YAMLs?

So I did some reading over the internet to find what the community says about this. And I would like to share those findings here.

Some examples in the Prometheus Operator repo. They maintained block style all along. But, they also put small rudimentary items (like single-item lists) in flow-style - instead of cranking up the number of lines just for the sake of “must follow a single style”.

https://github.com/crdoconnor/strictyaml/issues/20. This issue is closed today. However, they did mix flow-style in some areas where it was reasonable (and, in fact, more understandable) than reading one-item-per-line. Imagine having to read a matrix notation one-item-per-line just for the sake of “must follow a single style”.

This guys here, is saying what I kinda follow myself:

I avoid flow style in most cases, the only case I want to use flow style is when the data is simple enough so it could be wrote in one line.

Again, a mix of both styles is acceptable when done reasonably.

This reddit here is also very rich with many opinions.

Finally, what I think honestly is that, block-style is preferred all the way - no doubt about that. It is clean, it is easy to read, it forms a visual step graph when reading the file, all that makes reading block style YAMLs very convenient.

However, mixing flow-style in some areas can also be reasonable. It does not compromise readability of the YAML as long as:

• it’s not too long
• it’s not too many items
• it does not have too many key-values
• it does not have too much nesting

If it’s easy to read, IMO it doesn’t have to be like “must follow a single style”.

However, this was just my opinion on the subject. Feel free to share your opinion as well - I will be happy to hear from you. Remember, there is no right or wrong here. But there are many different practices which we should be aware of to make informed decisions about when & where we can.