YAML & JSON Schema For VS Code: Learnings Timeline Guide

by Alex Johnson 57 views

Are you looking to create a dynamic and organized learning timeline within your VS Code environment? This guide will walk you through the process of setting up a robust data infrastructure using YAML data files, JSON schemas, and VS Code configurations. By the end of this article, you'll understand how to create, validate, and load data for a learning timeline feature, ensuring a smooth and efficient development workflow.

Understanding the Need for a Learning Timeline

A learning timeline is an invaluable tool for developers and learners alike. It provides a structured overview of learning resources, projects, and milestones. By visualizing your learning journey, you can track progress, identify gaps, and stay motivated. In this context, we'll explore how to build a learning timeline feature using YAML for data storage and JSON schema for validation, all within the VS Code environment. This setup ensures data consistency, auto-completion, and type safety, making your development process more efficient.

Why YAML and JSON Schema?

  • YAML (YAML Ain't Markup Language): YAML is a human-readable data serialization format that is often used for configuration files and data storage. Its clean syntax and ease of use make it an excellent choice for managing structured data.
  • JSON Schema: JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. It provides a contract for your JSON data, ensuring that it adheres to a predefined structure and type constraints. This is crucial for maintaining data integrity and preventing runtime errors.

Using these technologies together in VS Code provides a powerful combination for managing and validating data, which can significantly enhance your development workflow.

Step 1: Creating the YAML Data File

At the heart of our learning timeline is the YAML data file. This file will store the information about your learning resources, projects, and milestones. Let's create a file named learnings.yaml within your project's data directory (packages/shared/src/data/).

Structuring the YAML File

The YAML file will consist of an array of learning items, each representing a specific resource or project. Each item will have several key-value pairs that describe it. Here’s an example structure:

- title: "How I Built the A/B Simulator"
  url: "/blog/how-i-built-the-ab-simulator"
  type: blog # blog | substack | doc | video
  project: ab-sim
  tags: [react, statistics, astro]
  date: 2025-11-15
  excerpt: "From idea to shipped product..."

Let’s break down each field:

  • title: The title of the learning resource or project.
  • url: The URL where the resource can be accessed.
  • type: The type of resource (e.g., blog, Substack article, documentation, video).
  • project: The project the resource is associated with.
  • tags: Keywords or topics related to the resource.
  • date: The date the resource was published or completed.
  • excerpt: A brief summary of the resource.

Populating the YAML File with Seed Entries

To get started, add a few seed entries to your learnings.yaml file. This will give you a tangible dataset to work with as you set up the rest of the infrastructure. Here are a couple of examples:

- title: "Introduction to React"
  url: "/docs/react-intro"
  type: doc
  project: react-fundamentals
  tags: [react, javascript]
  date: 2024-01-01
  excerpt: "A comprehensive introduction to React."

- title: "Building a RESTful API with Node.js"
  url: "/blog/nodejs-api"
  type: blog
  project: nodejs-api
  tags: [node.js, express, api]
  date: 2024-02-15
  excerpt: "Learn how to build a RESTful API using Node.js and Express."

Having these seed entries not only gives you data to work with but also helps you visualize how the data will be structured and used in your learning timeline feature.

Step 2: Defining the JSON Schema

The next step is to create a JSON schema that defines the structure and constraints of your learning items. This schema will ensure that your YAML data is valid and consistent. Create a file named learnings.schema.json in the same directory as your YAML file.

Structure of the JSON Schema

The JSON schema will define the properties of each learning item, their types, and any required fields. Here’s a basic structure for your schema:

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "The title of the learning resource or project"
      },
      "url": {
        "type": "string",
        "format": "url",
        "description": "The URL where the resource can be accessed"
      },
      "type": {
        "type": "string",
        "enum": ["blog", "substack", "doc", "video"],
        "description": "The type of resource"
      },
      "project": {
        "type": "string",
        "description": "The project the resource is associated with"
      },
      "tags": {
        "type": "array",
        "items": {
          "type": "string"
        },
        "description": "Keywords or topics related to the resource"
      },
      "date": {
        "type": "string",
        "format": "date",
        "description": "The date the resource was published or completed"
      },
      "excerpt": {
        "type": "string",
        "description": "A brief summary of the resource"
      }
    },
    "required": ["title", "url", "type", "project", "date", "excerpt"]
  }
}

Key Components of the Schema

  • type: Specifies that the schema is an array of objects.
  • items: Defines the schema for each item in the array.
  • properties: Lists the properties of each item (e.g., title, url, type).
  • type (within properties): Specifies the data type of each property (e.g., string, array).
  • enum: Defines an enumeration of allowed values for a property (e.g., the type property can only be one of blog, substack, doc, or video).
  • format: Specifies the format of a string (e.g., url for URLs, date for dates).
  • required: Lists the properties that are required for each item.

Validating Required Fields and Enums

This schema ensures that certain fields are always present (e.g., title, url, type, project, date, and excerpt) and that the type property only accepts predefined values. This validation is crucial for maintaining data integrity and consistency in your learning timeline.

Step 3: Configuring VS Code for Auto-Completion

One of the major benefits of using a JSON schema is the ability to enable auto-completion and validation within VS Code. This makes it easier to write and maintain your YAML data. To configure VS Code, you’ll need to update the .vscode/settings.json file in your project.

Linking the Schema to the YAML File

If you don’t have a .vscode directory or a settings.json file, create them in the root of your project. Then, add the following configuration to your settings.json file:

{
  "yaml.schemas": {
    "./packages/shared/src/data/learnings.schema.json": "packages/shared/src/data/learnings.yaml"
  }
}

This configuration tells VS Code to use the learnings.schema.json schema to validate the learnings.yaml file. Now, when you edit the YAML file, VS Code will provide auto-completion suggestions based on the schema and highlight any validation errors.

Verifying Auto-Completion

To verify that auto-completion is working, open your learnings.yaml file and start typing a new learning item. You should see suggestions for the properties defined in your schema, such as title, url, type, etc. Additionally, when you type the type property, you should see suggestions for the enum values (blog, substack, doc, video).

Benefits of VS Code Configuration

Configuring VS Code with a JSON schema provides several benefits:

  • Auto-completion: Speeds up development by suggesting valid properties and values.
  • Validation: Catches errors early by highlighting invalid data.
  • Consistency: Ensures that your data adheres to a predefined structure.

Step 4: Creating a TypeScript Loader

To use the data from your YAML file in your application, you’ll need to create a TypeScript loader. This loader will read the YAML file, parse it, and provide functions to access the learning items. Create a file named learnings.ts in your project's library directory (packages/shared/src/lib/).

Implementing the TypeScript Loader

First, you’ll need to install the js-yaml library, which is used to parse YAML files in JavaScript and TypeScript. You can install it using npm or yarn:

npm install js-yaml
# or
yarn add js-yaml

Then, add the following code to your learnings.ts file:

import * as yaml from 'js-yaml';
import * as fs from 'fs';
import * as path from 'path';

// Define the type for a learning item based on your schema
export interface LearningItem {
  title: string;
  url: string;
  type: 'blog' | 'substack' | 'doc' | 'video';
  project: string;
  tags: string[];
  date: string;
  excerpt: string;
}

const LEARNINGS_FILE_PATH = path.join(__dirname, '../data/learnings.yaml');

// Function to load and parse the YAML file
function loadLearnings(): LearningItem[] {
  try {
    const fileContents = fs.readFileSync(LEARNINGS_FILE_PATH, 'utf8');
    // fix type any
    const data = yaml.load(fileContents) as LearningItem[] || [];
    return data;
  } catch (e) {
    console.error("Error loading learnings data:", e);
    return [];
  }
}

let learningsCache: LearningItem[] | null = null;

function getLearningsFromCache(): LearningItem[] {
  if (!learningsCache) {
    learningsCache = loadLearnings();
  }
  return learningsCache;
}

// Function to get all learning items
export function getLearnings(): LearningItem[] {
  return getLearningsFromCache();
}

// Function to get learning items by project
export function getLearningsByProject(project: string): LearningItem[] {
  return getLearningsFromCache().filter(item => item.project === project);
}

Key Components of the Loader

  • Type Definition: The LearningItem interface defines the structure of a learning item, ensuring type safety in your code. This interface should match the structure defined in your JSON schema.
  • File Loading: The loadLearnings function reads the YAML file and parses it using js-yaml. It also includes error handling to gracefully handle cases where the file cannot be loaded or parsed.
  • Caching: The learningsCache variable and getLearningsFromCache function implement a caching mechanism. This ensures that the YAML file is only loaded and parsed once, improving performance.
  • Getter Functions: The getLearnings function returns all learning items, and the getLearningsByProject function filters items by project. These functions provide a clean and simple API for accessing your learning data.

Matching TypeScript Types to the Schema

It’s crucial that the TypeScript types defined in your loader (LearningItem interface) match the structure and types defined in your JSON schema. This ensures that your code is type-safe and that you catch any data inconsistencies at compile time.

Acceptance Criteria: Ensuring Everything Works

To ensure that everything is set up correctly, let’s review the acceptance criteria:

  • YAML File Created with Seed Entries: You should have a learnings.yaml file with 1-2 seed entries, as demonstrated in Step 1.
  • VS Code Auto-Complete: VS Code should show auto-completion suggestions for type and project properties when editing the YAML file, as configured in Step 3.
  • TypeScript Types Match Schema: The LearningItem interface in learnings.ts should accurately reflect the structure and types defined in learnings.schema.json, as discussed in Step 4.

By meeting these criteria, you can be confident that your data infrastructure is set up correctly and that you can start building your learning timeline feature.

Conclusion

Creating a robust data infrastructure for your learning timeline feature using YAML, JSON schema, and VS Code is a worthwhile investment. By following the steps outlined in this guide, you've learned how to create a YAML data file, define a JSON schema for validation, configure VS Code for auto-completion, and implement a TypeScript loader. This setup ensures data consistency, type safety, and an efficient development workflow. Now you can focus on building the user interface and features for your learning timeline, knowing that your data is well-structured and easily accessible.

For further reading on YAML and JSON Schema, check out the official documentation on the YAML website and JSON Schema website. These resources provide in-depth information and best practices for working with these technologies.