mirror of
https://github.com/rendercv/rendercv.git
synced 2026-01-18 10:18:37 -05:00
142 lines
4.8 KiB
Markdown
142 lines
4.8 KiB
Markdown
---
|
|
toc_depth: 3
|
|
---
|
|
|
|
# JSON Schema
|
|
|
|
## The Problem
|
|
|
|
You may have encountered this before, even if you didn't realize it:
|
|
|
|
**VS Code settings** (`settings.json`):
|
|
```json
|
|
{
|
|
"editor.fontSize": 14,
|
|
"editor.tabSiz": 4 // ← Typo! VS Code highlights it red immediately
|
|
}
|
|
```
|
|
|
|
**GitHub Actions workflows** (`.github/workflows/test.yaml`):
|
|
```yaml
|
|
on:
|
|
push:
|
|
branchs: # ← Typo! Your editor underlines it, suggests "branches"
|
|
- main
|
|
```
|
|
|
|
**These files are completely different (VS Code settings, GitHub workflows). But you get autocomplete and validation in both.** How?
|
|
|
|
VS Code doesn't just "know" what's valid in `settings.json`. GitHub Actions workflows don't magically get autocomplete.
|
|
|
|
**Someone had to tell your editor:** "Here are all the valid fields, their types, and what they mean."
|
|
|
|
That "someone" is [**JSON Schema**](https://json-schema.org).
|
|
|
|
## What is JSON Schema?
|
|
|
|
JSON Schema is a **standard way to describe the structure of JSON/YAML documents**.
|
|
|
|
Think of it as a specification, a formal description of what's valid:
|
|
|
|
```json
|
|
{
|
|
"type": "object",
|
|
"properties": {
|
|
"name": {
|
|
"type": "string",
|
|
"description": "Your full name"
|
|
},
|
|
"age": {
|
|
"type": "integer",
|
|
"minimum": 0,
|
|
"description": "Your age in years"
|
|
},
|
|
"email": {
|
|
"type": "string",
|
|
"format": "email"
|
|
}
|
|
},
|
|
"required": ["name"]
|
|
}
|
|
```
|
|
|
|
This schema says:
|
|
|
|
- A valid document is an object
|
|
- It must have a `name` field (string, required)
|
|
- It can have an `age` field (non-negative integer, optional)
|
|
- It can have an `email` field (string matching email format, optional)
|
|
|
|
**Why does JSON Schema exist?**
|
|
|
|
Because JSON and YAML files are **everywhere**: configuration files, API requests/responses, CI/CD workflows, application settings, data files.
|
|
|
|
You could write documentation on how to write those JSON/YAML files: "The `name` field is required and must be a string. The `age` field is optional and must be a non-negative integer." But **documentation is for humans to read, not machines**.
|
|
|
|
JSON Schema is the **same information in machine-readable format** so editors can understand it.
|
|
|
|
Once your editor has a schema, it can provide autocomplete, catch typos, and show inline documentation as you type.
|
|
|
|
This is why:
|
|
|
|
- **Microsoft publishes a JSON Schema for VS Code settings:** your editor fetches it and provides autocomplete
|
|
- **GitHub publishes a JSON Schema for Actions workflows:** that's how you get field suggestions
|
|
- **Thousands of tools do the same:** Kubernetes, Docker, Terraform, ESLint, `package.json`, `tsconfig.json`, the list goes on
|
|
|
|
## RenderCV's JSON Schema
|
|
|
|
RenderCV has the same problem. Users write their CVs in YAML, and we want them to have a smooth editor experience with autocomplete, typo detection, and inline documentation.
|
|
|
|
**Solution:** Publish a JSON Schema for RenderCV YAML files.
|
|
|
|
|
|
|
|
That's why [`schema.json`](https://github.com/rendercv/rendercv/blob/main/schema.json) exists in the repository.
|
|
|
|
## How the Schema is Generated?
|
|
|
|
We don't write `schema.json` by hand. **It's automatically generated from Pydantic models.**
|
|
|
|
RenderCV's entire data structure is defined using Pydantic models (see [Understanding RenderCV](understanding_rendercv.md) for details). Pydantic has a built-in feature: `model_json_schema()`, which generates JSON Schema from your models.
|
|
|
|
Whenever data models change, run:
|
|
|
|
```bash
|
|
just update-schema
|
|
```
|
|
|
|
This runs [`scripts/update_schema.py`](https://github.com/rendercv/rendercv/blob/main/scripts/update_schema.py), which regenerates `schema.json`.
|
|
|
|
## How Editors Know to Use RenderCV's Schema?
|
|
|
|
There are two ways editors discover and use RenderCV's schema:
|
|
|
|
### 1. Manual Declaration
|
|
|
|
Add a special comment at the top of your YAML file:
|
|
|
|
```yaml
|
|
# yaml-language-server: $schema=https://raw.githubusercontent.com/rendercv/rendercv/refs/tags/v2.4/schema.json
|
|
|
|
cv:
|
|
name: John Doe
|
|
```
|
|
|
|
This tells the editor: "Use RenderCV's schema for this file." Note the version tag in the URL, which ensures you get the schema matching your RenderCV version.
|
|
|
|
**Requirements:** Your editor needs to support this. For VS Code, install the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml).
|
|
|
|
### 2. Schema Store (Automatic)
|
|
|
|
RenderCV's schema is listed in [SchemaStore](https://github.com/SchemaStore/schemastore), a central registry of schemas that most IDEs use.
|
|
|
|
In SchemaStore, RenderCV's schema is configured to automatically activate for files ending with `_CV.yaml`. This means:
|
|
|
|
- If your file is named `John_Doe_CV.yaml`
|
|
- And your editor uses SchemaStore (VS Code with YAML extension does)
|
|
- You get autocomplete automatically, no comment needed
|
|
|
|
## Learn More
|
|
|
|
See [Pydantic JSON Schema](https://docs.pydantic.dev/latest/concepts/json_schema/) for how Pydantic generates schemas from models.
|