IIP-1: Onchain Atom Classification and Offchain Enrichment
To scale Intuition, a global onchain social knowledge graph, we need to expand upon the “things” we can contextualize and reason about.
I am proposing new Atom Classification and Atom Enrichment data structures to help with that goal. Below is the proposed data structures, examples and reasons why we should adopt this approach.
You can find the proposed data structures in the Intuition Data Structures repo.
Github: https://github.com/0xIntuition/intuition-data-structures
Summary
IIP-1 proposes a simple rule for Intuition data structures:
- Keep onchain atoms minimal and durable.
- Move rich, changing metadata into offchain enrichment artifacts.
The goal is to make atoms easy to create, stable over time, and scalable across the knowledge graph.
Why This Matters
If we store too much data in base atoms, it becomes stale quickly. Descriptions change, URLs move, and media disappears.
Instead, the atom should contain only the smallest viable representation of an idea, such as a person, place, thing, company, or software project. Additional context can be attached later as enrichment.
This keeps the core graph clean while still supporting rich experiences in apps and APIs.
Design Principles
- Minimal by default: every atom starts with only required identifying fields.
- Durability first: prefer fields that are less likely to change over time.
- Separation of concerns:
- On-chain atom = identity
- Off-chain enrichment = context
- Composable growth: add metadata as artifacts without mutating the core identity model.
Scope of IIP-1
IIP-1 introduces:
- Atom classification structures for flat, first-class categories.
- Enrichment envelope structures for attaching metadata artifacts offchain.
- A standard flow from URL input to classified atom to enriched entity.
Flat Classification Model
IIP-1 treats each schema type as a top-level classification in docs and folder structure.
This means we do not group types under umbrella labels like “Song” or “Ethereum” in the classification catalog. For example:
MusicRecording,MusicAlbum, andMusicGroupare separate first-class classifications.EthereumAccount,EthereumSmartContract, andEthereumERC20are separate first-class classifications.
Minimal Atom Classification
Atoms are classified using Schema.org types where applicable (plus protocol-specific types like Ethereum), with only a minimal subset of fields stored in the base atom.
Person (Person)
{
"@context": "https://schema.org/",
"@type": "Person",
"name": "Brad Pitt",
"sameAs": ["https://www.wikidata.org/wiki/Q35332"]
}
Location (Place)
{
"@context": "https://schema.org/",
"@type": "Place",
"name": "Golden Gate Bridge",
"address": "San Francisco, CA"
}
Thing (Thing)
{
"@context": "https://schema.org/",
"@type": "Thing",
"name": "Apple"
}
Company (Organization)
{
"@context": "https://schema.org/",
"@type": "Organization",
"name": "OpenAI",
"url": "https://openai.com"
}
Software (SoftwareSourceCode)
{
"@context": "https://schema.org/",
"@type": "SoftwareSourceCode",
"name": "Bun",
"codeRepository": "https://github.com/oven-sh/bun"
}
Music Recording (MusicRecording)
{
"@context": "https://schema.org/",
"@type": "MusicRecording",
"name": "Bohemian Rhapsody",
"byArtist": "Queen"
}
Music Album (MusicAlbum)
{
"@context": "https://schema.org/",
"@type": "MusicAlbum",
"name": "A Night at the Opera",
"byArtist": "Queen"
}
Music Group (MusicGroup)
{
"@context": "https://schema.org/",
"@type": "MusicGroup",
"name": "Queen"
}
Ethereum Account (EthereumAccount)
{
"address": "0x1234567890abcdef1234567890abcdef12345678"
}
Ethereum Smart Contract (EthereumSmartContract)
{
"chainId": "1",
"address": "0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
}
Ethereum ERC20 (EthereumERC20)
{
"chainId": "1",
"address": "0xA0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
"name": "USD Coin",
"symbol": "USDC",
"decimals": "6"
}
Offchain Enrichment Artifacts
Enrichment artifacts attach additional metadata to atoms. These artifacts are:
- offchain
- provider-specific
- replaceable and refreshable
- linked to a canonical atom identity
Generic enrichment envelope:
{
"artifact_type": "<classification_slug>",
"data": {},
"meta": {
"pluginId": "<plugin_slug>",
"provider": "<provider_name>",
"fetchedAt": "<iso_datetime>",
"sourceUrl": "<source_url_if_available>",
"confidence": "<number_0_to_1_if_available>"
}
}
Example enrichment for Brad Pitt:
{
"artifact_type": "person",
"data": {
"image": "https://upload.wikimedia.org/example.jpg",
"description": "American actor and film producer",
"notableWorks": ["Fight Club", "Se7en", "Moneyball"]
},
"meta": {
"pluginId": "wikidata",
"provider": "wikidata",
"fetchedAt": "2026-02-26T12:00:00Z",
"sourceUrl": "https://www.wikidata.org/wiki/Q35332",
"confidence": 0.98
}
}
URL to Atom to Enrichment Flow
Step 1: Input URL
User submits a URL:
https://en.wikipedia.org/wiki/Brad_Pitt
Step 2: Classification
Classifier resolves the canonical type and minimal identity fields:
{
"type": "Person",
"data": {
"@context": "https://schema.org/",
"@type": "Person",
"name": "Brad Pitt",
"sameAs": ["https://www.wikidata.org/wiki/Q35332"]
}
}
Step 3: Atom Creation (Onchain)
Only the minimal atom payload is committed onchain.
Step 4: Enrichment (Offchain)
Background workers fetch provider metadata and attach artifacts to the atom in backend systems.
Step 5: Query-Time Composition
Clients query both:
- the stable onchain atom identity
- current offchain enrichment artifacts
This gives users rich UI context without bloating onchain data.
Benefits
- Scalability: smaller atoms mean faster indexing and less storage pressure.
- Stability: core identity data does not need constant updates.
- Flexibility: enrichment can evolve independently by provider and use case.
- Interoperability: schema-based typing keeps classification predictable.
Non-Goals
- Storing every available metadata field directly in base atoms.
- Defining a single permanent enrichment provider format.
- Requiring enrichment to exist before an atom can be created.
Initial Classification Coverage
IIP-1 starts with:
ThingPersonOrganization(Company)Place(Location)ProductServiceSoftwareSourceCodeMusicRecordingMusicAlbumMusicGroupBookArticleSocialMediaPostingImageObjectVideoObjectMovieTVSeriesEventDefinedTermEthereumAccountEthereumSmartContractEthereumERC20
Open Questions for Community Feedback
- Which identity fields should be considered acceptable optional disambiguators per type?
- Should
sameAsbe recommended for all types, or only when strong canonical sources exist? - What artifact retention and refresh strategy should we standardize for enrichment?
- Should we define confidence thresholds for automatically accepted enrichment artifacts?
Proposed Next Steps
- Align classification docs and plugins to a single minimal-field reference table.
- Add validation and examples for URL classification outputs.
- Publish recommended enrichment provider mappings by category.
- Open implementation and migration checklist for services consuming enriched atoms.
Call for Feedback
Please review this proposal with a focus on:
- whether the minimal atom philosophy is clear and practical
- whether the current field sets are truly minimal
- where classification and enrichment boundaries should be tightened
If this direction is accepted, future IIPs can define refinement rules per category and provider.