XTAG: format specification

The XTAG: format is XTagger’s portable sharing format. It encodes a full tag collection as a single string safe to paste into any plaintext medium — a message, a tweet, a forum post.

---

Structure

XTAG:<base64url-encoded JSON>

The prefix XTAG: is literal. The payload is a Base64URL-encoded (no padding) JSON object conforming to the ExportManifest schema below.

---

ExportManifest schema

interface ExportManifest {
  schemaVersion: number;       // Must be 1 (current)
  platform:      string;       // "x.com"
  exportedAt:    string;       // ISO 8601, e.g. "2025-01-15T12:00:00Z"
  exportedBy?:   string;       // Optional author handle
  description?:  string;       // Optional collection description
  checksum:      string;       // 64-char hex SHA-256 of entries JSON
  entries:       Record<string, Tag[]>;  // Key: "platform:username"
}

Tag schema

interface Tag {
  id:          string;   // UUID v7 recommended; any UUID accepted
  name:        string;   // 1–50 characters, trimmed
  colorIndex:  number;   // 0–15 (base palette); 16–31 (extended)
  notes?:      string;   // Optional, max 500 characters
  source:      TagSource;
  createdAt:   number;   // UTC milliseconds
  updatedAt:   number;   // UTC milliseconds
  deletedAt?:  number;   // Present = soft-deleted
}

type TagSource =
  | { type: 'local' }
  | { type: 'imported'; origin: string; importedAt: number };

---

Entry key format

Keys in entries follow the pattern platform:username in lowercase:

"x.com:elonmusk"   → tags for @elonmusk on X.com
"x.com:alice_dev"  → tags for @alice_dev on X.com

---

Checksum

The checksum field is a SHA-256 hex digest of the JSON-serialised entries object (keys sorted, no extra whitespace):

const checksum = sha256(JSON.stringify(entries, Object.keys(entries).sort()));

XTagger verifies this on every import and rejects manifests with a mismatched checksum.

---

Colour index reference

Index	Colour	Hex
0	Coral	#e05a4e
1	Amber	#f59e0b
2	Emerald	#22bb66
3	Sky	#1d9bf0
4	Violet	#8b5cf6
5	Rose	#ec4899
6	Teal	#14b8a6
7	Orange	#f97316
8–15	Extended palette	—

---

Minimal valid example

{
  "schemaVersion": 1,
  "platform": "x.com",
  "exportedAt": "2025-01-15T12:00:00Z",
  "checksum": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "entries": {
    "x.com:alice": [
      {
        "id": "018e1234-5678-7abc-9def-000000000001",
        "name": "journalist",
        "colorIndex": 3,
        "source": { "type": "local" },
        "createdAt": 1736942400000,
        "updatedAt": 1736942400000
      }
    ]
  }
}

---

Versioning

schemaVersion is a monotonically increasing integer. XTagger refuses to import a manifest whose schemaVersion is greater than its own supported version. Older manifests with lower versions are migrated automatically on import.