Skip to content

README.md

Latest commit

 

History

History
127 lines (87 loc) · 3.89 KB

README.md

File metadata and controls

127 lines (87 loc) · 3.89 KB

Semantic Overlay

This directory provides the JSON-LD and Hydra semantic overlay for the SourceOS/SociOS specification. These files make the schema types and REST API self-describing to Linked Data tooling.

Files

File Purpose
context.jsonld JSON-LD @context mapping schema type names to stable IRIs under https://schemas.srcos.ai/v2/
hydra.jsonld A hydra:ApiDocumentation document describing the REST API's supported classes and operations
fog-vocabulary.jsonld Additive fog vocabulary seed for FogVault / FogCompute types and key predicates
agent-machine-model-carry-context.jsonld Additive context slice for SourceOS model carry and Agent Machine runtime facts/receipts
agent-machine-model-carry-hydra.jsonld Additive Hydra slice for SourceOS model carry and Agent Machine runtime classes

Recent additions — Agent Machine / Model Carry vocabulary

The Agent Machine / Model Carry slice currently contributes an additive semantic vocabulary covering:

  • SourceOSModelCarryRef
  • InferenceProvider
  • ModelResidency
  • PlacementFact
  • AgentMachineReceipt

This vocabulary is intentionally staged as additive slice files so it can be reviewed independently before being folded into the global context.jsonld and hydra.jsonld files.

Recent additions — Fog vocabulary

The fog layer currently contributes a seed semantic vocabulary in fog-vocabulary.jsonld covering:

  • Topic
  • TopicEnvelope
  • ReplicationPolicy
  • ContentRef
  • Offer
  • WorkOrder
  • UsageReceipt
  • SettlementEvent

This vocabulary is intentionally lightweight and is expected to be folded into the broader semantic overlay as the fog contract family stabilizes.

context.jsonld — JSON-LD context

Include the context in any JSON document to make it a JSON-LD document:

{
  "@context": "https://schemas.srcos.ai/v2/context.jsonld",
  "@type": "Dataset",
  "id": "urn:srcos:dataset:health_obs"
}

Or embed the context inline:

{
  "@context": {
    "srcos": "https://schemas.srcos.ai/v2/",
    "Dataset": "srcos:Dataset"
  }
}

The context maps:

  • id → @id (every id field becomes the node's IRI)
  • type → @type (every type field becomes the node's RDF type)
  • schema type names to srcos:<TypeName> IRIs
  • selected cross-vocabulary terms such as prov:wasGeneratedBy, prov:used, prov:wasAssociatedWith

hydra.jsonld — Hydra API documentation

The Hydra document is a machine-readable API description that extends the JSON-LD context. It can be served at /.well-known/hydra to make the API self-describing.

The document lists every resource class supported by the API with its supported operations (HTTP methods), expected inputs, and returned types.

Usage with Linked Data tools

Validate JSON-LD framing

npm install -g jsonld-cli
jsonld frame --frame '{"@type":"Dataset"}' examples/dataset.json

Generate RDF/Turtle from an example

jsonld format --output-format nquads examples/dataset.json

Check Hydra documentation

curl https://api.srcos.local/.well-known/hydra | python3 -m json.tool

Extending the context

When adding a new first-class schema type:

  1. Add a mapping to context.jsonld: "NewType": "srcos:NewType"
  2. Add a hydra:supportedClass entry to hydra.jsonld with at minimum hydra:title, hydra:description, and the applicable hydra:supportedOperation entries.
  3. Update this README's file table and any additive vocabulary seeds if the new type is being staged incrementally.

See CONTRIBUTING.md for the full guide.

Standards references