Is it .yaml or .yml?

Question

According to yaml.org, the official file extension is .yaml.

Quote:

Is there an official extension for YAML files?

Please use ".yaml" when possible.

However there seems to be a disagreement on the internet on which extension to use. If you look up examples on the web, many of them use the unsanctioned .yml extension.

Searching Google returns nearly 3 times as many results for the shorter one.

---

49,100

---

15,400

---

So which am I supposed to use? The proper 4 letter extension suggested by the creator, or the 3 letter extension found in the wild west of the internet?

Answer 1

Sadly there is no consensus on this and there will be none at least in years to come.

SHORT ANSWER

Use what the software you are working with takes as input. For your own projects you can have your preference of course and you can stick to it.

---

Note different operating systems handle a file extension in a different way. On some having config.yml and config.yaml next to each other is perfectly fine, on others - not.

I've recently encountered a funny situation, which brought me to this discussion here (one of many :D). This story will reveal that statements such as "YAML/YML is the official one because Google search yields more results for YAML/YML" are not only invalid (mostly because of reality and the fact that searching for YAML yields results that may not talk about the file extension at all but rather talk about the language itself!) but dangerous and can waste a developer's precious time over and over again.

---

THE STORY

I was setting up a CICD pipeline with a deployment stage that uses Helm to pull the image I was creating at an earlier stage, deploy it to my Kubernetes cluster and create a service for it. All of this was just to explore how Kubernetes works and what CICD is. I created an empty repo and immediately went to the Web Editor in GitLab for editing the CICD config file. If none is present (the case when you create an empty repo) it offers you a button such as this one:

What this does is create an example .gitlab-ci.yml file in the root of your repo, which is where the CICD mechanism of GitLab looks for its configuration.

Fast forward a couple of days later and I was setting up Helm. Without thinking I went on creating all Helm chart-related files (Chart, values, deployment template and so on).

Running the pipeline (a perfectly valid and simple one) was exhibiting strange behaviour. I was getting an error that Charts.yaml cannot be found. I checked. It was there. It took me some time to figure out that it's YAML and not YML that Helm was asking for. Another try after renaming the file yielded strange error that a value of some sort cannot be found. Funny enough it was the first value I was referencing in my deployment file. And it was because it was YML and not YAML.

Ok, so in order to keep things consistent (I mean who likes having a bunch of files for the same language with different file extensions in the same repo?) I decide to rename .gitlab-ci.yml to .gitlab-ci.yaml. This was the last commit I made that evening. The next day I called a colleague and told him that I've set up something that might be useful to him as well and if he would like to check it out. Meeting was arranged and I proceeded doing something else.

During the meeting I told him that I will just commit something (sharing my screen) in the Flask app I've created as a lab rat (a Hello world app basically) and he can connect to my cluster on IP and port XYZ to see the changes. We were both excited. I committed, pushed my changes to the remote repo and waited...And waited...At some point my colleague asked if he missed something. I said no, you should be able to see the changes already. But there were none. Commit was there (both local and remote history showed it) but the remote repo's pipeline was not being triggered, no jobs being executed and no upgrade of the image and deployment. The meeting was over.

Took me half an hour to figure the problem. GitLab does not like .yaml for the .gitlab-ci file. It recognizes only .yml. I figured this out by going to the Web editor and trying to edit the pipeline there just to be greeted by the button I've posted above. I then decided to click on it and just copy-paste my old pipeline. It worked. But now I had .gitlab-ci.yml and .gitlab-ci.yaml in the root of the repo. Only the .yml version was working of course.

---

I visited several discussions like this both on GitLab and Helm to see if it's just me who is annoyed by this behaviour. One thing that was pointed out in the Helm GitHub issue regarding this was that if you have one YAML and one YML file, which one should have the higher priority? I posted this on GitLab (same issue there of course :D) and pointed out that then this would open a whole new debate, where people would argue whether YAML or YML should be used if both present, thus creating a chicken-and-egg problem.

Answer 2

The nature and even existence of file extensions is platform-dependent (some obscure platforms don't even have them, remember) -- in other systems they're only conventional (UNIX and its ilk), while in still others they have definite semantics and in some cases specific limits on length or character content (Windows, etc.).

Since the maintainers have asked that you use ".yaml", that's as close to an "official" ruling as you can get, but the habit of 8.3 is hard to get out of (and, appallingly, still occasionally relevant in 2013).

Answer 3

.yaml is apparently the official extension, because some applications fail when using .yml. On the other hand I am not familiar with any applications which use YAML code, but fail with a .yaml extension.

I just stumbled across this, as I was used to writing .yml in Ansible and Docker Compose. Out of habit I used .yml when writing Netplan files which failed silently. I finally figured out my mistake. The author of a popular Ansible Galaxy role for Netplan makes the same assumption in his code:

- name: Capturing Existing Configurations
  find:
    paths: /etc/netplan
    patterns: "*.yml,*.yaml"
  register: _netplan_configs

Yet any files with a .yml extension get ignored by Netplan in the same way as files with a .bak extension. As Netplan is very quiet, and gives no feedback whatsoever on success, even with netplan apply --debug, a config such as 01-netcfg.yml will fail silently without any meaningful feedback.

Answer 4

EDIT:

So which am I supposed to use? The proper 4 letter extension suggested by the creator, or the 3 letter extension found in the wild west of the internet?

This question could be:

1. A request for advice; or

2. A natural expression of that particular emotion which is experienced, while one is observing that some official recommendation is being disregarded—prominently, or even predominantly.

People differ in their predilection for following:

1. Official advice; or

2. The preponderance of practice.

Of course, I am unlikely to influence you, regarding which of these two paths you prefer to take!

In what follows (and, in the spirit of science), I merely make an hypothesis, about what (merely as a matter of fact) led the majority of people to use the 3-letter extension. And, I focus on efficient causes.

By this, I do not intend moral exhortation. As you may recall, the fact that something is, does not imply that it should be.

Whatever your personal inclination, be it to follow one path or the other, I do not object.

(End of edit.)

The suggestion, that this preference (in real life usage) was caused by a 8.3 character DOS-ish limitation, IMO is a red herring (erroneous and misleading).

As of August, 2016, the Google search counts for YML and YAML were approximately 6,000,000 and 4,100,000 (to two digits of precision). Furthermore, the "YAML" count was unfairly high because it included mention of the language by name, beyond its use as an extension.

As of July, 2018, the Google's search counts for YML and YAML were approximately 8,100,000 and 4,100,000 (again, to two digits of precision). So, in the last two years, YML has essentially doubled in popularity, but YAML has stayed the same.

Another cultural measure is websites which attempt to explain file extensions. For example, on the FilExt website (as of July, 2018), the page for YAML results in: "Ooops! The FILEXT.com database does not have any information on file extension .YAML."

Whereas, it has an entry for YML, which gives: "YAML...uses a text file and organizes it into a format which is Human-readable. 'database.yml' is a typical example when YAML is used by Ruby on Rails to connect to a database."

As of November, 2014, Wikipedia's article on extension YML still stated that ".yml" is "the file extension for the YAML file format" (emphasis added). Its YAML article lists both extensions, without expressing a preference.

The extension ".yml" is sufficiently clear, is more brief (thus easier to type and recognize), and is much more common.

Of course, both of these extensions could be viewed as abbreviations of a long, possible extension, ".yamlaintmarkuplanguage". But programmers (and users) don't want to type all of that!

Instead, we programmers (and users) want to type as little as possible, and still yet be unambiguous and clear. And we want to see what kind of file it is, as quickly as possible, without reading a longer word. Typing just how many characters accomplishes both of these goals? Isn't the answer three (3)? In other words, YML?

Wikipedia's Category:Filename_extensions page lists entries for .a, .o and .Z. Somehow, it missed .c and .h (used by the C language). These example single-letter extensions help us to see that extensions should be as long as necessary, but no longer (to half-quote Albert Einstein).

Instead, notice that, in general, few extensions start with "Y". Commonly, on the other hand, the letter X is used for a great variety of meanings including "cross," "extensible," "extreme," "variable," etc. (e.g. in XML). So starting with "Y" already conveys much information (in terms of information theory), whereas starting with "X" does not.

Linguistically speaking, therefore, the acronym "XML" has (in a way) only two informative letters ("M" and "L"). "YML", instead, has three informative letters ("M", "L" and "Y"). Indeed, the existing set of acronyms beginning with Y seems extremely small. By implication, this is why a four letter YAML file extension feels greatly overspecified.

Perhaps this is why we see in practice that the "linguistic" pressure (in natural use) to lengthen the abbreviation in question to four (4) characters is weak, and the "linguistic" pressure to shorten this abbreviation to three (3) characters is strong.

Purely as a result, probably, of these factors (and not as an official endorsement), I would note that the YAML.org website's latest news item (from November, 2011) is all about a project written in JavaScript, JS-YAML, which, itself, internally prefers to use the extension ".yml".

The above-mentioned factors may have been the main ones; nevertheless, all the factors (known or unknown) have resulted in the abbreviated, three (3) character extension becoming the one in predominant use for YAML—despite the inventors' preference.

".YML" seems to be the de facto standard. Yet the same inventors were perceptive and correct, about the world's need for a human-readable data language. And we should thank them for providing it.

Answer 5

After reading a bunch of people's comments online about this, my first reaction was that this is basically one of those really unimportant debates. However, my initial interest was to find out the right format so I could be consistent with my file naming practice.

Long story short, the creator of YAML are saying .yaml, but personally I keep doing .yml. That just makes more sense to me. So I went on the journey to find affirmation and soon enough, I realise that docker uses .yml everywhere. I've been writing docker-compose.yml files all this time, while you keep seeing in kubernetes' docs kubectl apply -f *.yaml...

So, in conclusion, both formats are obviously accepted and if you are on the other end, (ie: writing systems that receive a YAML file as input) you should allow for both. That seems like another snake case versus camel case thingy...