From 70fe892951b6d7e3ba7785b20692ec9ad3b76207 Mon Sep 17 00:00:00 2001 From: jonathanprozzi Date: Thu, 2 Apr 2026 13:12:15 -0400 Subject: [PATCH 1/2] feat: add Semantic Engineering docs section (ENG-10545) Adds three-page section covering how to structure atoms, use the enrichment system, and connect atoms with enshrined predicates. Content distilled from the intuition-data-structures repo and predicates workshop decisions for hackathon builder accessibility. Co-Authored-By: Claude Opus 4.6 (1M context) --- cspell.json | 19 +- .../semantic-engineering/_category_.json | 8 + .../semantic-engineering/data-structures.md | 277 +++++++++++++++ docs/_data/semantic-engineering/index.md | 74 ++++ docs/_data/semantic-engineering/predicates.md | 327 ++++++++++++++++++ 5 files changed, 704 insertions(+), 1 deletion(-) create mode 100644 docs/_data/semantic-engineering/_category_.json create mode 100644 docs/_data/semantic-engineering/data-structures.md create mode 100644 docs/_data/semantic-engineering/index.md create mode 100644 docs/_data/semantic-engineering/predicates.md diff --git a/cspell.json b/cspell.json index 1eff446..f155f80 100644 --- a/cspell.json +++ b/cspell.json @@ -11,6 +11,23 @@ "quickstart", "releasenotes", "waitlisted", - "htmlui" + "htmlui", + "offchain", + "onchain", + "Vitalik", + "Buterin", + "vbuterin", + "Chainlink", + "Solana", + "Crunchbase", + "Memecoins", + "Restaking", + "Satoshi", + "frontends", + "refreshable", + "TMDB", + "Brainz", + "Microdata", + "Watchlist" ] } diff --git a/docs/_data/semantic-engineering/_category_.json b/docs/_data/semantic-engineering/_category_.json new file mode 100644 index 0000000..d4de5f2 --- /dev/null +++ b/docs/_data/semantic-engineering/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Semantic Engineering", + "position": 4, + "link": { + "type": "generated-index", + "description": "How to structure atoms, enrich them with metadata, and connect them with predicates in the Intuition knowledge graph." + } +} diff --git a/docs/_data/semantic-engineering/data-structures.md b/docs/_data/semantic-engineering/data-structures.md new file mode 100644 index 0000000..fcc2bd1 --- /dev/null +++ b/docs/_data/semantic-engineering/data-structures.md @@ -0,0 +1,277 @@ +--- +title: Data Structures +sidebar_label: Data Structures +sidebar_position: 2 +description: How to structure atom data using Schema.org classifications and the enrichment system +keywords: + [ + data structures, + atom classification, + enrichment, + schema.org, + atom data, + JSON-LD, + onchain, + offchain, + ] +--- + +# Data Structures + +:::tip This page covers how to format atom data +For creating atoms onchain, see [Atom Fundamentals](../intuition-concepts/primitives/Atoms/fundamentals.md). For connecting atoms with predicates, see [Predicates](./predicates). +::: + +Every atom in Intuition needs data. The data you put in determines the atom's permanent identity — so getting the format right matters. This page covers the classification system that standardizes atom data across the ecosystem. + +## The Core Idea + +**Store minimal identity onchain. Attach rich context offchain.** + +An atom's data should contain just enough to identify and disambiguate the entity. Everything else — descriptions, images, social links, market data — comes from enrichment providers that refresh independently. + +``` +Onchain (permanent): { "@type": "Person", "name": "Vitalik Buterin" } +Offchain (refreshable): Wikipedia bio, GitHub profile, ENS records, profile photo +``` + +## Atom Classification + +Classifications define the minimal shape of an atom for each entity type. They use [Schema.org](https://schema.org/) types for universal compatibility. + +### Format + +Every classified atom follows this structure: + +```json +{ + "@context": "https://schema.org/", + "@type": "Person", + "name": "Vitalik Buterin", + "sameAs": ["https://www.wikidata.org/wiki/Q35332"] +} +``` + +The key fields: + +- `@context` — Always `"https://schema.org/"` +- `@type` — The Schema.org type (Person, Organization, SoftwareSourceCode, etc.) +- Identity fields — The minimum needed to identify the entity + +### Common Classification Examples + +#### Person + +```json +{ + "@context": "https://schema.org/", + "@type": "Person", + "name": "Vitalik Buterin", + "sameAs": ["https://www.wikidata.org/wiki/Q35332"] +} +``` + +Only `name` is required. `sameAs` links to a canonical identifier for disambiguation. + +#### Organization / Company + +```json +{ + "@context": "https://schema.org/", + "@type": "Organization", + "name": "Uniswap Labs", + "url": "https://uniswap.org" +} +``` + +#### Software + +```json +{ + "@context": "https://schema.org/", + "@type": "SoftwareSourceCode", + "name": "Foundry", + "codeRepository": "https://github.com/foundry-rs/foundry" +} +``` + +#### Ethereum Account + +```json +{ + "chainId": "1", + "address": "0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48" +} +``` + +Blockchain-native types use their natural identifiers rather than Schema.org. + +#### Defined Term (Tags, Concepts, Predicates) + +```json +{ + "@context": "https://schema.org/", + "@type": "DefinedTerm", + "name": "Knowledge Graph", + "description": "A structured, semantic network of entities and relationships" +} +``` + +`DefinedTerm` is important — it's the type used for tags, concepts, and enshrined predicates. + +### All Classification Types + +| Type | Schema.org `@type` | Required Fields | +| --- | --- | --- | +| Person | `Person` | `name` | +| Company | `Organization` | `name`, `url` | +| Software | `SoftwareSourceCode` | `name`, `codeRepository` | +| Location | `Place` | `name` | +| Product | `Product` | `name` | +| Event | `Event` | `name` | +| Article | `Article` | `name` | +| Book | `Book` | `name` | +| Movie | `Movie` | `name` | +| Music Recording | `MusicRecording` | `name`, `byArtist` | +| Defined Term | `DefinedTerm` | `name` | +| Ethereum Account | *(custom)* | `chainId`, `address` | +| Ethereum ERC20 | *(custom)* | `chainId`, `address` | +| Smart Contract | *(custom)* | `chainId`, `address` | + +For the full catalog of all 36 classification types, see [classifications/](https://github.com/0xIntuition/intuition-data-structures/tree/main/classifications) in the data structures repo. + +### Why Minimal? + +Each additional field in an atom is permanent onchain data. Mutable information belongs in enrichment: + +| Field | Where It Goes | Why | +| --- | --- | --- | +| Name | Atom (onchain) | Stable identity — rarely changes | +| Profile photo | Enrichment (offchain) | Changes frequently | +| Bio/description | Enrichment (offchain) | Changes over time | +| Social links | Enrichment (offchain) | Platforms come and go | +| Market cap | Enrichment (offchain) | Changes every second | + +## Atom Enrichment + +Enrichment is the context layer — refreshable, offchain metadata attached to classified atoms. It provides everything a frontend needs without bloating atom payloads. + +### Enrichment Envelope + +All enrichment data uses a standard envelope: + +```json +{ + "artifact_type": "wikipedia", + "data": { + "summary": "Canadian-Russian computer programmer and co-founder of Ethereum", + "image": "https://upload.wikimedia.org/example.jpg" + }, + "meta": { + "pluginId": "wikipedia", + "provider": "wikipedia", + "fetchedAt": "2026-02-26T12:00:00Z", + "sourceUrl": "https://en.wikipedia.org/wiki/Vitalik_Buterin", + "confidence": 0.98 + } +} +``` + +The `meta` block tells you where the data came from, when it was fetched, and how confident the source is. + +### How Enrichment Works + +1. An atom is created onchain with minimal classification data +2. Backend workers detect the atom and run enrichment providers +3. Each provider returns an artifact with its specific data +4. Clients compose identity (onchain) + enrichment (offchain) at query time + +This means a single `Person` atom can have enrichment from Wikipedia, GitHub, Twitter, ENS, and more — all updated independently. + +### Enrichment Providers + +The system supports 37+ enrichment providers across categories: + +| Category | Providers | +| --- | --- | +| Knowledge | Wikipedia, Wikidata, Dictionary | +| Developer | GitHub, NPM, arXiv | +| Blockchain | CoinGecko, Etherscan, ENS, NFT Metadata | +| Media | Spotify, Apple Music, YouTube, Vimeo, TMDB, MusicBrainz | +| Social | Twitter Profile, Reddit Post | +| Web | OpenGraph, oEmbed, Favicon, Microdata | +| Business | Crunchbase, Company Profile, Product Listing | +| Location | Geocode, Places | +| AI | AI Summary, AI Entities | + +For the full enrichment specification, see [enrichment/](https://github.com/0xIntuition/intuition-data-structures/tree/main/enrichment) in the data structures repo. + +## End-to-End Example + +Here's the full flow for creating a `Person` atom: + +### 1. Input + +A user submits a URL: `https://en.wikipedia.org/wiki/Vitalik_Buterin` + +### 2. Classification (Onchain) + +The system classifies this as a Person and stores the minimal identity: + +```json +{ + "@context": "https://schema.org/", + "@type": "Person", + "name": "Vitalik Buterin", + "sameAs": ["https://www.wikidata.org/wiki/Q35332"] +} +``` + +### 3. Enrichment (Offchain) + +Providers attach context artifacts: + +```json +// Wikipedia enrichment +{ + "artifact_type": "wikipedia", + "data": { + "summary": "Canadian-Russian programmer, co-founder of Ethereum", + "image": "https://upload.wikimedia.org/..." + }, + "meta": { "provider": "wikipedia", "fetchedAt": "2026-02-26T12:00:00Z" } +} + +// GitHub enrichment +{ + "artifact_type": "github", + "data": { + "username": "vbuterin", + "repos": 42, + "followers": 12500 + }, + "meta": { "provider": "github", "fetchedAt": "2026-02-26T12:00:00Z" } +} +``` + +### 4. Query-Time Composition + +Clients compose the full picture at read time: + +- Stable atom identity from onchain data +- Latest enrichment from backend services +- Rich UX without bloated atom payloads + +## Design Principles + +1. **Minimal by default** — Keep only the smallest viable identity payload in base atoms +2. **Durable over complete** — Prefer fields that are stable over time +3. **Separate identity and context** — Onchain atom = identity, offchain enrichment = context +4. **Extensible by artifacts** — New metadata sources don't require changing atom identity +5. **Schema.org aligned** — Universal compatibility with web standards + +## Next Steps + +- **[Predicates](./predicates)** — Learn how to connect atoms with the canonical predicate vocabulary +- **[Atom Fundamentals](../intuition-concepts/primitives/Atoms/fundamentals.md)** — How to create atoms onchain +- **[intuition-data-structures repo](https://github.com/0xIntuition/intuition-data-structures)** — Full specification for all classification and enrichment types diff --git a/docs/_data/semantic-engineering/index.md b/docs/_data/semantic-engineering/index.md new file mode 100644 index 0000000..29d2498 --- /dev/null +++ b/docs/_data/semantic-engineering/index.md @@ -0,0 +1,74 @@ +--- +title: Semantic Engineering +sidebar_label: Overview +sidebar_position: 1 +description: How Intuition structures knowledge — from minimal onchain atoms to rich offchain context to predicate-connected relationships +keywords: + [ + semantic engineering, + data structures, + classifications, + enrichment, + predicates, + knowledge graph, + atoms, + triples, + ] +--- + +# Semantic Engineering + +Semantic engineering is how you design the data that goes into Intuition's knowledge graph. Every piece of knowledge follows a three-layer pattern: + +1. **Identity (onchain)** — A minimal, durable atom stored on the blockchain +2. **Context (offchain)** — Rich metadata attached and refreshed independently +3. **Relationships (predicates)** — Typed connections between atoms via triples + +This section covers the practical "what goes where" so you can build effectively on the protocol. + +## The Three-Layer Model + +``` +┌─────────────────────────────────────────────────┐ +│ Layer 3: Relationships (Predicates) │ +│ "How atoms connect to each other" │ +│ (I, follow, Vitalik) (Aave, uses, Chainlink) │ +├─────────────────────────────────────────────────┤ +│ Layer 2: Context (Enrichment) │ +│ "Rich metadata, refreshed offchain" │ +│ Wikipedia summaries, CoinGecko data, images │ +├─────────────────────────────────────────────────┤ +│ Layer 1: Identity (Classification) │ +│ "Minimal atom data, stored onchain" │ +│ { "@type": "Person", "name": "Vitalik" } │ +└─────────────────────────────────────────────────┘ +``` + +### Why separate identity from context? + +Atoms are permanent onchain. If you pack mutable data into an atom (images, descriptions, social links), it becomes stale and expensive to maintain. Instead: + +- **Onchain atom** = just enough to identify and disambiguate the entity +- **Offchain enrichment** = everything else, refreshed as better data becomes available +- **Composed at read time** for product UX and search + +This means a `Person` atom only needs `name` — the Wikipedia bio, profile photo, and social links come from enrichment providers that update independently. + +## How It Connects to Primitives + +If you've read the [Primitives](../intuition-concepts/primitives/index.md) section, you know about Atoms, Triples, and Signals. Semantic engineering builds on those foundations: + +| Primitive | Semantic Engineering Layer | +| --------- | --------------------------------------------------- | +| Atoms | **Classifications** define what data goes in an atom | +| Triples | **Predicates** define the relationship vocabulary | +| Signals | Deposits on triples express conviction in claims | + +## What's in This Section + +- **[Data Structures](./data-structures.md)** — How to format atom data using Schema.org classifications and the enrichment system +- **[Predicates](./predicates.md)** — The canonical predicate catalog, usage patterns, and how to avoid common mistakes + +## Full Reference + +These docs distill the most important patterns for builders. For the complete specification — all 36 classification types, 37 enrichment providers, and architectural deep dives — see the [intuition-data-structures](https://github.com/0xIntuition/intuition-data-structures) repository. diff --git a/docs/_data/semantic-engineering/predicates.md b/docs/_data/semantic-engineering/predicates.md new file mode 100644 index 0000000..668bf2f --- /dev/null +++ b/docs/_data/semantic-engineering/predicates.md @@ -0,0 +1,327 @@ +--- +title: Predicates +sidebar_label: Predicates +sidebar_position: 3 +description: The canonical predicate catalog, usage patterns, and common mistakes to avoid when building with Intuition triples +keywords: + [ + predicates, + triples, + knowledge graph, + enshrined predicates, + semantic relationships, + I atom, + depositional, + attributive, + ] +--- + +# Predicates + +:::tip This page covers how atoms relate to each other +For what goes inside an atom, see [Data Structures](./data-structures). For creating triples onchain, see [Triple Fundamentals](../intuition-concepts/primitives/Triples/fundamentals.md). +::: + +Predicates are the relationship vocabulary of the Intuition knowledge graph. When you create a triple like `(I, follow, Vitalik)`, the predicate `follow` defines how the subject and object relate. **Enshrined predicates** are the canonical set supported across the ecosystem — SDK, indexer, API, and frontends. + +## Key Concepts + +1. **Triples** are `(Subject, Predicate, Object)` — three atoms that form a knowledge claim +2. **Predicates** define the relationship between subject and object +3. **Enshrined predicates** are the canonical predicates supported by the Intuition ecosystem +4. **The `I` atom** is a singleton atom with data `"I"` — the universal subject for first-person claims +5. **Vaults** are created per triple — deposits express conviction, TVL is the signal + +## The `I` Atom Pattern + +This is the most important concept. Getting it wrong fragments your markets. + +### The Problem + +``` +BAD: (Alice, follow, Vitalik) → vault with 1 depositor +BAD: (Bob, follow, Vitalik) → vault with 1 depositor +BAD: (Carol, follow, Vitalik) → vault with 1 depositor +Result: 3 tiny vaults. No signal. + +GOOD: (I, follow, Vitalik) → vault with 3 depositors +Result: 1 deep vault. TVL = aggregate follow signal. +``` + +The difference is between **a thousand puddles and a lake**. Deep markets produce better price signals. Shallow markets produce noise. + +### The Rule + +**If the depositor IS the claim-maker (first-person claim), always use `I` as the subject.** + +When Alice deposits on `(I, follow, Vitalik)`, the blockchain records her address. The identity of "I" is resolved per-depositor from the vault's deposit ledger. + +### When NOT to Use `I` + +Use a specific entity as subject when: + +- **Factual claims**: `(Ethereum, created by, Vitalik)` — a fact about the world +- **Comparisons**: `(Rust, better than, Solidity)` — comparing two entities +- **Collections**: `(DeFi Blue Chips, contain, Aave)` — curating a list + +### Decision Tree + +``` +Is the depositor making a claim about themselves? +├── YES → Subject = I +│ (I, follow, Vitalik) +│ (I, bullish on, Ethereum) +│ (I, trust, Trail of Bits) +└── NO → Is it a comparison between two things? + ├── YES → Subject = the entity being compared + │ (Rust, better than, Solidity) + └── NO → Subject = the entity the claim is about + (Ethereum, created by, Vitalik) + (DeFi Blue Chips, contain, Aave) +``` + +## Three Classes of Triples + +### Depositional Triples (First-Person Markets) + +Subject is `I`. Anyone deposits to make the claim about themselves. The vault's depositor list = everyone who holds this position. + +``` +(I, follow, Vitalik) → "I follow Vitalik" +(I, bullish on, Ethereum) → "I'm bullish on ETH" +(I, trust, Trail of Bits) → "I trust this auditor" +(I, expert in, ZK proofs) → "I claim expertise in ZK" +``` + +**Reading the data:** Depositor count = headcount. TVL = capital-weighted conviction. + +### Comparative Triples (Opinion Markets) + +Subject is a real entity. Deposits mean agreement with the comparison. + +``` +(Rust, better than, Solidity) → depositors agree Rust > Solidity +(Solana, alternative to, Ethereum) → depositors agree these are substitutes +(Uniswap v4, supersede, Uniswap v3) → depositors agree v4 replaces v3 +``` + +**Reading the data:** Compare `(A, better than, B)` TVL with `(B, better than, A)` TVL for the full picture. The TVL ratio is the market's verdict. + +### Attributive Triples (Factual Claims) + +Subject is a specific entity. The triple asserts a fact. Deposits mean "I agree this is true." + +``` +(Ethereum, created by, Vitalik) → factual attribution +(Aave v3, audited by, Trail of Bits) → factual audit claim +(USDC, pegged to, USD) → factual economic relationship +``` + +**Reading the data:** TVL = market confidence that the claim is accurate. + +## Predicate Catalog + +Enshrined predicates are organized into categories. These use **base verb form** (not third-person) because they read with the `I` subject: "I follow," not "I follows." + +### Identity and Classification (1-8) + +| Predicate | Intent | Example Triple | +| --- | --- | --- | +| `has type` | Type classification | `(Uniswap, has type, DEX)` | +| `same as` | Cross-representation identity | `(ETH, same as, Ether)` | +| `alias of` | Alternative name | `(BTC, alias of, Bitcoin)` | +| `instance of` | Class membership | `(USDC, instance of, stablecoin)` | +| `subclass of` | Taxonomy hierarchy | `(DEX, subclass of, exchange)` | +| `has tag` | Free-form tagging | `(Aave, has tag, lending)` | +| `has category` | Categorical grouping | `(Chainlink, has category, oracle)` | + +### Social and Reputation (9-18) + +| Predicate | Intent | Example Triple | +| --- | --- | --- | +| `follow` | Subscription | `(I, follow, Vitalik)` | +| `like` | Lightweight positive signal | `(I, like, Ethereum)` | +| `endorse` | Strong public support | `(I, endorse, EIP-4844)` | +| `trust` | Positive trust assertion | `(I, trust, Trail of Bits)` | +| `distrust` | Negative trust assertion | `(I, distrust, Scam Project)` | +| `recommend` | Active recommendation | `(I, recommend, Hardhat)` | +| `vouch for` | Personal credibility stake | `(I, vouch for, Bob)` | + +### Curation and Containment (19-25) + +| Predicate | Intent | Example Triple | +| --- | --- | --- | +| `contain` | Collection membership | `(L1 Watchlist, contain, Ethereum)` | +| `curated by` | Collection ownership | `(DeFi Blue Chips, curated by, Alice)` | +| `pinned in` | Highlighted in collection | `(Ethereum, pinned in, L1 Watchlist)` | +| `depend on` | Functional dependency | `(Arbitrum, depend on, Ethereum)` | +| `alternative to` | Substitutability | `(Solana, alternative to, Ethereum)` | + +### Authorship and Contribution (26-31) + +| Predicate | Intent | Example Triple | +| --- | --- | --- | +| `created by` | Origin attribution | `(Ethereum, created by, Vitalik)` | +| `authored by` | Written content | `(Whitepaper, authored by, Satoshi)` | +| `contributed to` | Contribution record | `(Alice, contributed to, OpenZeppelin)` | +| `forked from` | Divergent copy | `(Sushiswap, forked from, Uniswap)` | +| `derived from` | Adaptation | `(Optimism, derived from, Ethereum)` | + +### Sentiment and Opinion (51-58) + +| Predicate | Intent | Example Triple | +| --- | --- | --- | +| `agree with` | Alignment | `(I, agree with, EIP-4844)` | +| `disagree with` | Opposition | `(I, disagree with, PoW Revival)` | +| `bullish on` | Positive conviction | `(I, bullish on, Ethereum)` | +| `bearish on` | Negative conviction | `(I, bearish on, Memecoins)` | +| `skeptical of` | Cautious doubt | `(I, skeptical of, Restaking)` | + +### Comparison and Ranking (59-66) + +| Predicate | Intent | Example Triple | +| --- | --- | --- | +| `better than` | Subjective superiority | `(Rust, better than, Solidity)` | +| `equivalent to` | Functional parity | `(USDC, equivalent to, USDT)` | +| `compete with` | Market competition | `(Uniswap, compete with, Curve)` | +| `supersede` | Replacement | `(Uniswap v4, supersede, Uniswap v3)` | + +### Provenance and Evidence (75-82) + +| Predicate | Intent | Example Triple | +| --- | --- | --- | +| `verified by` | Third-party verification | `(Contract, verified by, CertiK)` | +| `audited by` | Security audit | `(Aave v3, audited by, Trail of Bits)` | +| `evidenced by` | Supporting proof | `(Claim, evidenced by, On-chain Proof)` | + +For the complete catalog of all 100 predicates across 12 categories, see [predicate-analysis.md](https://github.com/0xIntuition/intuition-data-structures/blob/main/predicates/1-predicate-analysis.md) in the data structures repo. + +## Market Patterns + +Each predicate has a market pattern that determines how your app should handle it. + +### Depositional (Subject = `I`) + +Everyone deposits on the same triple. One vault, many depositors. + +``` +(I, follow, Vitalik) ← one vault, many depositors +(I, bullish on, Ethereum) ← one vault, many depositors +``` + +**Your app should:** Find the existing `(I, predicate, object)` triple and deposit on it. Never create `(UserName, follow, Vitalik)` — this fragments the market. + +### Attributive (Subject = specific entity) + +The triple asserts a fact. Deposits mean "I agree this is true." + +``` +(Ethereum, created by, Vitalik) ← factual claim +(DeFi Blue Chips, contain, Aave) ← curation fact +``` + +**Your app should:** Create the `(entity, predicate, object)` triple if it doesn't exist, then deposit. + +### Comparative (Subject = entity being ranked) + +The triple is a comparison. Check for both the triple and its inverse. + +``` +(Rust, better than, Solidity) ← opinion market +``` + +**Your app should:** The TVL ratio between `(A, better than, B)` and `(B, better than, A)` is the signal. + +## Common Mistakes + +### 1. Fragmenting the market + +```typescript +// BAD — creates a unique vault only Alice would deposit on +createTriple({ subject: aliceAtomId, predicate: FOLLOW, object: vitalikAtomId }) + +// GOOD — everyone deposits on the same vault +createTriple({ subject: I_SUBJECT, predicate: FOLLOW, object: vitalikAtomId }) +``` + +### 2. Using UI concepts as predicates + +```typescript +// BAD — "bookmark" and "star" are UI labels, not semantic predicates +createTriple({ subject: I_SUBJECT, predicate: 'bookmark', object: uniswapAtomId }) + +// GOOD — "like" is the semantic concept. Render it as a bookmark icon in your UI. +createTriple({ subject: I_SUBJECT, predicate: LIKE, object: uniswapAtomId }) +``` + +### 3. Using third-person verb forms + +```typescript +// BAD — "follows" and "follow" hash to different atom IDs +createTriple({ predicate: 'follows' }) + +// GOOD — always use base form +createTriple({ predicate: FOLLOW }) // "follow" +``` + +Predicates use base verb form because they read with the `I` subject: "I follow Vitalik," not "I follows Vitalik." + +### 4. Creating custom predicates for covered concepts + +Before creating a custom predicate, check if an enshrined one covers your use case: + +| You want to express | Use this predicate | +| --- | --- | +| User saves/bookmarks something | `like` | +| User subscribes to updates | `follow` | +| User rates something positively | `like` or `endorse` | +| User adds item to a list | `contain` (collection as subject) | +| User tags something | `has tag` | +| User thinks X is better than Y | `better than` | +| User expresses positive outlook | `bullish on` | + +### 5. Wrong triple direction + +``` +BAD: (Vitalik, authored by, Ethereum Whitepaper) ← backwards +GOOD: (Ethereum Whitepaper, authored by, Vitalik) ← the work was authored by the person + +BAD: (Alice, curated by, DeFi Blue Chips) ← backwards +GOOD: (DeFi Blue Chips, curated by, Alice) ← the collection was curated by Alice +``` + +### 6. Missing paired markets + +For opinion predicates, ensure both sides exist: + +``` +INCOMPLETE: (I, bullish on, Ethereum) ← exists + (I, bearish on, Ethereum) ← doesn't exist + +COMPLETE: (I, bullish on, Ethereum) ← exists + (I, bearish on, Ethereum) ← also exists +``` + +The ratio between paired markets is the signal. + +## Predicate Format: DefinedTerm Objects + +Enshrined predicates are moving from raw strings to `DefinedTerm` objects — the same Schema.org classification used for other atoms: + +```json +{ + "@context": "https://schema.org/", + "@type": "DefinedTerm", + "name": "follow", + "description": "Unidirectional subscription — the depositor follows the object entity" +} +``` + +This makes predicates self-describing and consistent with the rest of the classification system. The SDK handles the transition — always use SDK constants rather than raw strings. + +## Next Steps + +- **[Data Structures](./data-structures)** — How to format the atom data that predicates connect +- **[Triple Fundamentals](../intuition-concepts/primitives/Triples/fundamentals.md)** — Creating triples onchain +- **[Integration Partner Guide](https://github.com/0xIntuition/intuition-data-structures/blob/main/predicates/7-predicate-integration-partner-guide.md)** — Full implementation guide for builders +- **[Predicate Catalog](https://github.com/0xIntuition/intuition-data-structures/blob/main/predicates/1-predicate-analysis.md)** — Complete catalog of all 100 predicates From 17688d3e6a3b58962604b6c587ca0638f1f1889e Mon Sep 17 00:00:00 2001 From: jonathanprozzi Date: Thu, 2 Apr 2026 13:56:16 -0400 Subject: [PATCH 2/2] fix: add icon and reposition Semantic Engineering in sidebar MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Place section after Tutorials (pos 7) and bump GraphQL API to pos 8. Add 🧬 emoji to match sidebar icon convention. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/_data/graphql-api/_category_.json | 2 +- docs/_data/semantic-engineering/_category_.json | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/_data/graphql-api/_category_.json b/docs/_data/graphql-api/_category_.json index d493912..8248f21 100644 --- a/docs/_data/graphql-api/_category_.json +++ b/docs/_data/graphql-api/_category_.json @@ -1,6 +1,6 @@ { "label": "⛬ GraphQL API", - "position": 7, + "position": 8, "link": { "type": "generated-index", "description": "Comprehensive guide to use the Intuition GraphQL API for data fetching and mutations" diff --git a/docs/_data/semantic-engineering/_category_.json b/docs/_data/semantic-engineering/_category_.json index d4de5f2..ed9fd25 100644 --- a/docs/_data/semantic-engineering/_category_.json +++ b/docs/_data/semantic-engineering/_category_.json @@ -1,6 +1,6 @@ { - "label": "Semantic Engineering", - "position": 4, + "label": "🧬 Semantic Engineering", + "position": 7, "link": { "type": "generated-index", "description": "How to structure atoms, enrich them with metadata, and connect them with predicates in the Intuition knowledge graph."