What is the canonical YAML naming style

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

Hyphenated?

- job-name:
    ...

lower_case_with_underscores?

- job_name:
    ...

CamelCase?

- jobName:
    ...

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.

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.

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.