Quick Summary
JSON and YAML are considered the go-to languages to structure data for most frontend developers. However, these two languages are often used interchangeably due to YAML being the subset of JSON. In this article, Christine will discuss instances where YAML is best suited over JSON.
When it comes to structuring data, JSON (JavaScript Object Notation) and its subset YAML (YAML Ain't Markup Language) are the languages developers often use to fulfill this purpose because they help make data easier for people to read. As a result, YAML and JSON are often used interchangeably, causing developers to use the former ineffectively in their projects. In this article, we will learn which and when certain features in YAML suit your project as opposed to JSON.
Comments provide invaluable insights and explanations within YAML, and would be ideal when implementing things like GitHub Actions such as this one:
name: Spellcheck
on:
push:
branches:
- main # Adjust this branch name if needed
pull_request:
types:
- opened
- synchronize
jobs:
spellcheck:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v4
- name: Install codespell
run: pip install codespell
- name: Run spellcheck
run: codespell --quiet-level=2 --check-filenames -- ./**/*.jsonFor context, a colleague and I implement this GitHub Action in a project we maintain to decrease the amount of spelling errors that we often see. We decided to implement the comment shown near branches: -main so that people who want to improve this action to change the project’s main branch name if updates are made. Without it, the action would not align as the project evolves. Comments are just the beginning—let's delve into other powerful YAML features that redefine data structuring.
Structuring data can sometimes get tedious, and with YAML, you can reuse the data blocks that you've created in your file. This can help your project’s codebase stay organized and secure. Here's an example:
# reference: https://github.com/hoho4190/issue-pr-labeler
name: PR Labeler
on:
pull_request_target:
types:
- opened
- reopened
jobs:
main:
runs-on: ubuntu-latest
permissions:
contents: read # to read configuration yml file
pull-requests: write # to add labels to pull requests
steps:
- name: Run PR Labeler
uses: hoho4190/issue-pr-labeler@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
config-file-name: labeler-config.yml
# disable-bot: true # this will prevent issues, PRs created by botsIn the snippet above, the GitHub Action relies on a separate labeler-config.yml file. When the maintainers and I were planning on how to implemented this action in our open source project, we decided to use this approach as opposed to hardcoding the labels and their definitions. We believed that the separate yml file makes it easier for people to use different labels for their contributions, thus making it easier for use to track the issues that their contributions address.
Now, let's uncover another instance where YAML is best suited for projects.
YAML's flexibility allows tailoring data representation to match project requirements precisely. This is especially helpful when working on your project's documentation as shown in the code snippet below:
---
id: connections
title: 'Grow your network with our connections feature!'
sidebar_label: 'Connections'
keywords:
- connections
---
## What are Connections?
Connections on OpenSauced serve as a way to build and nurture your professional network within the open source ecosystem. Imagine you're searching for experts in Artificial Intelligence using our "List" feature, and you come across several promising developers. What's next? With Connections, you can now send a request to connect, bringing these experts into your professional circle for easy communication and collaboration.The use of YAML frontmatter in the above example adds context on what the content is about and where users to find it on the doc’s website.
If you want to learn more about the features YAML offers, here are some resources you can check out:
- YAML vs. JSON: What is the difference?: This resource discusses the key differences between JSON and YAML features. I highly recommend reading this if you need other ways to YAML in your projects.
- Frontmatter: This is the official website for Frontmatter. They have a comprehensive guide on how to implement this language in documentation and I highly recommend using it as a reference if you need more ways to use YAML in your project's tutorials.
- YAML.com: The language's official website is a great resource if you need a reminder on how to use YAML in your projects.
Whether you decide to implement YAML or use JSON, I hope this article has showed you the power of YAML and given you some ideas on how to imple 3639 ment it in your own and other people's projects. Speaking of other projects, feel to check out LinksHub and share your ideas with us! We'd love to hear from you! 😄 Author Bio
Christine Belzie is an open source maintainer at LinksHub and OpenSauced. When she's not helping people start their open source journey, you can find Christine writing articles at freeCodeCamp.
Author Photo
Author Links