Валидация метаданных

В контексте MDX метаданные представляют собой структурированную информацию, описывающую содержимое документа. Обычно они задаются в формате YAML или JSON в верхней части MDX-файла, внутри блока export const или frontmatter. Метаданные используются для организации документации, управления контентом и интеграции с системами рендеринга. Валидация метаданных необходима для обеспечения корректной работы приложения, предотвращения ошибок при рендеринге и поддержания консистентности данных.

Структура метаданных

Метаданные в MDX могут включать такие поля, как:

export const meta = {
  title: "Пример документа",
  description: "Краткое описание документа",
  date: "2026-03-23",
  tags: ["javascript", "mdx", "tutorial"],
  author: "Иван Иванов",
};

Ключевые моменты структуры:

  • title — строка, обязательное поле, задающее заголовок документа.
  • description — строка, краткое описание.
  • date — дата публикации в формате ISO (YYYY-MM-DD), обязательна для хронологической сортировки.
  • tags — массив строк, необязательное поле, используемое для фильтрации и поиска.
  • author — строка, необязательное поле, указывающее автора.

Причины валидации

Валидация метаданных решает следующие задачи:

  1. Предотвращение ошибок при сборке и рендеринге — некорректные типы данных или пропущенные обязательные поля могут вызвать сбои в приложении.
  2. Стандартизация контента — единый формат метаданных упрощает работу с контентом и интеграцию с CMS.
  3. Поддержка автоматизации — корректные метаданные позволяют автоматически генерировать индексы, таблицы содержимого и страницы категорий.

Инструменты валидации

В JavaScript-экосистеме применяются несколько подходов к проверке метаданных MDX:

  1. Ручная проверка — простой способ, но требует поддержания большого объема кода для каждой схемы данных.
function validateMeta(meta) {
  if (!meta.title || typeof meta.title !== "string") {
    throw new Error("Поле title обязательно и должно быть строкой");
  }
  if (!meta.date || !/^\d{4}-\d{2}-\d{2}$/.test(meta.date)) {
    throw new Error("Поле date обязательно и должно быть в формате YYYY-MM-DD");
  }
  if (meta.tags && !Array.isArray(meta.tags)) {
    throw new Error("Поле tags должно быть массивом строк");
  }
}
  1. Использование схем валидации — библиотеки zod, yup или joi позволяют описывать схему метаданных и автоматически проверять данные при импорте MDX.

Пример с zod:

import { z } from "zod";

const MetaSchema = z.object({
  title: z.string(),
  description: z.string().optional(),
  date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/),
  tags: z.array(z.string()).optional(),
  author: z.string().optional(),
});

function validateMeta(meta) {
  MetaSchema.parse(meta); // выбросит ошибку при несоответствии
}

Интеграция в MDX-сборку

При использовании инструментов сборки типа Next.js, Gatsby или VitePress, валидация метаданных может выполняться автоматически при импорте MDX-файлов:

import fs from "fs";
import path from "path";
import { MetaSchema } from "./metaSchema";
import matter from "gray-matter";

const mdxDir = path.join(process.cwd(), "content");
const files = fs.readdirSync(mdxDir);

files.forEach((file) => {
  const source = fs.readFileSync(path.join(mdxDir, file), "utf8");
  const { data } = matter(source);
  MetaSchema.parse(data);
});

В этом примере:

  • gray-matter извлекает метаданные из MDX-файла.
  • MetaSchema.parse проверяет корректность структуры и типов данных.

Расширенные подходы

  1. Валидация зависимостей между полями Иногда одно поле зависит от другого. Например, поле tags может быть обязательным, если документ помечен как “учебный материал”. В zod это реализуется через refine:
const MetaSchema = z.object({
  title: z.string(),
  type: z.enum(["tutorial", "reference"]),
  tags: z.array(z.string()).optional(),
}).refine((data) => data.type === "tutorial" ? data.tags?.length > 0 : true, {
  message: "Документы типа tutorial должны содержать хотя бы один тег",
});
  1. Валидация формата даты и времени Для более строгой проверки даты можно использовать библиотеку date-fns:
import { parseISO, isValid } from "date-fns";

function validateDate(date) {
  const parsed = parseISO(date);
  if (!isValid(parsed)) {
    throw new Error("Некорректная дата");
  }
}
  1. Автоматическое добавление дефолтных значений Если некоторые поля отсутствуют, можно задавать значения по умолчанию:
const defaultMeta = {
  description: "Описание отсутствует",
  tags: [],
  author: "Неизвестен",
};

function applyDefaults(meta) {
  return { ...defaultMeta, ...meta };
}

Практические рекомендации

  • Все обязательные поля должны иметь строгие типы и формат.
  • Необязательные поля следует определять с дефолтными значениями.
  • Валидацию стоит проводить на этапе сборки проекта, чтобы предотвратить ошибки на продакшене.
  • Использование схем (zod, yup, joi) повышает читаемость кода и упрощает поддержку.
  • Для больших проектов рекомендуется создавать отдельный модуль для метаданных с централизованной схемой валидации.

В результате внедрения валидации метаданных обеспечивается консистентность контента, предотвращаются ошибки при рендеринге MDX-документов и упрощается масштабирование документации.

Оглавление