Поле description и метаданные

В экосистеме декларативных визуализаций Vega-Lite и низкоуровневого движка Vega поле description относится к метауровню описания графика и служит семантическим комментарием к спецификации.

Семантическая роль description

Поле description не влияет на вычисление данных, отрисовку геометрии или работу трансформаций. Его задача — фиксировать смысл визуализации в текстовой форме, которая может быть использована внешними системами:

  • экранными дикторами (screen readers)
  • системами доступности
  • инструментами документации
  • каталогами визуализаций
  • поисковыми индексами внутри дашбордов

В отличие от визуальных свойств (mark, encoding, transform), description не участвует в графе исполнения спецификации.

Расположение в структуре спецификации

В Vega-Lite поле description может появляться на верхнем уровне объекта спецификации:

{
  "description": "Распределение продаж по регионам за 2025 год",
  "data": { "url": "sales.csv" },
  "mark": "bar",
  "encoding": {
    "x": { "field": "region", "type": "nominal" },
    "y": { "field": "revenue", "type": "quantitative" }
  }
}

В Vega аналогичная концепция применяется как часть общего JSON-графа сцены:

{
  "description": "Линейный график временного ряда температуры",
  "data": [{ "name": "table" }],
  "marks": []
}

Метауровни описания: distinction между description и title

Хотя description и title часто используются совместно, их семантика различается:

  • title — визуально отображаемый заголовок графика
  • description — невизуальное текстовое описание смысла

Ключевое отличие заключается в том, что description может вообще не отображаться в интерфейсе, но при этом сохраняться в DOM или JSON-структуре для внешнего потребления.

Пример:

{
  "title": "Продажи по регионам",
  "description": "Гистограмма показывает суммарные продажи по регионам за 12 месяцев с агрегацией по сумме выручки"
}

Accessibility-ориентированное использование description

Одной из основных причин существования поля является поддержка доступности (accessibility). В сложных визуализациях, где графическое представление теряет семантическую полноту, description выступает как текстовый эквивалент.

Типичные сценарии:

  • описание тренда временного ряда
  • объяснение агрегаций
  • интерпретация многомерных графиков
  • пояснение фильтрации данных

Пример более насыщенного описания:

{
  "description": "Диаграмма показывает рост продаж с января по декабрь. Наблюдается устойчивый рост во втором квартале и спад в начале четвёртого квартала. Данные агрегированы по месяцам."
}

Поле description и жизненный цикл визуализации

На уровне рендеринга Vega/Vega-Lite спецификация проходит несколько этапов:

  1. парсинг JSON-структуры
  2. валидация схемы
  3. компиляция Vega-Lite → Vega (в случае Vega-Lite)
  4. построение runtime-графа
  5. отрисовка

description участвует только в первом этапе как метаданные и далее транслируется без изменений.

Важно, что компилятор Vega-Lite не модифицирует значение description и не использует его для оптимизации графа.

Интеграция с DOM и экспортом

При использовании рендеринга в браузере через SVG или Canvas поле description может быть связано с DOM-атрибутами:

  • aria-label
  • aria-description
  • внутренние metadata-узлы

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

Пример логической привязки:

<svg aria-label="Распределение продаж">
  <!-- графические элементы -->
</svg>

Метаданные в Vega и Vega-Lite

Помимо description, спецификации поддерживают более широкий набор метаполей:

name

Используется для идентификации компонента внутри сцены:

{
  "name": "sales_chart"
}

usermeta

Позволяет прикреплять произвольные данные:

{
  "usermeta": {
    "author": "data-team",
    "version": "1.3",
    "tags": ["finance", "dashboard"]
  }
}

description как часть метамодели

В отличие от usermeta, поле description стандартизировано и имеет ожидаемую семантику: человекочитаемое пояснение.

Использование в сложных композициях

В составных визуализациях Vega-Lite (hconcat, vconcat, facet, repeat) каждый вложенный блок может иметь собственное description.

Пример:

{
  "vconcat": [
    {
      "description": "Верхний график показывает продажи",
      "mark": "bar",
      "encoding": { }
    },
    {
      "description": "Нижний график показывает прибыль",
      "mark": "line",
      "encoding": { }
    }
  ]
}

Такое разделение особенно важно в системах аналитики, где один экран содержит несколько смысловых слоёв данных.

Поведение при компиляции Vega-Lite → Vega

При трансляции спецификации Vega-Lite в Vega:

  • description переносится без изменений
  • не участвует в вычислении dataflow
  • не влияет на transforms
  • не изменяет signals или scales

Компилятор рассматривает поле как пассивный атрибут узла сцены.

Версионирование и стабильность метаданных

Поле description считается стабильной частью API спецификации. Это означает:

  • его формат не зависит от версии рендерера
  • оно не изменяется при обновлениях схемы
  • сохраняется при сериализации/десериализации

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

Типичные ошибки использования

Подмена визуальной логики

Недопустимо использовать description как источник данных:

{
  "description": "sales > 1000"
}

Это нарушает разделение данных и метаданных.

Перегрузка семантикой

Чрезмерно длинные или многослойные описания ухудшают читаемость и теряют пользу для accessibility-инструментов.

Дублирование title

Когда description полностью повторяет title, метаинформация становится избыточной и теряет смысловую добавочную ценность.

Роль в документации и каталогизации визуализаций

В корпоративных системах аналитики description часто используется как:

  • текст для карточек визуализаций
  • аннотация в библиотеке графиков
  • описание при экспорте в PDF/PNG
  • источник для генерации отчётов

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

Оглавление