The dual nature of context - AI grounding information and JSON-LD semantic vocabulary

context

The dual-purpose primitive that provides meaning through two complementary mechanisms: AI/Agent context for grounding intelligent decisions, and JSON-LD @context for semantic vocabulary definitions (schema.org.ai).

Overview

Context is everything - literally. The context primitive embodies a powerful double entendre, serving two critical yet unified purposes:

AI Context - Grounding information that enables AI models and agents to make informed, contextually-aware decisions
Semantic Context - JSON-LD @context that defines semantic vocabulary for schema.org.ai and MDXLD interoperability

The Unified Purpose: Both forms of context serve the same fundamental goal - providing meaning. Whether grounding an AI agent or defining semantic vocabulary, context transforms raw data into meaningful information.

Core Insight: Context is REQUIRED for both AI/Agents AND JSON-LD/MDXLD. The same primitive that helps agents understand "What does this customer need?" also helps systems understand "What does 'Customer' mean in our semantic graph?"

AI Context: Grounding Intelligent Decisions

Context provides the grounding information that enables AI models and agents to make informed decisions.

Context Gathering

Collect relevant information to ground AI operations:

import { ai, $, context } from 'sdk.do'

// Gather context for lead qualification
const leadContext = await context.gather({
  lead: await $.Lead.get('lead-123'),
  company: await $.Company.get('company-456'),
  industry: await $.Industry.get('tech'),
  competitors: await $.Competitor.list({ industry: 'tech' }),
  recentInteractions: await $.Lead.has.Interactions({ leadId: 'lead-123' }),
  similarDeals: await $.Deal.where.industry.equals('tech').limit(5),
})

// Use context in AI generation
const analysis = await ai.generate({
  model: 'gpt-5',
  prompt: 'Analyze this lead and recommend next steps',
  context: leadContext,
})

Context Enrichment

Dynamically enrich context as workflows progress:

import { workflow, context, ai } from 'sdk.do'

workflow('qualify-lead', async ({ lead }) => {
  // Initial context
  let ctx = await context.gather({
    lead: await $.Lead.get(lead.id),
    company: await $.Company.get(lead.companyId),
  })

  // Step 1: Research and enrich context
  const research = await ai.generate({
    model: 'gpt-5',
    prompt: 'Research this company',
    context: ctx,
  })
  ctx = context.enrich(ctx, { research })

  // Step 2: Score with enriched context
  const score = await ai.generate({
    model: 'claude-sonnet-4.5',
    prompt: 'Score this lead',
    context: ctx,
  })
  ctx = context.enrich(ctx, { score })

  // Step 3: Decide with full context
  const decision = await ai.decide({
    question: 'Should we pursue this lead?',
    context: ctx,
  })

  return { lead, research, score, decision }
})

Context Scoping

Scope context to relevant information for specific operations:

import { context, agent } from 'sdk.do'

// Agent with scoped context
const salesAgent = await agent.create({
  name: 'sales-assistant',
  role: 'SDR',

  async execute({ lead }) {
    // Full context
    const fullContext = await context.gather({
      lead,
      company: await $.Company.get(lead.companyId),
      industry: await $.Industry.get(lead.industry),
      competitors: await $.Competitor.list(),
      deals: await $.Deal.list(),
      interactions: await $.Interaction.list(),
    })

    // Scope context for research
    const researchContext = context.scope(fullContext, ['company', 'industry', 'competitors'])

    const research = await ai.generate({
      model: 'gpt-5',
      prompt: 'Research company and competitors',
      context: researchContext,
    })

    // Scope context for scoring
    const scoringContext = context.scope(fullContext, ['lead', 'company', 'deals'])

    const score = await ai.generate({
      model: 'claude-sonnet-4.5',
      prompt: 'Score lead against historical deals',
      context: { ...scoringContext, research },
    })

    return { research, score }
  },
})

Context in Agent Memory

Agents maintain persistent context across interactions:

import { agent, context } from 'sdk.do'

const supportAgent = await agent.create({
  name: 'support-assistant',
  memory: context.create({
    customer: null,
    conversationHistory: [],
    previousIssues: [],
    knownPreferences: {},
  }),

  async execute({ message, customerId }) {
    // Load customer context
    const customer = await $.Customer.get(customerId)

    // Enrich agent memory with context
    this.memory = context.enrich(this.memory, {
      customer,
      conversationHistory: [...this.memory.conversationHistory, { role: 'user', content: message }],
      previousIssues: await $.Customer.has.Issues({ customerId }),
    })

    // Generate response with full context
    const response = await ai.generate({
      model: 'gpt-5',
      prompt: 'Respond to customer message',
      context: this.memory,
    })

    // Update memory
    this.memory.conversationHistory.push({
      role: 'assistant',
      content: response,
    })

    return response
  },
})

Semantic Context: JSON-LD @context

Context defines semantic vocabulary for MDXLD and schema.org.ai interoperability.

JSON-LD @context Basics

The @context property maps terms to IRIs (Internationalized Resource Identifiers):

import { mdxld } from 'sdk.do'

// Define semantic context
const businessContext = {
  '@context': {
    '@vocab': 'https://schema.org.ai/',
    schema: 'https://schema.org/',
    Business: 'schema:Organization',
    name: 'schema:name',
    address: 'schema:address',
    employees: 'schema:employee',
    revenue: 'schema:annualRevenue',
  },
}

// Use in MDXLD
const business = await mdxld.parse(
  `
# Acme Inc

- name: Acme Inc
- revenue: $10M
- employees: 50
`,
  businessContext
)

// Result: Fully semantic business entity
// {
//   '@context': { ... },
//   '@type': 'Business',
//   'name': 'Acme Inc',
//   'revenue': { '@type': 'MonetaryAmount', 'value': 10000000 },
//   'employees': 50
// }

schema.org.ai Context Standards

All Things use schema.org.ai vocabularies via @context:

import { $, mdxld } from 'sdk.do'

// schema.org.ai context for Business
const businessContext = {
  '@context': {
    '@vocab': 'https://schema.org.ai/',
    Business: {
      '@id': 'schema:Organization',
      '@type': '@id',
    },
    industry: {
      '@id': 'schema:industry',
      '@type': '@id',
      '@context': {
        '@vocab': 'https://industries.org.ai/',
      },
    },
    process: {
      '@id': 'apqc:process',
      '@type': '@id',
      '@context': {
        '@vocab': 'https://process.org.ai/',
      },
    },
  },
}

// Create semantic business entity
const business = await $.Business.create({
  '@context': businessContext,
  name: 'Acme Inc',
  industry: 'Technology',
  process: ['sales', 'marketing', 'engineering'],
})

MDXLD Context Integration

MDXLD uses @context for semantic interoperability:

---
@context:
  @vocab: https://schema.org.ai/
  schema: https://schema.org/
  Product: schema:Product
  price: schema:price
  availability: schema:availability
---

# MacBook Pro

The latest MacBook Pro with M4 chip.

- price: $2499
- availability: InStock
- brand: Apple
- category: Computers

Parsed Result:

{
  "@context": {
    "@vocab": "https://schema.org.ai/",
    "Product": "schema:Product",
    "price": "schema:price"
  },
  "@type": "Product",
  "name": "MacBook Pro",
  "description": "The latest MacBook Pro with M4 chip",
  "price": {
    "@type": "MonetaryAmount",
    "value": 2499,
    "currency": "USD"
  },
  "availability": "InStock",
  "brand": "Apple",
  "category": "Computers"
}

Context Inheritance

Contexts can inherit and extend parent contexts:

import { mdxld } from 'sdk.do'

// Base schema.org.ai context
const baseContext = {
  '@context': {
    '@vocab': 'https://schema.org.ai/',
    Thing: 'schema:Thing',
    name: 'schema:name',
    description: 'schema:description',
  },
}

// Extended context for Products
const productContext = {
  '@context': [
    baseContext['@context'],
    {
      Product: 'schema:Product',
      price: 'schema:price',
      sku: 'schema:sku',
      brand: 'schema:brand',
    },
  ],
}

// Extended context for SoftwareApplication
const softwareContext = {
  '@context': [
    productContext['@context'],
    {
      SoftwareApplication: 'schema:SoftwareApplication',
      version: 'schema:softwareVersion',
      platform: 'schema:operatingSystem',
    },
  ],
}

The Unified Context Pattern

Both AI context and semantic context serve the same purpose: providing meaning.

Context as Meaning

import { $, ai, mdxld, context } from 'sdk.do'

// Define semantic context (@context for vocabulary)
const customerContext = {
  '@context': {
    '@vocab': 'https://schema.org.ai/',
    Customer: 'schema:Person',
    orders: 'schema:Order',
    preferences: 'schema:knowsAbout',
  },
}

// Gather AI context (grounding information)
const aiContext = await context.gather({
  customer: await $.Customer.get('customer-123'),
  orders: await $.Customer.has.Orders({ customerId: 'customer-123' }),
  preferences: await $.Customer.has.Preferences({ customerId: 'customer-123' }),
  recentActivity: await $.Customer.has.Activity({ customerId: 'customer-123' }),
})

// Both contexts provide meaning
// - Semantic context defines WHAT things are (vocabulary)
// - AI context defines WHICH instances we're working with (grounding)

// Use together in agent
const recommendation = await ai.generate({
  model: 'gpt-5',
  prompt: 'Recommend products for this customer',
  context: {
    semantic: customerContext, // Vocabulary definitions
    data: aiContext, // Grounding information
  },
})

// Export as MDXLD with both contexts
const mdx = await mdxld.generate({
  '@context': customerContext,
  ...aiContext,
  recommendation,
})

Context in Workflows

Workflows use both forms of context:

import { workflow, context, ai, $ } from 'sdk.do'

workflow('process-customer-request', async ({ request }) => {
  // Semantic context (vocabulary)
  const semanticContext = {
    '@context': {
      '@vocab': 'https://schema.org.ai/',
      Request: 'schema:ServiceRequest',
      Customer: 'schema:Person',
    },
  }

  // AI context (grounding)
  let aiContext = await context.gather({
    request: await $.Request.get(request.id),
    customer: await $.Customer.get(request.customerId),
    history: await $.Customer.has.Requests({ customerId: request.customerId }),
  })

  // Step 1: Classify request with context
  const classification = await ai.generate({
    model: 'gpt-5',
    prompt: 'Classify this customer request',
    context: {
      semantic: semanticContext,
      data: aiContext,
    },
  })

  // Enrich context with classification
  aiContext = context.enrich(aiContext, { classification })

  // Step 2: Generate response with enriched context
  const response = await ai.generate({
    model: 'claude-sonnet-4.5',
    prompt: 'Generate customer response',
    context: {
      semantic: semanticContext,
      data: aiContext,
    },
  })

  return { request, classification, response }
})

SDK Object Integration

Context integrates with all 8 core SDK objects:

import { $, ai, api, db, decide, every, on, send, user, context } from 'sdk.do'

// AI - Generative functions with context
const strategy = await ai.generate({
  model: 'gpt-5',
  prompt: 'Generate strategy',
  context: await context.gather({
    company: await $.Company.get('company-123'),
    market: await $.Market.get('saas'),
  }),
})

// API - Integration actions with context
await api.action('github.create_issue', {
  context: await context.gather({
    repo: await $.Repository.get('repo-456'),
    project: await $.Project.get('project-789'),
  }),
})

// DB - Database queries with semantic context
const businesses = await db.list($.Business, {
  '@context': {
    '@vocab': 'https://schema.org.ai/',
  },
})

// DECIDE - Experiments with user context
const variant = await decide.get('pricing-test', {
  context: await context.gather({
    user: await $.User.get('user-123'),
    segment: await $.User.belongs.Segment({ userId: 'user-123' }),
  }),
})

// EVERY - Scheduled workflows with context
every('daily at 9am', async () => {
  const ctx = await context.gather({
    date: new Date(),
    reports: await $.Report.where.pending.equals(true),
  })

  for (const report of ctx.reports) {
    await $.Report.generate({
      reportId: report.id,
      context: ctx,
    })
  }
})

// ON - Event handlers with context
on($.Order.created, async ({ order }) => {
  const ctx = await context.gather({
    order,
    customer: await $.Order.belongs.Customer({ orderId: order.id }),
    items: await $.Order.contains.Items({ orderId: order.id }),
  })

  await $.Workflow.start('process-order', { context: ctx })
})

// SEND - Analytics with context
await send($.Analytics.track, {
  event: 'order.completed',
  context: await context.gather({
    order: await $.Order.get('order-123'),
    customer: await $.Customer.get('customer-456'),
  }),
})

// USER - Human functions with context
const approval = await user.requestApproval({
  type: 'contract-review',
  context: await context.gather({
    contract: await $.Contract.get('contract-789'),
    customer: await $.Customer.get('customer-456'),
    terms: await $.Contract.has.Terms({ contractId: 'contract-789' }),
  }),
})

Context Patterns in Practice

Agent Context Management

import { agent, context, ai } from 'sdk.do'

const researchAgent = await agent.create({
  name: 'market-researcher',

  async execute({ company }) {
    // Phase 1: Gather base context
    const baseContext = await context.gather({
      company: await $.Company.get(company.id),
      industry: await $.Company.belongs.Industry({ companyId: company.id }),
    })

    // Phase 2: Research and enrich
    const research = await ai.generate({
      model: 'gpt-5',
      prompt: 'Research company and competitors',
      context: baseContext,
      tools: ['web-search', 'crunchbase-api'],
    })

    const enrichedContext = context.enrich(baseContext, { research })

    // Phase 3: Analyze with full context
    const analysis = await ai.generate({
      model: 'claude-sonnet-4.5',
      prompt: 'Analyze market position and opportunities',
      context: enrichedContext,
    })

    // Phase 4: Generate recommendations
    const recommendations = await ai.generate({
      model: 'gpt-5',
      prompt: 'Generate strategic recommendations',
      context: context.enrich(enrichedContext, { analysis }),
    })

    return { research, analysis, recommendations }
  },
})

Semantic Context Chains

import { mdxld, context } from 'sdk.do'

// Base schema.org.ai context
const baseContext = {
  '@context': {
    '@vocab': 'https://schema.org.ai/',
    schema: 'https://schema.org/',
  },
}

// Organization context extends base
const orgContext = context.extend(baseContext, {
  Organization: 'schema:Organization',
  industry: {
    '@id': 'schema:industry',
    '@context': {
      '@vocab': 'https://industries.org.ai/',
    },
  },
})

// Business context extends organization
const businessContext = context.extend(orgContext, {
  Business: 'schema:LocalBusiness',
  process: {
    '@id': 'apqc:process',
    '@context': {
      '@vocab': 'https://process.org.ai/',
    },
  },
})

// Use chained context in MDXLD
const business = await mdxld.parse(
  `
# Acme Inc

- industry: Technology
- process: Sales
`,
  businessContext
)

Core Capabilities

AI Context - Grounding information for intelligent decisions
Semantic Context - JSON-LD @context for vocabulary definitions
Context Gathering - Collect relevant information
Context Enrichment - Dynamically extend context
Context Scoping - Filter to relevant information
Context Inheritance - Extend and compose contexts
MDXLD Integration - Semantic MDX with @context
schema.org.ai Standards - Shared vocabulary across Things
Unified Purpose - Both provide meaning

Access Methods

SDK

TypeScript/JavaScript library for context management

const ctx = await context.gather({ user: await $.User.get('user-123') })

→ SDK Documentation

CLI

Command-line tool for context operations

do context gather "$.User.get('user-123')"

→ CLI Documentation

API

REST/RPC endpoints with context propagation

curl -X POST https://api.do/v1/context/gather -d '{"user":"user-123"}'

→ API Documentation

MCP

Model Context Protocol for context-aware operations

Gather context for user user-123 including orders and preferences

→ MCP Documentation

Parent Concept

semantics - Context uses semantic patterns

SDK Object Mappings

ai - AI operations require context (SDK object - 1 of 8 core)
db - Database operations with semantic context (SDK object - 1 of 8 core)

agents - Agents use context for autonomous decisions
workflows - Workflows maintain and enrich context
data - Data operations use semantic context
graph - Graph traversal with contextual relationships
llm - LLMs require context for generation

context

On this page