Zmiana metadanych (.openspec.yaml)

Obsługiwane pola i reguły walidacji dla metadanych przechowywanych wraz z każdą zmianą.

Lokalizacja

Każda zmiana przechowuje swoje metadane w pliku openspec/changes/<change-name>/.openspec.yaml, obok swoich artefaktów. Tworzenie zmiany zapisuje plik z wypełnionymi polami schema oraz created.

Pola

Klucz	Typ	Wymagane	Efekt
schema	string	Tak	Schemat przepływu pracy, któremu ta zmiana podlega
created	string, YYYY-MM-DD	Nie	Rejestruje datę utworzenia zmiany
goal	string	Nie	Rejestruje cel, jaki stawia sobie zmiana
affected_areas	lista stringów	Nie	Rejestruje obszary, których zmiana ma dotyczyć
initiative	map: store i id	Nie	Rejestruje inicjatywę, do której należy ta zmiana
skip_specs	boolean	Nie	Deklaruje, że zmiana nie wprowadza żadnych różnic w specyfikacjach (spec deltas), więc walidacja akceptuje zero różnic
retire_capabilities	boolean	Nie	Autoryzuje archiwizację do wycofania możliwości (capability), którą ta zmiana opróżnia

schema

Schemat przepływu pracy, któremu ta zmiana podlega. Jest ustawiany w momencie tworzenia zmiany i ma pierwszeństwo przed konfiguracją projektu, dzięki czemu zmiana zachowuje swój schemat nawet jeśli openspec/config.yaml zostanie zmieniony później. Uruchom openspec schemas, aby wyświetlić dostępne nazwy schematów.

initiative

Inicjatywa, do której należy ta zmiana, jako identyfikator magazynu (store) i identyfikator inicjatywy (id), oba w formacie kebab-case:

initiative:
  store: platform-specs
  id: unify-billing

Klucze inne niż store i id są odrzucane. Żadne polecenie obecnie nie odczytuje tego powiązania.

skip_specs

Deklaruje, że zmiana celowo nie wprowadza żadnych różnic w specyfikacjach: jest to czysta refaktoryzacja, zmiana narzędziowa lub dokumentacji. Przy ustawionej tej opcji walidacja akceptuje zero różnic, a artefakty, które normalnie generowałyby pliki specyfikacji, są uznawane za kompletne. Ustawienie tej flagi przy istniejących plikach specyfikacji w katalogu specs/ powoduje błąd walidacji.

retire_capabilities

Autoryzuje archiwizację do wycofania możliwości (capability). Gdy usunięte różnice (REMOVED deltas) w tej zmianie usuwają ostatnie wymaganie, jakie posiada dana możliwość, archiwizacja usuwa główny plik specyfikacji tej możliwości zamiast zatrzymywać proces. Flaga istnieje, ponieważ usunięcie jest odwracalne tylko poprzez git, dlatego decyzja pozostaje po stronie autora.

Klucze rozszerzeń

Klucz najwyższego poziomu zaczynający się od małej litery x- należy do Ciebie, służąc do przechowywania danych przez inne narzędzia lub Twój zespół obok zmiany, takich jak identyfikator w systemie śledzenia błędów lub właściciel:

schema: spec-driven
x-tracker: SB-5497
x-jiraKey: ABC-1
x-owner:
  team: payments

• Nazwa: prefiks x- pisany małymi literami, po którym następuje co najmniej jeden znak, bez żadnych spacji. Po prefiksie dopuszczalna jest dowolna wielkość liter i pisownia, więc x-jiraKey oraz x-trackerID są poprawne. X-Tracker, sam x- oraz x- tracker są niepoprawne i zgłaszane jako nieznane klucze.
• Wartość: dowolna wartość YAML. OpenSpec nie odczytuje ani nie waliduje tych wartości, a ich obecność nie wpływa na działanie systemu.
• Zakres: tylko na poziomie najwyższym. Klucz x- umieszczony wewnątrz initiative jest nadal odrzucany, tak jak każdy inny klucz tam znajdujący się.
• Walidacja: klucze rozszerzeń nigdy nie są zgłaszane jako nieznane, więc openspec validate --strict przechodzi pomyślnie dla zmiany zawierającej te klucze.
• Archiwizacja: plik przenosi się wraz ze zmianą bez zmian, w tym z kluczami rozszerzeń.

Przykład

Wypełniony plik .openspec.yaml:

schema: spec-driven
created: 2026-08-14
goal: Add magic-link login to the API
affected_areas:
  - auth
  - api

Walidacja

Plik jest walidowany za każdym razem, gdy polecenie go zapisuje lub odczytuje. Zapis, który nie przejdzie walidacji, zgłasza błąd i nic nie zapisuje. Odczyt istniejącego pliku kończy się niepowodzeniem w przypadku nieprawidłowego formatu YAML, pola naruszającego swoją umowę (kontrakt) lub niedostępnej nazwy schematu. Brak pliku nie jest błędem, a zmiana jest traktowana jako posiadająca brak metadanych.

W przeciwieństwie do config.yaml, złe wartości nigdy nie są ignorowane z ostrzeżeniem. Błąd metadanych zatrzymuje działanie polecenia.

• Nieznane klucze najwyższego poziomu: OpenSpec je ignoruje. status, instructions, validate i archive informują, że nie mają one żadnego efektu. Wynik JSON zawiera to ostrzeżenie w swojej strukturalnej odpowiedzi. Klucze rozszerzeń nie są uznawane za nieznane i nigdy nie są zgłaszane.
• Ścisła walidacja: openspec validate --strict traktuje ostrzeżenie o nieznanym kluczu jako błąd. Zmiana, której jedynymi dodatkowymi kluczami są klucze rozszerzeń, przechodzi walidację.