cesarvarela · August 15, 2025 22:41 · Aug 15, 2025
diff --git a/jsonld-bible.md b/jsonld-bible.md
@@ -0,0 +1,79 @@
+
+# Vocabulary, Context, and Data — How They Fit Together
+
+## 1. Vocabulary (Ontology)
+Defines **what exists** and how things relate — like a database schema.
+
+```json
+{
+  "@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.
+
+```json
+{
+  "@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.
+
+```json
+{
+  "@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)
No results found