Wersjonowanie i rozszerzalność standardu .meb
Status:
[x]gotowe — wersja 3.0.0
1. Zarządca standardu
Standard .meb jest własnością MEBsystem sp. z o.o., NIP 6312727689. Wszelkie zmiany struktury, semantyki i reguł walidacji wprowadza wyłącznie MEBsystem sp. z o.o. Inne podmioty mogą używać standardu bez ograniczeń, ale nie mogą publikować modyfikacji jako wersji standardu .meb.
Zgłoszenia błędów i propozycje zmian przyjmowane są przez repozytorium standardu.
2. Schemat wersjonowania
Wersja standardu zapisywana jest w meta.version jako semver MAJOR.MINOR.PATCH.
| Poziom | Kiedy się zmienia | Przykład |
|---|---|---|
| MAJOR | Zmiany łamiące wsteczną kompatybilność | 1.0.0 → 2.0.0 |
| MINOR | Nowe pola, obiekty lub wartości enum — wstecznie kompatybilne | 1.0.0 → 1.1.0 |
| PATCH | Poprawki dokumentacji, korekty bez wpływu na strukturę | 1.0.0 → 1.0.1 |
Co jest breaking change (MAJOR)
Zmiana wymaga inkrementacji MAJOR gdy:
- usunięte zostaje pole wymagane
- zmieniony zostaje typ istniejącego pola
- zmieniona zostaje semantyka istniejącego pola w sposób niekompatybilny
- dodawane jest nowe pole wymagane
- zmienione zostaje znaczenie istniejącej wartości enum
Co nie jest breaking change (MINOR)
- dodanie nowego pola opcjonalnego
- dodanie nowej wartości enum (patrz §4)
- dodanie nowego obiektu katalogowego
- zmiana pola z wymaganego na opcjonalne
PATCH
Zmiany PATCH nie wpływają na strukturę ani semantykę pliku. Implementacje nie muszą reagować na zmianę numeru PATCH.
3. Zachowanie implementacji przy nieznanej wersji
Implementacja porównuje wersję w meta.version z najwyższą obsługiwaną wersją.
| Sytuacja | Wymagane zachowanie |
|---|---|
| MAJOR pliku > MAJOR obsługiwany | MUSI odrzucić plik z błędem |
| MAJOR pliku = MAJOR obsługiwany, MINOR pliku > MINOR obsługiwany | MUSI załadować plik, ignorując nieznane pola; POWINNA poinformować użytkownika |
| PATCH pliku różny od obsługiwanego | bez znaczenia — ładuje normalnie |
| MAJOR pliku < MAJOR obsługiwany | POWINNA załadować plik (tryb kompatybilności wstecznej) |
Komunikat błędu przy odrzuceniu z powodu nieznanego MAJOR MUSI zawierać wersję pliku i wersję obsługiwaną przez implementację.
4. Nowe wartości enum
Dodanie nowej wartości do istniejącego pola enum jest zmianą MINOR — nie wymaga inkrementacji MAJOR.
Implementacja MUSI NIE zwracać błędu krytycznego przy napotkaniu nieznanej wartości enum. Zalecane zachowanie:
- pominąć operację zawierającą nieznaną wartość
- zalogować ostrzeżenie z nazwą pola i napotkaną wartością
- kontynuować przetwarzanie pozostałych danych
Exhaustive matching na wartościach enum jest wyborem implementatora — standard nie wymaga obsługi wszystkich wartości, wymaga natomiast graceful degradation przy wartościach nieznanych.
5. Polityka deprecacji
Pole lub wartość oznaczone jako deprecated:
- Pozostają w standardzie przez dokładnie jedną wersję MAJOR
- Są usuwane w kolejnej wersji MAJOR
- Są odnotowane w changelogu z wersją wprowadzenia deprecacji i wersją planowanego usunięcia
Implementacja napotykająca deprecated pole POWINNA zalogować ostrzeżenie. MUSI NIE odrzucać pliku wyłącznie z powodu obecności deprecated pola.
Deprecated pole nigdy nie staje się wymaganym.
6. Rozszerzenia vendorów (x_)
Zasada ogólna
Implementacje mogą dodawać do pliku .meb własne pola z prefiksem x_. Pola x_ są wyłącznie informacyjne — służą do przechowywania metadanych specyficznych dla danego oprogramowania.
Dozwolone użycia
- wewnętrzne ID z bazy danych oprogramowania źródłowego
- hinty renderowania (kolor wyświetlania, widoczność w viewerze)
- dane sesji (ostatnio edytowany węzeł, poziom zoom)
- komentarze techniczne nieistotne dla produkcji
Zakazy bezwzględne
Pola x_ MUSZĄ NIE:
- powielać ani nadpisywać pól zdefiniowanych w standardzie
- zmieniać interpretacji jakiegokolwiek pola standardowego
- zawierać danych geometrycznych ani operacji produkcyjnych
- być wymagane do poprawnego odczytu pliku
Implementacja która czyta plik MUSI być w stanie wyprodukować poprawną szafkę ignorując wszystkie pola x_ w całości.
Format nazwy
x_{vendor}_{nazwa}Przykłady poprawnych nazw:
"x_systemex_project_db_id": "PRJ-00412",
"x_cabinetpro_last_edited_node": "node_007",
"x_acme_display_color": "#3a7bd5"Prefiks vendora powinien być unikalnym identyfikatorem oprogramowania — minimalizuje ryzyko kolizji między niezależnymi implementacjami.
Kolizje nazw
Standard nie prowadzi rejestru prefiksów vendorów. Przy kolizji nazw między dwoma implementacjami odpowiedzialność za rozwiązanie leży po stronie tych implementacji — standard nie definiuje mechanizmu rozstrzygania.
7. Kompatybilność wsteczna — zasady dla MEBsystem sp. z o.o.
Przy wprowadzaniu zmian MINOR MEBsystem sp. z o.o. MUSI:
- zapewnić, że plik zgodny z wersją
N.xpozostaje poprawny w wersjiN.(x+1) - nie zmieniać znaczenia istniejących pól wymaganych
- nie zmieniać dozwolonych wartości istniejących enum (tylko dodawać)
Przy wprowadzaniu zmian MAJOR MEBsystem sp. z o.o. POWINIEN:
- opublikować ścieżkę migracji opisującą każdą breaking change
- utrzymać wsparcie dla poprzedniej wersji MAJOR przez co najmniej 12 miesięcy od publikacji nowej
- dostarczyć narzędzie lub instrukcję konwersji plików ze starej wersji do nowej