DEV Community

suissAI
suissAI

Posted on

FullAgenticStack WhatsApp-first: RFC-WF-0021

#agents #architecture #softwareengineering #systemdesign

RFC-WF-0021

Schema Extensions & Compatibility Rules (SECR)

Status: Draft Standard
Version: 1.0.0
Date: 20 Nov 2025
Category: Standards Track
Author: FullAgenticStack Initiative
Dependencies: RFC-WF-0005 (CRCD), RFC-WF-0006 (EAS), RFC-WF-0011 (CATS), RFC-WF-0013 (WKD), RFC-WF-0016 (RCMC)
License: Open Specification (Public, Royalty-Free)

Abstract

This document specifies Schema Extensions & Compatibility Rules (SECR) for WhatsApp-first systems. SECR defines normative rules for extending, versioning, and negotiating compatibility across machine-readable artifacts such as CRCD registries, EAS evidence artifacts, policy packs, and audit reports. SECR standardizes extension namespaces, forward/backward compatibility expectations, semantic versioning constraints, and discovery-based version negotiation via WKD—ensuring ecosystem tooling (CATS/RCMC) remains interoperable as schemas evolve.

Index Terms— schema evolution, compatibility, semantic versioning, extensions, JSON Schema, version negotiation, interoperability.

I. Introduction

WhatsApp-first relies on multiple structured artifacts (registries, evidence, policies, reports). Without strict compatibility rules, implementations will drift: tools fail to parse artifacts, audits become inconsistent, and evidence becomes unverifiable over time. SECR defines how these artifacts evolve safely:

  • extension points that do not break parsers
  • SemVer rules for schema changes
  • negotiation and discovery of supported versions
  • compatibility obligations for producers and consumers

II. Scope

SECR specifies:

  • Extension mechanism for JSON/YAML artifacts (namespacing, location, limits)
  • Compatibility rules for CRCD, EAS, policy packs, CATS reports, and discovery docs
  • SemVer constraints and what constitutes breaking changes
  • Version negotiation via WKD (/.well-known/wfs.json)
  • Deprecation and migration guidance requirements
  • Minimal consumer obligations (how strict tools must be)

SECR does not mandate a particular canonicalization method; it defines compatibility behavior.

III. Normative Language

MUST, MUST NOT, SHOULD, SHOULD NOT, MAY are normative.

IV. Definitions

Producer: A system component emitting an artifact (CRCD, EAS, etc.).
Consumer: A tool or component reading an artifact (CATS, auditors, dashboards).
Extension: Non-core fields added to an artifact while preserving core schema validity.
Breaking Change: A change that may cause a conforming consumer to fail or misinterpret.

V. General Compatibility Principles

A. Core vs Extension Separation

Each artifact type MUST define:

  • a core schema (normative fields)
  • permitted extension points (where extra fields may appear)

Consumers MUST parse the core schema and MUST ignore unknown extension fields unless explicitly configured otherwise.

B. Strictness Rule

  • Producers MUST NOT change semantics of existing core fields in a MINOR or PATCH update.
  • Consumers SHOULD be forward-compatible by ignoring unknown fields in extension points.
  • Consumers MUST fail if required core fields are missing or invalid.

C. Determinism Rule

If a consumer does not understand an extension, it MUST NOT alter core compliance decisions based on it.

VI. Extension Namespace Standard

A. x_ Extension Fields

SECR standardizes a single extension namespace format:

  • extension keys MUST start with x_

Example:

  • x_vendor
  • x_ai
  • x_internal

B. Extension Container (Preferred)

Artifacts SHOULD support a top-level extensions object:

{
  "extensions": {
    "x_vendor": { "...": "..." }
  }
}
Enter fullscreen mode Exit fullscreen mode

If both extensions and x_* top-level fields are used, producers MUST document precedence. Preferred approach is single container.

C. Collision Avoidance

Extension objects SHOULD include an origin identifier:

  • origin (e.g., org/repo name)
  • ext_version (SemVer)

VII. Artifact-Specific Rules

A. EAS Evidence Artifacts

  • Producers MUST preserve eas_version and core fields defined by EAS.
  • New optional core fields MAY be added in MINOR versions.
  • Changing required fields, enums that affect parsing, or lifecycle semantics is MAJOR.

Evidence consumers MUST:

  • validate the core
  • ignore unknown extension fields
  • preserve integrity fields and hash rules as specified by the EAS version

B. CRCD Registry

  • Adding commands/capabilities is MINOR.
  • Renaming command_name, changing required args, or changing intent semantics is MAJOR.
  • Deprecations MUST specify replacements where possible.

Consumers MUST:

  • treat unknown command fields as extensions
  • rely on declared registry_version for compatibility decisions

C. Policy Packs

  • Adding new selectors/policies is MINOR.
  • Changing default binding semantics or precedence is MAJOR.
  • Removing a policy referenced by CRCD without replacement is MAJOR.

D. CATS Reports

  • Tools MUST output a stable core format for results.
  • Adding extra metrics is MINOR.
  • Changing control ID semantics or result enums is MAJOR.

E. WKD Discovery Documents

  • Adding new endpoints is MINOR.
  • Changing endpoint meaning or removing required endpoints is MAJOR.
  • Discovery MUST declare supported versions (Section VIII).

VIII. Version Negotiation and Discovery (WKD)

A. Declaring Supported Versions

/.well-known/wfs.json MUST declare:

  • wfs_spec_version (overall)

  • per-artifact versions where relevant:

    • crcd.registry_version
    • eas.eas_version
    • cats.manifest_version and/or controls catalog version

B. Compatibility Claims

Discovery SHOULD include:

  • supported_versions arrays for key artifacts, enabling tools to select a compatible mode.

Example:

{
  "supported_versions": {
    "eas": ["1.0.0", "1.1.0"],
    "crcd": ["1.2.0"]
  }
}
Enter fullscreen mode Exit fullscreen mode

C. Negotiation Strategy (Normative)

If a consumer does not support the declared version:

  • it MUST fail safely and report incompatibility, OR
  • it MAY request a compatible version if the endpoint supports it (e.g., ?version=), if declared.

Silent misinterpretation is prohibited.

IX. SemVer Rules (Normative)

A. MAJOR

Breaking changes, including:

  • removal or renaming of required fields
  • meaning changes to existing core fields
  • changes to enums used in compliance decisions
  • changes to hashing/canonicalization assumptions affecting integrity verification

B. MINOR

Backward-compatible additions:

  • new optional fields
  • new extension points
  • new controls/scenarios (if existing remain valid)

C. PATCH

Bugfixes and clarifications:

  • descriptions, documentation, examples
  • tightening constraints ONLY if it does not break valid producers

X. Deprecation and Migration Requirements

When a field/enum/endpoint is deprecated:

  • producers MUST document deprecated_since
  • producers SHOULD provide a replacement field or mapping guidance
  • consumers SHOULD warn but continue to function during a deprecation window

XI. Conformance Requirements

An implementation is SECR-compliant if it:

  1. Uses x_* namespaced extensions and/or extensions container consistently
  2. Versions artifacts with SemVer and follows MAJOR/MINOR/PATCH rules
  3. Declares supported versions in WKD discovery
  4. Ensures consumers can safely ignore unknown extensions
  5. Avoids silent downgrade/misinterpretation when versions mismatch

XII. Relationship to Other RFCs

  • CRCD (0005): schema evolution for registry artifacts
  • EAS (0006): schema evolution for evidence artifacts
  • CATS (0011): audit report compatibility
  • WKD (0013): discovery and version negotiation
  • RCMC (0016): stable control IDs and versioned control semantics

XIII. Security Considerations

Extensions can be abused to smuggle sensitive or misleading data. Implementations MUST apply redaction and access control policies consistently to both core and extensions. Tooling MUST avoid interpreting unknown fields as authoritative for security/compliance decisions.

XIV. Conclusion

SECR provides the compatibility contract that keeps the WhatsApp-first ecosystem stable as it evolves. By standardizing extension namespaces, SemVer rules, and discovery-based version negotiation, SECR prevents schema drift from collapsing interoperability, audits, and evidence verification.

References

[1] RFC-WF-0005, Command Registry & Capability Declaration (CRCD).
[2] RFC-WF-0006, Evidence Artifact Schema (EAS).
[3] RFC-WF-0011, Compliance Audit Toolkit Spec (CATS).
[4] RFC-WF-0013, Well-Known Discovery & Interop Endpoints (WKD).
[5] RFC-WF-0016, Reference Compliance Matrix & Control IDs (RCMC).

Concepts and Technologies

Schema evolution, extension namespaces (x_*), forward/backward compatibility, SemVer constraints, version negotiation, discovery documents, deprecation windows, tool interoperability rules.

Top comments (0)