TDF - Temporal Data Format

Auto-generate your docs

Overview
Why JSON-LD?
Core Concepts
1. Rendered Future
2. Rendered Past
3. Validated Prediction
Schema Fields
Required Fields
Temporal Fields
Actor Identification
Causal Context
Phase 2 Integration
Proteus Submission
Resolution Output
Distance Metrics in TDF
Levenshtein Distance (Phase 1)
Semantic Distance (Phase 2)
Graph Distance (Phase 3)
Validation
Common Validation Errors
Querying Clockchain with TDF
SNAG Bench Integration
Implementation Roadmap
Current State (v0)
Phase 2 (Planned)
Phase 3 (Research)
Resources
External Resources
Example: Full Market Lifecycle

TDF (Temporal Data Format) is the standardized JSON-LD interchange format used across all Timepoint Suite services. It provides a common language for expressing temporal predictions, historical reconstructions, and causal relationships.

Status: TDF specification is under active development. Proteus v0 does not yet implement TDF. This documentation describes the planned Phase 2 integration.

Overview

TDF enables interoperability across the Timepoint ecosystem:

Pro outputs Rendered Futures in TDF format
Flash outputs historical reconstructions in TDF format
Proteus will accept predictions as TDF records (Phase 2)
Clockchain stores validated predictions and events as TDF
SNAG Bench evaluates causal resolution using TDF metadata

Why JSON-LD?

JSON-LD (JavaScript Object Notation for Linked Data) provides:

Machine-readable: Standard JSON parsing
Semantic web: RDF-compatible with @context vocabularies
Extensible: Custom fields and namespaces
Interoperable: Cross-service data exchange

Core Concepts

1. Rendered Future

A prediction generated by Pro or submitted by a participant:

{
  "@context": "https://timepoint.ai/tdf/v1",
  "@type": "RenderedFuture",
  "@id": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
  "prediction": {
    "actor": "@elonmusk",
    "event": "social_media_post",
    "content": "Starship flight 2 is GO for March. Humanity becomes multiplanetary or we die trying.",
    "temporal": {
      "window_start": "2026-03-01T00:00:00Z",
      "window_end": "2026-04-01T00:00:00Z",
      "timezone": "UTC"
    },
    "confidence": 0.87,
    "renderer": {
      "system": "pro-v2.1",
      "model": "claude-4.5-sonnet",
      "timestamp": "2026-02-15T10:30:00Z"
    },
    "causal_context": [
      {
        "@id": "urn:clockchain:event:starship_test_1_success",
        "description": "Starship Test Flight 1 successful landing",
        "timestamp": "2026-01-15T08:00:00Z"
      },
      {
        "@id": "urn:clockchain:event:faa_approval",
        "description": "FAA approval for Test Flight 2",
        "timestamp": "2026-02-10T14:00:00Z"
      }
    ]
  },
  "metadata": {
    "version": "1.0",
    "created": "2026-02-15T10:30:00Z",
    "source": "timepoint-pro"
  }
}

2. Rendered Past

A historical reconstruction generated by Flash:

{
  "@context": "https://timepoint.ai/tdf/v1",
  "@type": "RenderedPast",
  "@id": "urn:uuid:a1b2c3d4-1234-5678-90ab-cdef12345678",
  "event": {
    "actor": "@sama",
    "description": "Sam Altman posts AGI confidence statement",
    "content": "we are now confident AGI is achievable with current techniques. announcement soon.",
    "timestamp": "2026-03-15T14:23:11Z",
    "verification": {
      "source": "x.com",
      "post_id": "1234567890123456789",
      "archive_url": "https://archive.today/abc123",
      "verified_at": "2026-03-15T14:25:00Z"
    }
  },
  "context": {
    "preceding_events": [
      "urn:clockchain:event:gpt5_training_complete",
      "urn:clockchain:event:openai_board_meeting"
    ],
    "market_impact": {
      "sentiment_shift": 0.23,
      "volume_spike": 1.8
    }
  },
  "metadata": {
    "version": "1.0",
    "created": "2026-03-15T14:26:00Z",
    "source": "timepoint-flash"
  }
}

3. Validated Prediction

A Proteus market resolution with distance metric:

{
  "@context": "https://timepoint.ai/tdf/v1",
  "@type": "ValidatedPrediction",
  "@id": "urn:proteus:market:123",
  "market": {
    "id": 123,
    "target": "@sama",
    "resolution_timestamp": "2026-03-15T14:23:11Z",
    "blockchain": {
      "network": "base-mainnet",
      "contract": "0x5174Da96BCA87c78591038DEe9DB1811288c9286",
      "block": 8675309,
      "tx_hash": "0xabcdef..."
    }
  },
  "predictions": [
    {
      "submitter": "0x1234...",
      "stake": "0.05",
      "predicted_content": "we are now confident AGI is achievable with current techniques. big announcement soon.",
      "distance": 4,
      "winner": true
    },
    {
      "submitter": "0x5678...",
      "stake": "0.02",
      "predicted_content": "we now believe AGI is achievable with current techniques. announcement coming soon.",
      "distance": 18,
      "winner": false
    }
  ],
  "actual": {
    "content": "we are now confident AGI is achievable with current techniques. announcement soon.",
    "verified_by": "oracle_consensus",
    "verification_sources": [
      "x.com/sama/status/1234567890123456789",
      "archive.today/abc123"
    ]
  },
  "metrics": {
    "winning_distance": 4,
    "mean_distance": 27.3,
    "total_pool": "1.42",
    "winner_payout": "1.32"
  },
  "clockchain_graduate": true,
  "metadata": {
    "version": "1.0",
    "created": "2026-03-15T14:30:00Z",
    "source": "proteus"
  }
}

Schema Fields

Required Fields

All TDF records must include:

Field	Type	Description
`@context`	string	TDF vocabulary URL
`@type`	string	Record type (RenderedFuture, RenderedPast, ValidatedPrediction)
`@id`	string	Unique identifier (URN or URL)
`metadata.version`	string	TDF schema version
`metadata.created`	ISO 8601	Creation timestamp
`metadata.source`	string	Originating system

Temporal Fields

Temporal bounds for predictions:

{
  "temporal": {
    "window_start": "2026-03-01T00:00:00Z",  // ISO 8601
    "window_end": "2026-04-01T00:00:00Z",
    "timezone": "UTC",
    "granularity": "day"  // second, minute, hour, day, week
  }
}

Actor Identification

Standardized actor references:

{
  "actor": "@elonmusk",           // X handle
  "actor_type": "public_figure",  // public_figure, organization, bot
  "actor_verified": true,
  "actor_metadata": {
    "x_id": "44196397",
    "follower_count": 180000000,
    "account_created": "2009-06-02"
  }
}

Causal Context

Link to preceding events in the Clockchain:

{
  "causal_context": [
    {
      "@id": "urn:clockchain:event:12345",
      "description": "Event description",
      "timestamp": "2026-01-15T08:00:00Z",
      "causal_weight": 0.8  // 0.0-1.0, relevance to prediction
    }
  ]
}

Phase 2 Integration

Proteus Submission

When TDF is implemented, predictions will be submitted as:

// Current (v0): Free-form text
await proteus.submitPrediction(marketId, {
  predictedText: "Starship flight 2 is GO for March...",
  stake: ethers.utils.parseEther("0.1")
});

// Future (Phase 2): TDF record
const rendering = await pro.render({
  persona: '@elonmusk',
  context: 'Starship test flight',
  window: {
    start: '2026-03-01',
    end: '2026-04-01'
  }
});

await proteus.submitPrediction(marketId, {
  tdf: rendering.toTDF(),  // TDF format
  stake: ethers.utils.parseEther("0.1")
});

Resolution Output

Resolved markets will generate TDF records automatically:

// Resolve market (oracle)
const resolution = await proteus.resolveMarket(marketId, {
  actualText: "Starship flight 2 is GO for March...",
  verificationSources: [
    "https://x.com/elonmusk/status/...",
    "https://archive.today/..."
  ]
});

// Export to TDF
const tdf = await proteus.exportTDF(marketId);

// Submit to Clockchain
await clockchain.ingest(tdf);

Distance Metrics in TDF

Levenshtein Distance (Phase 1)

{
  "distance_metric": {
    "type": "levenshtein",
    "value": 4,
    "components": {
      "insertions": 0,
      "deletions": 0,
      "substitutions": 4
    },
    "normalized": 0.034  // distance / max(len(a), len(b))
  }
}

Semantic Distance (Phase 2)

{
  "distance_metric": {
    "type": "semantic",
    "value": 0.23,
    "method": "embedding_cosine",
    "model": "text-embedding-3-large",
    "components": {
      "content_similarity": 0.89,
      "temporal_accuracy": 0.95,
      "actor_match": 1.0
    }
  }
}

Graph Distance (Phase 3)

{
  "distance_metric": {
    "type": "graph",
    "value": 5,
    "method": "edit_distance",
    "components": {
      "node_insertions": 2,
      "node_deletions": 1,
      "edge_modifications": 2,
      "causal_path_accuracy": 0.87
    }
  }
}

Validation

TDF records should be validated against the schema:

import { TDFValidator } from '@timepoint/tdf';

const validator = new TDFValidator('v1');

try {
  validator.validate(tdfRecord);
  console.log('Valid TDF record');
} catch (error) {
  console.error('Validation failed:', error.details);
}

Common Validation Errors

Error	Cause	Solution
`MISSING_REQUIRED_FIELD`	Required field absent	Add `@context`, `@type`, `@id`, or `metadata`
`INVALID_TIMESTAMP`	Malformed ISO 8601	Use `YYYY-MM-DDTHH:mm:ssZ` format
`INVALID_ACTOR_REFERENCE`	Bad actor ID format	Use `@handle` or `urn:actor:...`
`TEMPORAL_WINDOW_INVALID`	End before start	Ensure `window_end` > `window_start`

Querying Clockchain with TDF

// Query by actor
const predictions = await clockchain.query({
  '@type': 'ValidatedPrediction',
  'market.target': '@elonmusk',
  'metrics.winning_distance': { $lt: 10 },
  'temporal.window_start': {
    $gte: '2026-01-01',
    $lt: '2026-04-01'
  }
});

// Query by causal context
const relatedEvents = await clockchain.query({
  '@type': 'RenderedPast',
  'causal_context.@id': 'urn:clockchain:event:starship_test_1'
});

// Aggregate metrics
const accuracy = await clockchain.aggregate([
  { $match: { '@type': 'ValidatedPrediction' } },
  { $group: {
    _id: '$market.target',
    avgDistance: { $avg: '$metrics.winning_distance' },
    count: { $sum: 1 }
  }}
]);

SNAG Bench Integration

SNAG Bench uses TDF to measure Causal Resolution:

{
  "@context": "https://timepoint.ai/tdf/v1",
  "@type": "SNAGBenchmark",
  "evaluation": {
    "renderer": "pro-v2.1",
    "predictions": [
      "urn:proteus:market:123",
      "urn:proteus:market:124",
      "urn:proteus:market:125"
    ],
    "causal_resolution": 0.87,
    "metrics": {
      "mean_distance": 8.3,
      "temporal_accuracy": 0.92,
      "causal_consistency": 0.85
    }
  }
}

Implementation Roadmap

Current State (v0)

❌ TDF schema not finalized
❌ Proteus does not accept TDF
❌ Pro does not output TDF
❌ Clockchain TDF storage not implemented

Phase 2 (Planned)

TDF v1 schema specification complete
Reference implementation in TypeScript/Python
Proteus accepts TDF predictions
Pro outputs Rendered Futures as TDF
Clockchain stores validated predictions as TDF
SNAG Bench evaluates TDF records

Phase 3 (Research)

Graph distance metrics in TDF
Multi-level prediction nesting
Causal subgraph representation
Full Proof of Causal Convergence

Resources

Suite Overview

Learn about the full Timepoint Suite

Integration Guide

How Proteus integrates with the suite

External Resources

TDF Repository: timepoint-tdf (specification and reference implementation)
JSON-LD Specification: W3C JSON-LD
Timepoint Thesis (forthcoming): Formal specification
Follow: @seanmcdonaldxyz for updates

Example: Full Market Lifecycle

// 1. Pro generates rendering
const rendering = await pro.render({
  persona: '@sama',
  context: 'AGI announcement',
  window: { start: '2026-03-01', end: '2026-04-01' }
});

// 2. Submit to Proteus as TDF
const submission = await proteus.submit({
  marketId: 123,
  tdf: rendering.toTDF(),
  stake: ethers.utils.parseEther('0.1')
});

// 3. Market resolves
const resolution = await proteus.resolve({
  marketId: 123,
  actualText: "we are now confident AGI is achievable...",
  sources: ["https://x.com/sama/status/..."]
});

// 4. Export validated prediction
const validated = await proteus.exportTDF(123);

// 5. Graduate to Clockchain
if (validated.metrics.winning_distance < 10) {
  await clockchain.ingest(validated);
  console.log('Graduated to Clockchain');
}

// 6. Query for training data
const trainingData = await clockchain.query({
  '@type': 'ValidatedPrediction',
  'market.target': '@sama',
  'clockchain_graduate': true
});

// 7. Refine Pro model
await pro.finetune({
  persona: '@sama',
  data: trainingData,
  metric: 'levenshtein'
});

This lifecycle demonstrates how TDF enables seamless interoperability across the entire Timepoint Suite.

Proteus Integration with Timepoint Suite

⌘I

Build docs developers (and LLMs) love

Get started for free Talk to us

Theory

Timepoint Suite

​Overview

​Why JSON-LD?

​Core Concepts

​1. Rendered Future

​2. Rendered Past

​3. Validated Prediction

​Schema Fields

​Required Fields

​Temporal Fields

​Actor Identification

​Causal Context

​Phase 2 Integration

​Proteus Submission

​Resolution Output

​Distance Metrics in TDF

​Levenshtein Distance (Phase 1)

​Semantic Distance (Phase 2)

​Graph Distance (Phase 3)

​Validation

​Common Validation Errors

​Querying Clockchain with TDF

​SNAG Bench Integration

​Implementation Roadmap

​Current State (v0)

​Phase 2 (Planned)

​Phase 3 (Research)

​Resources

Suite Overview

Integration Guide

​External Resources

​Example: Full Market Lifecycle

Build docs developers (and LLMs) love

Overview

Why JSON-LD?

Core Concepts

1. Rendered Future

2. Rendered Past

3. Validated Prediction

Schema Fields

Required Fields

Temporal Fields

Actor Identification

Causal Context

Phase 2 Integration

Proteus Submission

Resolution Output

Distance Metrics in TDF

Levenshtein Distance (Phase 1)

Semantic Distance (Phase 2)

Graph Distance (Phase 3)

Validation

Common Validation Errors

Querying Clockchain with TDF

SNAG Bench Integration

Implementation Roadmap

Current State (v0)

Phase 2 (Planned)

Phase 3 (Research)

Resources

External Resources

Example: Full Market Lifecycle