Версионирование и расширяемость стандарта .meb
Статус:
[x]готово — версия 3.0.0
1. Управляющий стандартом
Стандарт .meb является собственностью MEBsystem sp. z o.o., NIP 6312727689. Любые изменения структуры, семантики и правил валидации вносит исключительно MEBsystem sp. z o.o. Другие лица могут использовать стандарт без ограничений, но не могут публиковать модификации как версии стандарта .meb.
Сообщения об ошибках и предложения изменений принимаются через репозиторий стандарта.
2. Схема версионирования
Версия стандарта записывается в meta.version в формате semver MAJOR.MINOR.PATCH.
| Уровень | Когда меняется | Пример |
|---|---|---|
| MAJOR | Изменения, нарушающие обратную совместимость | 1.0.0 → 2.0.0 |
| MINOR | Новые поля, объекты или значения enum — с сохранением обратной совместимости | 1.0.0 → 1.1.0 |
| PATCH | Исправления документации, правки без влияния на структуру | 1.0.0 → 1.0.1 |
Что является breaking change (MAJOR)
Изменение требует увеличения MAJOR, если:
- удаляется обязательное поле
- изменяется тип существующего поля
- семантика существующего поля изменяется несовместимым образом
- добавляется новое обязательное поле
- изменяется смысл существующего значения enum
Что не является breaking change (MINOR)
- добавление нового необязательного поля
- добавление нового значения enum (см. §4)
- добавление нового объекта каталога
- изменение поля с обязательного на необязательное
PATCH
Изменения PATCH не влияют ни на структуру, ни на семантику файла. Реализациям не нужно реагировать на изменение номера PATCH.
3. Поведение реализации при неизвестной версии
Реализация сравнивает версию в meta.version с наивысшей поддерживаемой версией.
| Ситуация | Требуемое поведение |
|---|---|
| MAJOR файла > поддерживаемый MAJOR | ДОЛЖНА отклонить файл с ошибкой |
| MAJOR файла = поддерживаемый MAJOR, MINOR файла > поддерживаемый MINOR | ДОЛЖНА загрузить файл, игнорируя неизвестные поля; СЛЕДУЕТ уведомить пользователя |
| PATCH файла отличается от поддерживаемого | не имеет значения — файл загружается как обычно |
| MAJOR файла < поддерживаемый MAJOR | СЛЕДУЕТ загрузить файл (режим обратной совместимости) |
Сообщение об ошибке при отклонении из-за неизвестного MAJOR ДОЛЖНО содержать версию файла и версию, поддерживаемую реализацией.
4. Новые значения enum
Добавление нового значения в существующее поле enum является изменением MINOR — оно не требует увеличения MAJOR.
Реализация НЕ ДОЛЖНА возвращать критическую ошибку, встретив неизвестное значение enum. Рекомендуемое поведение:
- пропустить операцию, содержащую неизвестное значение
- записать в журнал предупреждение с именем поля и встреченным значением
- продолжить обработку остальных данных
Exhaustive matching по значениям enum — выбор разработчика реализации: стандарт не требует обработки всех значений, но требует graceful degradation при неизвестных значениях.
5. Политика устаревания
Поле или значение, помеченные как deprecated:
- Остаются в стандарте в течение ровно одной версии MAJOR
- Удаляются в следующей версии MAJOR
- Отмечаются в changelog с указанием версии, в которой они объявлены deprecated, и версии планируемого удаления
Реализации, встретившей deprecated поле, СЛЕДУЕТ записать предупреждение в журнал. Она НЕ ДОЛЖНА отклонять файл только из-за присутствия deprecated поля.
Deprecated поле никогда не становится обязательным.
6. Расширения вендоров (x_)
Общий принцип
Реализации могут добавлять в файл .meb собственные поля с префиксом x_. Поля x_ являются исключительно информационными — они служат для хранения метаданных, специфичных для конкретного программного обеспечения.
Допустимые применения
- внутренние ID из базы данных исходного программного обеспечения
- подсказки рендеринга (цвет отображения, видимость в просмотрщике)
- данные сеанса (последний редактировавшийся узел, уровень масштаба)
- технические комментарии, несущественные для производства
Безусловные запреты
Поля x_ НЕ ДОЛЖНЫ:
- дублировать или переопределять поля, определённые в стандарте
- изменять интерпретацию какого-либо стандартного поля
- содержать геометрические данные или производственные операции
- быть необходимыми для правильного чтения файла
Реализация, читающая файл, ДОЛЖНА быть в состоянии изготовить правильный шкаф, полностью игнорируя все поля x_.
Формат имени
x_{vendor}_{имя}Примеры правильных имён:
"x_systemex_project_db_id": "PRJ-00412",
"x_cabinetpro_last_edited_node": "node_007",
"x_acme_display_color": "#3a7bd5"В качестве префикса вендора следует использовать уникальный идентификатор программного обеспечения — это сводит к минимуму риск коллизий между независимыми реализациями.
Коллизии имён
Стандарт не ведёт реестр префиксов вендоров. При коллизии имён между двумя реализациями ответственность за её разрешение лежит на этих реализациях — стандарт не определяет механизма разрешения.
7. Обратная совместимость — правила для MEBsystem sp. z o.o.
При внесении изменений MINOR компания MEBsystem sp. z o.o. ДОЛЖНА:
- обеспечить, чтобы файл, соответствующий версии
N.x, оставался корректным в версииN.(x+1) - не изменять смысл существующих обязательных полей
- не изменять допустимые значения существующих enum (только добавлять)
При внесении изменений MAJOR компании MEBsystem sp. z o.o. СЛЕДУЕТ:
- опубликовать путь миграции, описывающий каждое breaking change
- поддерживать предыдущую версию MAJOR не менее 12 месяцев с момента публикации новой
- предоставить инструмент или инструкцию по конвертации файлов из старой версии в новую