SODEA

📘 SODEA Core API Specification

The SODEA Core API defines the foundational structure and behaviors of semantic objects (SO’s). It is not an implementation or set of endpoints, but a standardized specification describing how data and behaviors should be represented and interpreted across SODEA-compatible systems.

This specification ensures that tools like Morpheus, Fountain, or any third-party service can create, share, and process semantic objects in a consistent, interoperable way.

✳️ Object Structure

All semantic objects follow JSON-LD syntax and must include:

{
  "@context": "https://schema.sodea.org/core#",
  "@id": "urn:example:object-id",
  "@type": "CustomType"
}

Reserved Keywords

  • @context: Identifies the SODEA schema context.
  • @id: Globally unique identifier (preferably a URN or IRI).
  • @type: Describes the object’s class or role.

Additional fields are user-defined.

🔒 The _private Section

This optional section defines non-public metadata and operational features.

"_private": {
  "hooks": {...},
  "schedule": {...},
  "subscriptions": [...],
  "policies": {...}
}

Subfields:

  • hooks: Executable logic such as onEvent, onTick, mutateWith, etc.
  • schedule: Trigger timing for onTick.
  • subscriptions: Event types this object listens to.
  • policies: Access control, permissions, or role logic.

🔁 Hook Specification

Hooks are defined as executable code blocks inside _private.hooks. Supported languages include python and javascript.

"onEvent": {
  "language": "python",
  "code": "def run(obj, params, save, load, delete): ..."
}

Morpheus or other runtimes are expected to:

  • Execute the hook when triggered
  • Pass in execution context
  • Apply results to the semantic object

🔔 Event Model

Objects can:

  • Emit events (via return { trigger_event: { ... } } from hooks)
  • Subscribe to events (_private.subscriptions)
  • React to events through onEvent

Events are structured as:

{
  "eventType": "counter_limit",
  "payload": { "target": "urn:example:next-object" }
}

🧩 Object Linking

Semantic objects can link to other objects using IRIs or URNs:

"relatedTo": "urn:example:another-object"

Linked objects can be local or remote, supporting decentralized and federated systems.

🔐 Access Control (Optional)

Objects may include access policies to restrict:

  • Who can view
  • Who can modify
  • Who can execute hooks

This is defined under _private.policies.

🧪 Compatibility

Any tool that reads or writes SODEA-conformant objects:

  • Must preserve the structure defined above
  • May ignore _private if not applicable
  • Should validate key structure and @context