Introduction to Semantic Objects (SOs)

Semantic Objects (SOs) are the foundation of SODEA’s architecture. They represent units of meaning—encapsulated pieces of data, logic, and relationships—designed to power modular, extensible, and dynamic systems.

At their essence, SOs are structured JSON-LD documents that can carry not only values and links, but also behavior and internal rules. This makes them fundamentally different from traditional data records.

Why Semantic Objects?

SOs are built to address a core limitation of modern systems: rigid schemas and disconnected logic. By contrast, SOs offer:

Self-describing data – Every SO carries its own schema (@context) and type definition (@type)
Portable knowledge – SOs can be stored, shared, and moved without external dependencies
Executable logic – Hooks embedded in the SO allow it to react to events, time, and conditions
Linked semantics – SOs form meaningful graphs through references, enabling emergent structures and insight

In short, SOs blend data, behavior, and relationships into a single, consistent object model.

Anatomy of an SO

Here's an example of a simple SO:

{
  "@context": "https://schema.sodea.org/core#",
  "@id": "urn:demo:note",
  "@type": "Note",
  "title": "Welcome to SODEA",
  "body": "This is a semantic object.",
  "_private": {
    "createdBy": "admin"
  }
}

Key elements:

@context: declares the schema or vocabulary used
@id: a unique identifier (URN or URL)
@type: the class or type of the object
title, body: custom fields—can follow standards or be domain-specific
_private: contains internal metadata, including hooks and configuration

The Power of `_private`

The _private section is optional but powerful. It allows an SO to carry logic with it:

Hooks: Small, language-defined functions triggered by events or schedules
Subscriptions: Types of events this SO listens for
Schedule: Defines timers, such as every 1s, to trigger periodic actions
Metadata: Hidden configuration like permissions, creators, or audit fields

This turns a Semantic Object from a passive container into an active agent.

Executable Behavior

SOs can contain Python or JavaScript code snippets, allowing them to react and evolve:

"_private": {
  "hooks": {
    "onTick": {
      "language": "python",
      "code": "def run(obj, params, save, load, delete): obj['counter'] += 1; return obj"
    }
  },
  "schedule": { "interval": "5s" }
}

The above SO will increment its counter field every 5 seconds. This kind of embedded autonomy makes SOs ideal for building decentralized intelligent agents.

Graph-Ready by Default

Because every SO uses JSON-LD, it's inherently compatible with graph structures. For example:

"assignedTo": {
  "@id": "urn:user:alice"
}

This allows a task to reference a user—creating a navigable, queryable relationship with meaning.

SOs can represent:

People, organizations, locations
Workflows, devices, records
Policies, permissions, goals
Anything with semantic value

Benefits of Using SOs

Capability	Description
✅ Portability	SOs are self-contained and can be stored anywhere
✅ Linkability	SOs form a navigable graph of knowledge
✅ Executability	Hooks make SOs active components
✅ Composability	SOs can be combined to model complex systems
✅ Semantic alignment	Everything is grounded in shared schemas

Next in the Journey

SOs are a new paradigm: closer to living systems than dead data.

To get started:

Dive in and build systems that are readable, adaptable, and intelligent—one object at a time.