suissAI

Posted on Feb 26

FullAgenticStack WhatsApp-first: RFC-WF-0029

#webdev #programming #opensource #rfc

RFC-WF-0029

Term Registry & Glossary Standard (TRGS)

Status: Draft Standard
Version: 1.0.0
Date: 20 Nov 2025
Category: Standards Track
Author: FullAgenticStack Initiative
Dependencies: RFC-WF-0028 (SICR), RFC-WF-0026 (SGRP), RFC-WF-0021 (SECR)
License: Open Specification (Public, Royalty-Free)

Abstract

This document specifies the Term Registry & Glossary Standard (TRGS) for the WhatsApp-first Specification. TRGS defines a canonical, machine-readable registry for terms, acronyms, and normative definitions used across RFCs, ensuring consistent semantics, preventing definition drift, and enabling tooling to validate references. TRGS standardizes term identifiers, definition formats, cross-references, and versioning rules, and provides a mechanism to link terms to RFC clauses and compliance controls.

Index Terms— glossary, terminology registry, controlled vocabulary, acronyms, definition drift, interoperability, specification tooling.

I. Introduction

Large specifications rot when definitions drift: “capability” means one thing in one RFC and another elsewhere. WhatsApp-first already spans multiple domains (commands, evidence, observability, recovery, policy, agents). TRGS centralizes vocabulary so:

RFCs can reference canonical term IDs instead of redefining repeatedly
tools can validate that terms are used consistently
translations can be managed cleanly (optional extension)

II. Scope

TRGS specifies:

A canonical term registry file format (JSON)
Term identifiers and naming rules
Required metadata per term and acronym
Rules for defining, deprecating, and superseding terms
Cross-references from terms to RFC clauses and controls
Compatibility and extension rules (SECR)

TRGS does not replace in-RFC short definitions; it defines the canonical source of truth.

III. Normative Language

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

IV. Definitions

Term Registry: A machine-readable catalog of definitions and acronyms.
Term ID: A stable identifier for a term used across RFCs.
Definition Drift: Divergence of meaning across documents or versions.

V. Design Goals

TRGS MUST ensure:

G1. Consistency: one canonical definition per term ID
G2. Stability: term IDs are permanent; definitions versioned
G3. Toolability: RFCs can reference term IDs; tools can validate
G4. Traceability: terms can link to RFC clauses and controls
G5. Extensibility: allow translations and domain-specific expansions

VI. Canonical Location and Discovery

A TRGS-compliant publication SHOULD provide:

/.well-known/wfs/terms.json

And WKD discovery SHOULD reference it under endpoints.terms_registry.url.

VII. Term Registry File Format (Normative)

A. Required Top-Level Fields

The registry MUST include:

trgs_version (SemVer of registry format)
generated_at
terms[]
acronyms[] (optional but recommended)

B. Term Entry Required Fields

Each term MUST include:

term_id (stable)
term (string)
definition (normative definition)
category (e.g., command, evidence, security, observability, recovery)
status (active|deprecated|obsoleted)
introduced_in (RFC id + version)
references[] (RFC clause pointers; optional but recommended)

C. Acronym Entry Required Fields

Each acronym MUST include:

acronym
expanded
definition (optional but recommended)
status
references[] (optional)

D. Example `terms.json`

{
  "trgs_version": "1.0.0",
  "generated_at": "2026-02-22T00:00:00Z",
  "terms": [
    {
      "term_id": "WFS.TERM.CAPABILITY",
      "term": "Capability",
      "definition": "Any functionality that produces value or mutates persistent system state, including administrative, recovery, and observability functions.",
      "category": "core",
      "status": "active",
      "introduced_in": { "rfc_id": "RFC-WF-0001", "version": "1.0.0" },
      "references": ["RFC-WF-0001#Terminology"]
    }
  ],
  "acronyms": [
    {
      "acronym": "CCP",
      "expanded": "Conversational Command Protocol",
      "definition": "Protocol defining command envelopes, confirmation, and execution semantics over WhatsApp.",
      "status": "active",
      "references": ["RFC-WF-0003"]
    }
  ]
}

VIII. Term Identifier Rules

A. Stability

term_id MUST be stable and MUST NOT be reused for different meanings.

B. Naming Convention

TRGS standardizes:

WFS.TERM.<UPPER_SNAKE> for terms
WFS.ACRONYM.<ACRONYM> for acronyms (optional)

C. RFC Usage

RFCs SHOULD reference term IDs when introducing or using core terms, e.g.:

“Capability (WFS.TERM.CAPABILITY)”

IX. Deprecation and Supersedence

A. Deprecation

Deprecated terms MUST include:

deprecated_since
replacement_term_id (if any)
deprecation rationale (optional)

B. Obsoleted

Obsoleted terms MUST NOT be used in new RFC text.

X. Compatibility and Extensions (SECR)

TRGS MUST follow SemVer:

MAJOR for breaking changes to required fields or enums
MINOR for adding terms/fields
PATCH for definition clarifications that do not change meaning materially

Extensions MAY be added under extensions or x_* fields.

Optional translation support MAY be added as an extension (e.g., i18n.pt_br.definition).

XI. Relationship to Controls and Audits

TRGS MAY link terms to controls in RCMC for clarity, e.g.:

term “Idempotency Key” links to controls WFS-I-001 etc.

This linkage is informational, not required for conformance.

XII. Security Considerations

A public glossary is generally safe, but it can reveal operational semantics. Implementations SHOULD keep only generic definitions public and avoid embedding sensitive internal examples. Terms registry integrity matters for tooling; high-assurance workflows MAY pin terms.json by hash.

XIII. Conclusion

TRGS prevents semantic drift by providing a canonical vocabulary for WhatsApp-first. With stable term IDs, versioned definitions, and machine-readable references, TRGS enables consistent documentation, reliable tooling, and cleaner ecosystem evolution.

References

[1] RFC-WF-0028, Specification Index & Canonical Registry (SICR).
[2] RFC-WF-0026, Specification Governance & RFC Process (SGRP).
[3] RFC-WF-0021, Schema Extensions & Compatibility Rules (SECR).

Concepts and Technologies

Controlled vocabulary, term registries, stable identifiers, acronym registries, definition drift prevention, SemVer for glossary evolution, machine-readable spec tooling, optional i18n extensions.

DEV Community