ChangeSpec 1.0 Specification

Abstract

ChangeSpec defines a standard event format for communicating software changes from producers (vendors, library maintainers, service operators) to consumers (developers, agents, compliance teams). A ChangeSpec event is a self-describing JSON object with a fixed set of required fields and a rich set of optional fields covering severity, affected version ranges, migration guidance, and source attribution.

This document specifies:

1. The core event structure and field semantics
2. The category taxonomy
3. The severity taxonomy
4. Vendor identifier format
5. Source attribution model
6. Signing and verification for publisher-verified events
7. Envelope format and CloudEvents compatibility
8. Transport bindings: HTTPS webhook, MCP, RSS/Atom, polling API
9. Extension field convention
10. Backward compatibility rules

Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

A conforming event is a JSON object that validates against the ChangeSpec JSON Schema (schema.json) included in this repository.

A conforming producer generates events that are conforming events.

A conforming consumer accepts conforming events and ignores unknown fields (including extension fields) without error.

1.Core Event Structure

A ChangeSpec event is a JSON object. All field names are lowercase with underscores.

1.1Required Fields

1.2Optional Fields

1.3Field Constraints

• source_url and migration_url, when present, MUST use the https:// scheme. Enforced by the JSON Schema pattern constraint.
• published_at MUST be a valid RFC 3339 datetime string.
• effective_date and sunset_date, when present, MUST be valid RFC 3339 full-date strings (YYYY-MM-DD).
• id MUST be unique across all events from a given producer.
• title MUST NOT contain newlines.
• summary MUST be plain text. Producers MUST NOT include markdown syntax, HTML, or other markup.

2.Minimal Conforming Event

The smallest valid ChangeSpec event:

{
  "specversion": "1.0",
  "id": "cs_01HXYZ1234ABCD",
  "vendor_id": "acme",
  "category": "informational",
  "severity": "informational",
  "title": "Documentation typo fix in authentication section",
  "summary": "Corrected a typo in the authentication section of the developer documentation. No behavior change.",
  "published_at": "2026-04-10T14:00:00Z",
  "source_type": "crawled"
}

3.Vendor Identifier Format

3.1Format Rules

A vendor_id MUST match the pattern:

vendor_id = [namespace ":"] slug
namespace = 1*( ALPHA / DIGIT )
slug      = 1*( ALPHA / DIGIT / "-" / "_" )

3.2Namespace Conventions

4.Category Taxonomy

The category field classifies what kind of change this event represents.

5.Severity Taxonomy

6.Source Attribution

7.Signing and Verification

Publisher-verified events MAY be signed using Ed25519. Implementers MUST also read Section 12 (Security Considerations) for the full threat model and implementation requirements.

7.1Why Ed25519

Ed25519 provides compact signatures (64 bytes), fast verification, deterministic nonce derivation (no weak-random risk), and is implemented in Go (crypto/ed25519), Node.js (crypto), and Python (cryptography). RSA is not recommended due to key size overhead and parameter confusion risks.

Implementations MUST use strict Ed25519 verification as defined in RFC 8032: reject signatures where scalar S is not in [0, ell), reject non-canonical R encodings, reject small-order or low-order public keys.

7.2Signature Object

{
  "signature": {
    "alg": "ed25519",
    "key_id": "stripe-2026-01",
    "value": "<base64url-encoded 64-byte signature>",
    "signed_fields": [
      "specversion", "id", "vendor_id", "category", "severity",
      "title", "summary", "published_at", "source_type",
      "signature.alg", "signature.key_id", "signature.signed_fields"
    ],
    "key_fingerprint": "<optional base64url SHA-256 fingerprint of public key>"
  }
}

7.3Signature Input Construction

Step 1 - Domain separator. Begin with the exact UTF-8 bytes: ChangeSpec-Signature-1.0\n (24 bytes). This prevents cross-protocol signature reuse.

Step 2 - Typed envelope. Append the JCS (RFC 8785) canonicalization of a JSON object containing alg, key_id, payload, signed_fields, and vendor_id. The payload contains the named fields from the event.

Step 3 - Sign. Sign the concatenation using Ed25519 in strict mode.

The signed_fields array MUST contain every required event field, all signature metadata, and all security-critical optional fields when present. Consumers MUST reject events where signed_fields omits any required field that is present in the event.

7.4Key Distribution

Vendors publish their Ed25519 public keys at:

https://{vendor-domain}/.well-known/changespec-keys.json

Key documents MUST be served over HTTPS with Cache-Control: max-age=3600, must-revalidate. Key valid_until MUST NOT exceed one year from valid_from.

7.5Verification Steps

1. Check that source_type is publisher_verified.
2. Retrieve the public key for (vendor_id, key_id) scoped to the event's vendor_id.
3. Check that key_id is not in the revoked_keys list.
4. Check that the current time is within the key's validity window (allow 300 seconds of clock skew).
5. Check that published_at is within the consumer's freshness window (default: 90 days past, 300 seconds future).
6. Check that signature.signed_fields includes all required fields.
7. Construct the signature input per Section 7.3.
8. Verify the Ed25519 signature in strict mode.
9. If key_fingerprint is present, verify it matches the resolved key.
10. Reject the event if any step fails.

8.Envelope Format

8.1Standalone Format

The default transport format is a standalone JSON object. The event fields are the top-level keys.

8.2CloudEvents Envelope

ChangeSpec events MAY be transported inside a CloudEvents 1.0 envelope. Mapping:

9.Transport Bindings

9.1HTTPS POST Webhook

Delivered as HTTP POST with Content-Type: application/json. The delivering platform SHOULD implement retry with exponential backoff for non-2xx responses. Webhook delivery signing SHOULD follow the Standard Webhooks specification.

9.2MCP (Model Context Protocol)

Events are returned by MCP tool calls as JSON objects in standalone format. Events returned by MCP tools MAY be truncated when context length is a concern; truncation MUST be indicated by setting _truncated: true in the returned object.

9.3RSS/Atom Feed

Events MAY be published as RSS 2.0 or Atom 1.0 feed items. The full ChangeSpec event SHOULD be embedded as a <changespec:event> extension element with namespace xmlns:changespec="https://changespec.com/ns/1.0".

9.4Polling API

Polling APIs MUST return events in a paginated envelope with events, next_cursor, and has_more fields. Consumers paginate by passing cursor=<next_cursor>.

10.Extension Fields

Extension fields MUST use the ext: prefix followed by a namespace and field name: ext:<namespace>.<fieldname>.

{
  "ext:compliance.osfi_b10": true,
  "ext:compliance.dora_article": "32",
  "ext:internal.ticket_id": "ENG-4521",
  "ext:risk.vendor_tier": 1
}

Conforming consumers MUST ignore unknown extension fields without error. Core spec fields MUST NOT use the ext: prefix.

11.Backward Compatibility Rules

Patch releases (1.0.1): Clarifications only. No field additions, removals, or semantic changes.

Minor releases (1.1, 1.2): May add optional fields. May extend enum values. Existing values MUST NOT be removed or redefined. A 1.0 consumer receiving a 1.1 event with an unknown category SHOULD treat it as informational.

Major releases (2.0): May change required fields or redefine semantics. Require a formal deprecation period of at least 12 months.

12.Security Considerations

ChangeSpec events flow from producers to consumers. Information carried in a ChangeSpec event can drive automated decisions including software updates, security patches, legal and regulatory workflows, and policy enforcement. A forged, tampered, or replayed event can therefore cause significant harm. This section describes the threats this specification considers.

The full security considerations are detailed in the source document at github.com/changespec/spec. Sections cover: threat model, event authenticity, signature canonicalization, Ed25519 strict verification, key distribution and trust bootstrap, key revocation, replay and freshness protection, transport security, URL field handling, input size and parser safety, injection and rendering, automated agent safety, CSRF and origin validation, extension field security, confidence score trust boundary, denial of service resistance, supply chain, logging and observability, and known limitations.

12.20 Known Limitations of Version 1.0

• No transparency log. Key distribution relies on TLS trust and key pinning. A signed key-transparency log is planned for v1.1.
• No signer-authorization chain. A cryptographic signer-authorization mechanism is planned for v1.1.
• No event retraction. A retraction mechanism is planned for v1.1.
• No producer sequence numbers. Ordering relies on published_at timestamps. Signed sequence numbers are planned for v1.1.
• Post-quantum readiness. Ed25519 is not post-quantum secure. A hybrid signature scheme is planned for v2.0.

Appendix A: Field Quick Reference

Required fields: specversion, id, vendor_id, category, severity, title, summary, published_at, source_type

Security fields: cve_id, cvss_score, cvss_vector, fixed_in_version

Version fields: affected_versions, fixed_in_version

Temporal fields: published_at, effective_date, sunset_date

Guidance fields: migration_hint, migration_url, action_required, recommended_reviewers

Attribution fields: source_url, source_type, confidence_score

Targeting fields: affected_systems, affected_sections, tags

Signing fields: signature

Appendix B: MIME Type

The MIME type for a ChangeSpec event document is:

application/vnd.changespec+json

When serving events over HTTP, producers SHOULD set Content-Type: application/vnd.changespec+json.

Appendix C: Normative References

• RFC 2119: Key words for use in RFCs to Indicate Requirement Levels
• RFC 3339: Date and Time on the Internet: Timestamps
• RFC 3986: Uniform Resource Identifier (URI): Generic Syntax
• RFC 8032: Edwards-Curve Digital Signature Algorithm (EdDSA)
• RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format
• RFC 8785: JSON Canonicalization Scheme (JCS)
• RFC 8996: Deprecating TLS 1.0 and TLS 1.1
• RFC 9110: HTTP Semantics
• BCP 195: Recommendations for Secure Use of TLS and DTLS
• JSON Schema draft 2020-12: json-schema.org/draft/2020-12
• CloudEvents 1.0: github.com/cloudevents/spec
• Semantic Versioning 2.0.0: semver.org
• Standard Webhooks: standardwebhooks.com
• CVE format: cve.org
• CVSS 3.1: first.org/cvss
• SLSA v1.0: slsa.dev

Appendix D: Changes from Draft to 1.0.0

The following security and conformance fixes were applied between the initial draft and the 1.0.0 release following a pre-launch security review.

Signature System Overhaul

SIG-01 - Canonicalization under-specified - FIXED. Section 7.3 now mandates JCS (RFC 8785) over a typed envelope.

SIG-02 - signed_fields self-reference vulnerability - FIXED. The signed_fields array is now included in the typed envelope's payload object. A mandatory minimum field set is defined.

SIG-03 - No domain separation - FIXED. Section 7.3 now requires the 24-byte domain separator ChangeSpec-Signature-1.0\n prepended to every signature input.

SIG-04 - No replay protection - FIXED. published_at is now a required member of the mandatory signed-field minimum. Section 12.7 defines mandatory freshness enforcement.

SIG-05 - No vendor_id to key_id binding - FIXED. vendor_id is now part of the typed envelope. Key resolution is scoped by (vendor_id, key_id).

SIG-06 - Trust bootstrap under-specified - PARTIALLY ADDRESSED. Three acceptable trust bootstrap mechanisms defined. Key pinning is formally available for v1.0; transparency log planned for v1.1.

Schema Hardening

GEN-01 - Schema divergence between implementations - FIXED. Go reference implementation now embeds canonical schema.json via //go:embed.

GEN-02 - URL scheme not restricted - FIXED. source_url and migration_url carry a pattern: "^https://" constraint in schema.json.

All 10 conformance gaps identified in the pre-launch audit are closed. See full changelog at github.com/changespec/spec.