jsonld-bible.md

Vocabulary, Context, and Data — How They Fit Together

1. Vocabulary (Ontology)

Defines what exists and how things relate — like a database schema.

{
  "@graph": [
    { "@id": "aiid:Incident", "@type": "rdfs:Class" },
    { "@id": "aiid:allegedDeployer", "@type": "rdf:Property",
      "rdfs:domain": "aiid:Incident",
      "rdfs:range": "schema:Organization" }
  ]
}

Example meaning: “An Incident exists. It has an allegedDeployer property that points to an Organization.”

2. Context

Provides JSON-friendly shortcuts — like column aliases in SQL.

{
  "@context": {
    "Incident": "aiid:Incident",
    "deployer": { "@id": "aiid:allegedDeployer", "@type": "@id" }
  }
}

Example meaning: “When you see ‘Incident’ in JSON, it means ‘aiid:Incident’. ‘deployer’ means ‘aiid:allegedDeployer’ and is a reference.”

3. Data

The actual information — like rows in a table.

{
  "@context": "link-to-context.json",
  "@type": "Incident",
  "deployer": "org/acme-corp"
}

Example meaning: “This is an incident. ACME Corp deployed it.”

How They Work Together

Vocabulary ("Schema") → Context ("Shorthand") → Data ("Facts")

• Vocabulary: Defines the classes and properties.
• Context: Maps human-readable JSON keys to those definitions.
• Data: Stores real instances.

Analogy: Database

• Vocabulary = CREATE TABLE statements
• Context = Column aliases / API mapping
• Data = INSERT statements

Why All Three Matter

• Vocabulary alone → You can validate, but it’s cumbersome to write.
• Context alone → JSON is easier, but lacks meaning or validation.
• Data alone → Ambiguous — “name” could mean anything.

Together they provide:

• Human-readable JSON (context)
• Machine-understandable semantics (vocabulary)
• Real, shareable information (data)