Semantic Key Shortening

Semantic Key Shortening Protocol (JSON Payload Compression)

Overview

In automated extraction, log processing, and multi-agent communications, models frequently emit structured JSON objects with long, descriptive multi-word keys ("source_file_absolute_path", "target_destination_directory", "error_diagnostic_message").

In high-volume batch runs ($>500$ records), repeating 30-character descriptive keys on every JSON object consumes thousands of redundant tokens without adding any technical clarity.

The Semantic Key Shortening Protocol replaces verbose key names with standardized developer abbreviations (src, dst, err, req, res, fn, qty) - using client-side Pydantic and TypeScript aliases to expand them into full domain entities automatically.

Verbose Descriptive Keys vs. Semantic Short Keys

┌─────────────────────────────────────────────────────────────┐
│                 JSON Key Token Density                      │
│                                                             │
│  Verbose Descriptive Keys (145 Tokens for 2 Records):       │
│  [                                                          │
│    {                                                        │
│      "source_file_path": "src/auth.ts",                     │
│      "destination_file_path": "dist/auth.js",               │
│      "compilation_error_message": "Type mismatch",          │
│      "status_execution_code": 1                             │
│    }                                                        │
│  ]                                                          │
│  ↳ 45 tokens per record billed on verbose key strings       │
│                                                             │
│  Semantic Short Keys (42 Tokens - 71.0% Cut!):              │
│  [                                                          │
│    {"src":"src/auth.ts","dst":"dist/auth.js","err":"Type mismatch","code":1}│
│  ]                                                          │
│  ↳ 16 tokens per record, 100% semantic clarity for LLMs     │
└─────────────────────────────────────────────────────────────┘

The Standardized Abbreviation Dictionary

Use these universally recognized developer abbreviations in prompt schemas and tool definitions:

Production Python Pydantic Implementation (Field(alias=...))

Define data models with short wire aliases and rich internal variable names:

from pydantic import BaseModel, Field
from typing import List

class FileMutation(BaseModel):
    source_path: str = Field(alias="src")
    destination_path: str = Field(alias="dst")
    error_message: str = Field(alias="err", default="")
    status_code: int = Field(alias="code", default=0)

    class Config:
        populate_by_name = True

# Downstream client parses dense compact JSON automatically
raw_llm_json = '[{"src":"src/a.ts","dst":"dist/a.js","code":0}]'
mutations = [FileMutation.model_validate(item) for item in json.loads(raw_llm_json)]
print(mutations[0].source_path)  # Outputs: 'src/a.ts'

TypeScript Schema Aliases

export interface WireMutationPayload {
  src: string;
  dst: string;
  err?: string;
  code: number;
}

// Client-side mapper to rich domain model
export function fromWirePayload(wire: WireMutationPayload) {
  return {
    sourcePath: wire.src,
    destinationPath: wire.dst,
    errorMessage: wire.err,
    statusCode: wire.code,
  };
}

Benchmark Comparison

Processing 1,000 continuous integration build log entries:

Agent Operational Directive

MANDATORY: For high-volume structured outputs, log extractions, and multi-agent JSON payloads, agents must use standardized semantic short keys (src, dst, err, req, res, fn, ts). Let client-side Pydantic/TypeScript models expand wire aliases into rich domain properties.