# JSON Mapping

JSON is a **transport format**, not a canonical representation of HEXT.

JSON documents are projections of the Semantic Object Graph. They are suitable for API responses, MCP tool payloads, and programmatic interchange. They MUST NOT be treated as authoritative over Semantic XML.

## Principle

```
Semantic Object Graph
        │
        ├─► Semantic XML   (canonical serialization)
        └─► JSON           (transport projection)
```

JSON is non-canonical because it is a projection of the graph, not the graph itself.

## Field Mapping

JSON objects use snake_case field names aligned with the core object model:

| JSON field | XML element | Required |
|---|---|---|
| `spec_version` | `hext:Document/@specVersion` | Yes |
| `object` | `hext:Object` | Yes |
| `provenance` | `hext:Provenance` | Yes |
| `semantic` | `hext:Semantic` | No |
| `ledger` | `hext:Ledger` | Yes |
| `final_seal` | `hext:Seal` | Yes |
| `evidence` | `hext:Evidence` | Yes |

### object

```json
{
  "id": "rfc-nvp18",
  "type": "document.rfc",
  "lifecycle": "draft",
  "registry_ref": "gmm://rfc/NVP18",
  "metrics": {
    "characters": 22815,
    "lines": 842,
    "paragraphs": 137,
    "tokens_estimated": 6124
  }
}
```

### provenance

```json
{
  "derived_from": "gmm://rfc/NVP14",
  "contributors": [
    { "agent": "human:tomo", "role": "author" },
    { "agent": "ai:claude-sonnet-4-6", "role": "co-author" }
  ],
  "agency": {
    "human_touch": 0.81,
    "primary_generator": "human"
  }
}
```

### semantic (optional)

```json
{
  "instrument": { "type": "nvs-kernel", "version": "2.1.0" },
  "measurement": {
    "coordinate_system": "siv-6d-event",
    "window_method": "morphological-beat-segmentation",
    "window_calibration": {
      "entropy_threshold": 0.35,
      "morphology_parser": "mecab-unidic-v3"
    }
  },
  "observation_ref": "gmm://observation/rfc-nvp18-v1"
}
```

### ledger

```json
[
  {
    "t": 1750291200,
    "type": "HUMAN",
    "delta": 34,
    "hash": "sha256:e3b0c44298fc1c149afbf4c8996fb924"
  }
]
```

### final_seal

```json
{
  "sealed_at": "2026-06-19T15:00:00Z",
  "state_hash": "sha256:d5c3175c8e9f2a1b4c6d8e0f3a5b7c9d"
}
```

### evidence

```json
{
  "format": "text/markdown",
  "body": "# Example\n\nCrystallized content."
}
```

## Round-Trip Requirements

Implementations that project HEXT to JSON:

- MUST preserve all required fields
- MUST preserve optional fields when present
- MUST support lossless reconstruction to Semantic XML
- MUST NOT introduce fields absent from the Object Graph model

## MCP Tool Mapping

HEXT JSON projections are intended for MCP resources and tools such as:

```
resource://hext/document/{id}
crystallize_hext
validate_integrity
```

Tool interfaces are defined in [SPECIFICATION.md](../SPECIFICATION.md#mcp-mapping).

## Legacy Markdown Metadata Blocks

Legacy `.hxt` files embed JSON (not YAML) metadata blocks in Markdown. Import tools MAY accept this form and convert it to canonical XML or to the JSON projection above.

See [serialization.md](../docs/serialization.md) and [history/SPEC-v0.1.0-markdown-ledger.md](../history/SPEC-v0.1.0-markdown-ledger.md).