177

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:
    ...
3
  • 1
    That's actually dromedaryCase; as your spelling reveals, proper CamelCase also capitalizes the first word (resulting in two humps).
    – tripleee
    Commented Nov 29, 2023 at 7:04
  • 1
    @tripleee You're thinking of Pascal case. His use of camel case was correct. Commented Jun 13 at 14:36
  • @NicholasDavidson Thanks, that's not how I learned it but the sources I checked mainly seem to agree with you. Perhaps see also stackoverflow.com/questions/17326185/…
    – tripleee
    Commented Jun 13 at 15:25

3 Answers 3

140

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.

6
  • 41
    YAML is independent, so it does not obey anything.
    – Miraage
    Commented Sep 21, 2016 at 18:34
  • 10
    I agree with @Miraage. And, from a practical point of view, what if the "surrounding software" is written in multiple languages? Commented Jan 13, 2017 at 20:34
  • 3
    @RobWorsnop like he said it is independant from the software language. You can use the CASE that you like the most. Commented Dec 20, 2018 at 16:09
  • can a yaml name start with an underscore? like, _jobname__ more precisely, I need this one, __version__
    – Mohd
    Commented May 7, 2020 at 18:59
  • 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. Commented Jan 21, 2022 at 19:23
124

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.

2
  • 1
    Adding: GitLab and Ansible both using snake_case: docs.gitlab.com/ee/ci/yaml github.com/ansible/ansible-examples/blob/master/lamp_simple/… Commented Mar 20, 2019 at 21:22
  • 1
    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). Commented Jun 21, 2020 at 7:49
7

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 its 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", so do what's most sensible to you and your team.

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".

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.