@soulid/core

TypeScript types and validation for SOUL ID Soul Documents.

Install

npm install @soulid/core

Usage

Types

import type { SoulDocument, SoulId } from '@soulid/core'

const doc: SoulDocument = {
  soul_id: 'soulid:rasputina:v1:001',
  name: 'Rasputina',
  archetype: 'assistant',
  purpose: 'Personal AI assistant with memory and tools',
  values: ['honesty', 'resourcefulness', 'privacy'],
  capabilities: ['web_search', 'code', 'memory'],
  memory: { type: 'persistent', backend: 'file' },
  lineage: { origin: 'soulid:rasputina:v1' }
}

Validation

import { validate, parse } from '@soulid/core'

// Validate — returns { valid, errors }
const result = validate(doc)
if (!result.valid) {
  console.error(result.errors)
}

// Parse — throws on invalid input, returns typed SoulDocument
const trusted = parse(jsonString)

soul_id helpers

import { isSoulId, parseSoulId, createSoulId, generateInstance } from '@soulid/core'

isSoulId('soulid:rasputina:v1:001')       // true
isSoulId('invalid')                        // false

parseSoulId('soulid:rasputina:v1:001')
// { namespace: 'soulid', archetype: 'rasputina', version: 'v1', instance: '001' }

createSoulId('soulid', 'scout', 'v1', '001')  // 'soulid:scout:v1:001'

generateInstance()  // e.g. 'a3f9c1' — random 6-char hex

API Reference

| Export | Description | |---|---| | SoulDocument | Full Soul Document type (v0.1–v0.6) | | SoulId | string alias for soul_id | | validate(doc) | Validate any value → { valid, errors } | | parse(input) | Parse JSON string or object, throw if invalid | | isSoulId(str) | Type guard — checks soul_id format | | parseSoulId(str) | Parse soul_id into { namespace, archetype, version, instance } | | createSoulId(...) | Build a soul_id from parts | | generateInstance() | Random 6-char hex instance identifier |

Spec

Full specification: soulid.io/docs

• v0.1 — Identity (soul_id format, Soul Document)
• v0.2 — Ownership & signatures (owner, signature, trust)
• v0.3 — Runtime Adapters (runtime_hints)
• v0.4 — Registry (resolve, publish, discover)
• v0.5 — Ecosystem (CLI, SDK)
• v0.6 — Decentralization (IPFS, DID, on-chain)

License

MIT — soulid.io