specVersion

SpecVersion is a metadata field used in some data exchange formats to declare the version of the specification to which a payload or artifact conforms. It serves as a contract indicator, separate from the artifact's own release version, and allows processors to apply the correct validation rules and interpretation for the fields that follow.

In practice, specVersion is included as a string field in serialized messages or documents. The field name may vary by project, commonly specversion (lowercase v) in JSON-based specs, or specVersion in code-style schemas. The value should reference the version of the specification that defines the structure, semantics, and constraints of the payload.

Example: The CloudEvents specification uses a specversion field with the value '1.0' to indicate that the event follows CloudEvents 1.0 rules. Some internal APIs or tools may expose specVersion values such as '2.1' or '3.0' depending on the versioning scheme adopted.

Design and interoperability considerations: when introducing a specVersion field, ensure backward compatibility and clear migration paths. Validators should handle unknown versions gracefully and provide helpful errors. Documentation should map each supported specVersion to the applicable schema, validation rules, and behavior.