Swarm KYA JSON-LD — Consumer Processing Guide (v1.1)

Purpose
Each asset page includes a hidden, machine-readable JSON-LD block at the end of the document. This block is the canonical data source for integrations, indexing, and automation. Human-facing tables are informative only.

Example (pretty-printed by default):

<script type="application/ld+json">
{
  "type": "Asset",
  "...": "..."
}
</script>

Audience
Consumers of KYA data (indexers, apps, validators, explorers).

---

1) Discovery

• In the rendered HTML of an asset page, select the last <script type="application/ld+json">…</script> block.
• Parse JSON and assert type === "Asset". If absent, treat the page as not machine-ready.
• Producers may emit either pretty-printed (default) or minified JSON. Consumers must accept both.

Robust extraction (pseudo)
Prefer DOM parsing; fallback to regex only if DOM is unavailable. If multiple JSON-LD blocks exist, pick the last one where type equals "Asset".

---

2) Data Model (summary)

Root object: type: "Asset"

On-chain deployment item

{
  "network": "Polygon PoS",   // label in human table
  "chainId": 137,             // integer
  "tokenAddress": "0x...",    // EVM address
  "ticker": "AAPL",           // often same as root symbol
  "decimals": 18,             // 0–36
  "usdcTokenAddress": "0x..." // optional; present where USDC redemption applies
}

Documents

• baseProspectus — URL (if present).
• prospectusFinalTerms — URL (if present).
• terms[] — array of { title?, url } items.

Versions

• kyaVersion — KYA document version string.
• tokenVersion — token implementation version string.

---

3) Processing Rules

1. Canonical: JSON-LD overrides human tables when discrepancies are found.
2. Deployment key: index deployments by (symbol, network, chainId, tokenAddress).
3. Ticker default: if omitted, assume ticker = symbol.
4. USDC redemption: if usdcTokenAddress is present, redemption is available on that network.
5. Extras: preserve unknown fields under extra for forward compatibility.
6. Timestamps: parse createdAt/updatedAt (if present) as ISO 8601.

---

4) Validation Hints (Consumer-side)

• type must equal "Asset".
• tokenStandard must equal "SX1411".
• actors must include issuer, guardian, agent with a title string.
• onChain must have ≥ 1 item. Each item: chainId integer; decimals integer in [0,36].
• EVM addresses: ^0x[a-fA-F0-9]{40}$ (relax if a non-EVM network appears in the future).

---

5) Integration Examples

Node.js (jsdom)

import { JSDOM } from "jsdom";

export function extractAssetJSONLD(html) {
  const dom = new JSDOM(html);
  const scripts = [...dom.window.document.querySelectorAll("script[type='application/ld+json']")];
  for (const el of scripts.reverse()) {
    try {
      const obj = JSON.parse(el.textContent);
      if (obj && obj.type === "Asset") return obj;
    } catch {}
  }
  throw new Error("No Asset JSON-LD found");
}

Python (BeautifulSoup + json)
Code fences use txt intentionally to avoid renderer restrictions.

from bs4 import BeautifulSoup
import json

def extract_asset_jsonld(html: str):
    soup = BeautifulSoup(html, "html.parser")
    blocks = soup.find_all("script", {"type": "application/ld+json"})
    for b in reversed(blocks):  # prefer last
        try:
            data = json.loads(b.string)
            if isinstance(data, dict) and data.get("type") == "Asset":
                return data
        except Exception:
            pass
    raise ValueError("No Asset JSON-LD found")

---

6) Versioning & Compatibility

• Schema version: v1.1 (no breaking changes).
• Consumers should ignore unknown fields to remain forward-compatible.

Changelog

• 2025-09-26 (v1.1): Document that JSON-LD is pretty-printed by default; minified is still valid.
• 2025-09-26 (v1.0): Initial publication.