The semantic pattern system using $.Subject.predicate.Object with GraphDL and parts of speech

semantics

The meta-primitive that defines how all .do code is structured using semantic patterns based on parts of speech, RDF-style triples, and GraphDL.

Overview

The semantics primitive is the foundational design philosophy of the .do platform. It defines how all code, data, and business logic is expressed using semantic patterns that mirror natural language structure, making code intuitive and self-documenting.

Core Principle: Every operation in .do follows semantic patterns based on:

Parts of Speech - Nouns, Verbs, Adjectives, Adverbs
RDF Triples - Subject.predicate.Object
GraphDL - Graph Definition Language for relationships
Natural Language - Code that reads like English

This creates code that is:

Self-documenting - Meaning is clear from structure
Intuitive - Follows natural language patterns
Type-safe - Semantic validation at compile time
Graph-native - Built for interconnected data

The $ Semantic Root

All semantic operations start with $ (the semantic root):

import { $ } from 'sdk.do'

// $ represents the semantic namespace
// Everything under $ follows semantic patterns

// Entities (Nouns)
$.User()
$.Order()
$.Product()
$.Team()

// Actions (Verbs)
$.User.create()
$.Order.update()
$.Product.delete()

// Relationships (Subject.predicate.Object)
$.User.has.Orders()
$.Order.contains.Items()
$.Team.includes.Members()

Why $?

Universal semantic root
Short and memorable
Distinguishes semantic operations from regular code
Inspired by jQuery's DOM selector ($ for semantic selection)

The Semantic Triple Pattern

The foundation of all semantic operations:

Basic Triple: $.Subject.predicate.Object

// Subject = Entity (Noun)
// predicate = Relationship or Action (Verb)
// Object = Related Entity or Value (Noun)

$.User.assign.Role()
$.Order.contains.Items()
$.Team.has.Members()
$.Product.belongs.Category()

With Prepositional Phrases: $.Subject.predicate.Object.in.Thing

// Add context with prepositions
$.User.assign.Role.in.Organization()
$.Task.assign.User.in.Project()
$.Product.add.Category.in.Catalog()

// Multiple prepositional phrases
$.User.assign.Role.in.Organization.on.Team()
$.Message.send.to.User.from.Agent()

Chained Relationships

// Follow relationship chains
const result = await $.Organization.has.Teams.with.Members.where.role.equals('admin').who.work.Projects.in.Department({ deptId: 'eng' })

Parts of Speech Patterns

Semantic operations follow natural language grammar:

1. Nouns (Entities)

Entities are capitalized and represent things/concepts:

// Business entities
$.User()
$.Order()
$.Product()
$.Invoice()
$.Contract()

// Organizational entities
$.Organization()
$.Team()
$.Department()
$.Project()

// System entities
$.Event()
$.Task()
$.Workflow()
$.Agent()

2. Verbs (Actions & Relationships)

Verbs are lowercase and represent actions or relationships:

// CRUD actions
$.User.create()
$.Order.update()
$.Product.delete()
$.Team.read()

// Relationship verbs
$.User.has.Orders()
$.Order.contains.Items()
$.Team.includes.Members()
$.Product.belongs.Category()

// Business action verbs
$.Payment.process()
$.Email.send()
$.Report.generate()
$.Task.complete()
$.Agent.qualify()

3. Adjectives (Properties & Filters)

Adjectives describe properties and filter criteria:

// Property adjectives
$.User.where.active.equals(true)
$.Product.where.inStock.equals(true)
$.Order.where.status.equals('shipped')

// Comparison adjectives
$.Product.where.price.greaterThan(100)
$.User.where.age.between(18, 65)
$.Order.where.total.lessThan(50)

// Chained adjectives
$.Product.where.active.equals(true).where.price.greaterThan(10).where.inStock.equals(true)

4. Adverbs (Query Modifiers)

Adverbs modify how queries execute:

// Sorting adverbs
$.User.orderBy.createdAt.desc()
$.Product.sortBy.price.asc()

// Limiting adverbs
$.Order.limit(10)
$.User.take(5)

// Grouping adverbs
$.Order.groupBy.customer()
$.Product.groupBy.category()

// Pagination adverbs
$.User.paginate({ page: 1, perPage: 20 })

5. Prepositions (Context)

Prepositions add context and scope:

// Common prepositions
$.User.assign.Role.in.Organization // in
$.Task.assign.User.on.Project // on
$.Meeting.schedule.at.Time // at
$.Report.generate.for.Executive // for
$.Payment.process.with.Method // with
$.Data.import.from.Source // from
$.Email.send.to.User // to
$.Document.share.with.Team // with
$.Event.occur.during.Timeframe // during

GraphDL: Graph Definition Language

GraphDL extends semantic patterns for graph-based relationships:

Entity Definitions

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

// Define entity in graph
const User = graph.entity('User', {
  properties: {
    name: 'string',
    email: 'string',
    age: 'number',
  },
  relationships: {
    has: ['Order', 'Profile'],
    works: ['Organization', 'Team'],
    manages: ['Project'],
  },
})

// Semantic access
const user = await $.User.get('user-123')
const orders = await $.User.has.Orders({ userId: user.id })

Relationship Definitions

// Define relationships
graph.relationship('has', {
  from: 'User',
  to: 'Order',
  cardinality: 'one-to-many',
  inverse: 'belongs',
})

graph.relationship('works', {
  from: 'User',
  to: 'Organization',
  cardinality: 'many-to-many',
  properties: {
    role: 'string',
    startDate: 'date',
  },
})

// Use in semantic queries
const user = await $.User.get('user-123')
const orgs = await $.User.works.Organizations({ userId: user.id })

Graph Traversal

import { graph } from 'sdk.do'

// Traverse graph semantically
const results = await graph
  .from($.User.get('user-123'))
  .traverse($.User.works.Organizations)
  .traverse($.Organization.has.Teams)
  .traverse($.Team.has.Projects)
  .where($.Project.status.equals('active'))

// Multi-hop relationships
const connections = await graph.from($.User.get('user-123')).hop($.User.knows.Users, { depth: 2 }).unique()

Semantic Validation

Semantic patterns enable compile-time validation:

Type Safety

// TypeScript knows the shape
const user: User = await $.User.get('user-123')
const orders: Order[] = await $.User.has.Orders({ userId: user.id })

// Compile error: Invalid relationship
const invalid = await $.User.has.Products({ userId: user.id })
// Error: User does not have relationship 'has.Products'

// Compile error: Invalid property
await $.User.where.invalidProp.equals(true)
// Error: User entity does not have property 'invalidProp'

Relationship Validation

// Valid relationships defined in schema
graph.relationship('has', { from: 'User', to: 'Order' })

// Valid semantic query
await $.User.has.Orders({ userId: 'user-123' }) // ✓

// Invalid semantic query
await $.User.has.InvalidEntity({ userId: 'user-123' }) // ✗
// Error: No relationship 'has' from User to InvalidEntity

Semantic Linting

// ESLint plugin: eslint-plugin-dotdo-semantics

// Rule: semantic-noun-capitalization
$.user.create() // ✗ Error: Entities must be capitalized
$.User.create() // ✓

// Rule: semantic-verb-lowercase
$.User.Create() // ✗ Error: Verbs must be lowercase
$.User.create() // ✓

// Rule: semantic-relationship-exists
$.User.has.InvalidEntity() // ✗ Error: Relationship not defined
$.User.has.Orders() // ✓

Semantic Patterns in Practice

Business Logic

// Self-documenting business logic
workflow('process-order', async ({ order }) => {
  // Validate order (verb pattern)
  await $.Order.validate({ orderId: order.id })

  // Check inventory (relationship pattern)
  const items = await $.Order.contains.Items({ orderId: order.id })
  for (const item of items) {
    const inStock = await $.Product.where.inStock.equals(true).where.id.equals(item.productId)

    if (!inStock) {
      throw new Error(`Product ${item.productId} out of stock`)
    }
  }

  // Process payment (action pattern)
  await $.Payment.process({
    orderId: order.id,
    amount: order.total,
  })

  // Create shipment (creation pattern)
  await $.Shipment.create({
    orderId: order.id,
    address: order.shippingAddress,
  })

  // Notify customer (communication pattern)
  const customer = await $.Order.belongs.User({ orderId: order.id })
  await $.Email.send.to.User({
    userId: customer.id,
    template: 'order-confirmation',
    data: { order },
  })
})

Query Composition

// Complex queries remain readable
const results = await $.Organization.where.type
  .equals('enterprise')
  .where.active.equals(true)
  .has.Teams.where.size.greaterThan(5)
  .has.Members.where.role.equals('engineer')
  .who.work.Projects.where.status.equals('active')
  .where.deadline.before(nextMonth)
  .orderBy.priority.desc.limit(20)

Relationship Traversal

// Natural relationship following
const userProjects = await $.User.get('user-123').works.Organizations.has.Teams.has.Projects.where.status.equals('active')

// Inverse relationships
const projectTeam = await $.Project.get('project-456').belongs.Team.has.Members.where.role.in(['lead', 'senior'])

SDK Object Integration

Semantic patterns integrate with all 8 core SDK objects:

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

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

// API - Integration actions with semantic patterns
await api.action('github.create_issue', {
  repo: await $.Repository.get('repo-456'),
  title: 'Bug found',
})

// DB - Direct database with semantic layer
const user = await db.get('users', 'user-123') // Direct
const user2 = await $.User.get('user-123') // Semantic (preferred)

// DECIDE - Experiments with semantic targeting
const variant = await decide.get('button-test', {
  user: await $.User.get('user-123'),
})

// EVERY - Scheduled workflows with semantic patterns
every('daily at 9am', async () => {
  const reports = await $.Report.where.type.equals('daily').where.pending.equals(true)

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

// ON - Event handlers with semantic patterns
on($.Order.created, async ({ order }) => {
  await $.Workflow.start('process-order', { order })
})

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

// USER - Human functions with semantic patterns
const approval = await user.requestApproval({
  type: 'contract-review',
  entity: await $.Contract.get('contract-456'),
})

Semantic Naming Conventions

Entities (Nouns)

PascalCase: $.User, $.Order, $.Product
Singular: Use singular form ($.User not $.Users)
Descriptive: Clear, business-domain names
No abbreviations: $.Organization not $.Org

Relationships (Verbs)

camelCase: has, contains, belongs, includes
Present tense: create, update, delete (not created, updated)
Descriptive: Clear relationship meaning
Standard verbs: has, belongs, contains, includes, references

Properties (Adjectives)

camelCase: active, inStock, isPublished
Boolean prefix: is, has, can for booleans
Descriptive: Clear property meaning

Methods (Verbs)

camelCase: create, update, delete, validate
Action-oriented: Verb that describes action
Consistent: Use same verbs across entities

Core Capabilities

Semantic Triples - $.Subject.predicate.Object pattern
Parts of Speech - Nouns, Verbs, Adjectives, Adverbs, Prepositions
GraphDL - Graph definition and traversal language
Type Safety - Compile-time semantic validation
Self-Documenting - Code structure conveys meaning
Natural Language - Reads like English
SDK Integration - Works with all 8 core objects

Access Methods

SDK

TypeScript/JavaScript library with semantic patterns

await $.User.has.Orders({ userId: 'user-123' })

See SDK Documentation

CLI

Command-line with semantic query syntax

do semantic query "$.User.has.Orders" --userId user-123

See CLI Documentation

API

REST/RPC with semantic triple endpoints

curl -X POST https://api.do/v1/semantic/query -d '{"triple":"$.User.has.Orders"}'

See API Documentation

MCP

Model Context Protocol with semantic understanding

Query all orders for user using semantic pattern $.User.has.Orders

See MCP Documentation

Applies To All Primitives

functions - All functions use semantic patterns
workflows - Workflows use semantic patterns
agents - Agents use $.Agent.verb.Object pattern
data - Data operations use semantic triples

Core Concepts

graph - GraphDL implementation
schema - Entity and relationship schemas
database - Semantic layer over databases

SDK Objects (All Use Semantics)

ai - AI with semantic context
api - API actions with semantic patterns
db - Database with semantic layer
decide - Experiments with semantic targeting
every - Scheduled functions with semantic patterns
on - Event handlers with semantic patterns
send - Analytics with semantic context
user - Human functions with semantic patterns

semantics

On this page