What is the canonical YAML naming style

Question

I am designing a new YAML file, and I want to use the most standard style of naming. Which is it?

kebab-case?

- job-name:
    ...

snake_case?

- job_name:
    ...

CamelCase?

- jobName:
    ...

Completion

That's actually dromedaryCase; as your spelling reveals, proper CamelCase also capitalizes the first word (resulting in two humps). – Femmine

Answer 1

Use the standard dictated by the surrounding software.

For example, in my current project the YAML file contains default values for Python attributes. Since the names used in YAML appear in the associated Python API, it is clear that on this particular project, the YAML names should obey the Python lower_case_with_underscores naming convention per PEP-8.

My next project might have a different prevailing naming convention, in which case I will use that in the associated YAML files.

Completion

YAML is independent, so it does not obey anything. – Fedora

I agree with @Miraage. And, from a practical point of view, what if the "surrounding software" is written in multiple languages? – Ghastly

@RobWorsnop like he said it is independant from the software language. You can use the CASE that you like the most. – Prorate

can a yaml name start with an underscore? like, _jobname__ more precisely, I need this one, __version__ – Stalnaker

At the very least, use the convention that is used by whatever is going to be reading the yaml. For example, you may end up doing more work to get kebab-cased-properties to deserialize correctly in C# or Java. And before someone asks: if you have multiple components let alone in different technologies that will be reading the same yaml, that may be a bit of a smell. – Sped

YAML might be independent, but I have faced issues while using Helm with kebab-case. In my opinion snake_case is a safer option – Keratoplasty

Answer 2

Kubernetes using camelCase: https://kubernetes.io/docs/user-guide/jobs/

apiVersion, restartPolicy

CircleCI using snake_case: https://circleci.com/docs/1.0/configuration/

working_directory restore_cache, store_artifacts

Jenkins with dash-case: https://github.com/jenkinsci/yaml-project-plugin/blob/master/samples/google-cloud-storage/.jenkins.yaml

stapler-class

---

So it looks like projects and teams use their own conventions and there is no one definite standard.

Cowen

Adding: GitLab and Ansible both using snake_case: docs.gitlab.com/ee/ci/yaml github.com/ansible/ansible-examples/blob/master/lamp_simple/… – Alehouse

You are correct that there is no universal standard. I think it's important to point out the both CircleCI and GitLab are using a mix of snake_case and kebab-case. Maybe it was not the case at the time when the answer was first posted, but it is the case now. GitHub Actions (one of the newer yaml based ci services) uses kebab-case (at least for all major config options). – Reportorial

Answer 3

A less popular opinion derived from years of experience:

TL;DR

Obviously stick to the convention but IMHO follow the one that is established in your project's YML files and not the one that comes with the dependencies. I dare to say naming convention depends on too many factors to give a definitive answer or even try to describe a good practice other than "have some".

Full answer

Libraries might change over time which leads to multiple naming conventions in one config more often than any sane programmer would like - you can't do much about it unless you want to introduce (and later maintain) a whole new abstraction layer dedicated to just that: keeping the parameter naming convention pristine.

A one example of why you would want a different naming convention in your configs vs. configs that came with the dependencies is searchability, e.g. if all dependencies use a parameter named request_id, naming yours request-id or requestId will make it distinct and easily searchable while not hurting how descriptive the name is.

Also, it sometimes makes sense to have multiple parameters with the same name nested in different namespaces. In that case it might be justified to invent a whole new naming convention based on some existing ones, e.g.:

• order.request-id.format and
• notification.request-id.format

While it probably isn't necessary for your IDE to differentiate between the two (as it's able to index parameters within the namespace) you might consider doing so anyway as a courtesy for your peers - not only other developers who could use different IDEs but especially DevOps and admins who usually do use less specialized tools during maintenance, migrations and deployment.

Finally, another good point raised by one of my colleagues is that distinctive parameter names can be easily converted into a different convention with something as simple as one awk command. Doing so the other way around is obviously possible but by an order of magnitude more complicated which often spawns debates in the KISS advocates community about what it really means to "keep it simple stupid".

The conclusion is: do what's most sensible to you and your team.

Indiscernible