eyeling 1.14.5 → 1.14.7

package/examples/deck/schema-foaf-mapping.md

@@ -0,0 +1,219 @@
+# Mapping two data models (beginner-friendly)
+
+When people say “map two data models,” they mean:
+
+> **Taking data described using one vocabulary (Model A) and expressing the same meaning using another vocabulary (Model B).**
+
+In the Semantic Web / Linked Data world, a “data model” is often a **set of RDF terms** (classes + properties) defined by an ontology or vocabulary—like **schema.org** or **FOAF**.
+
+---
+
+## Why would you map vocabularies?
+
+Even if two vocabularies describe similar things, they may use **different names** and **different structures**.
+
+- **schema.org** is common for publishing data on the web (SEO, structured data).
+- **FOAF (Friend of a Friend)** is common for describing people, names, online accounts, and social relationships.
+
+Mapping lets you:
+
+- reuse tools built for another vocabulary,
+- integrate datasets that use different terms,
+- keep your original data but still answer queries in the target vocabulary.
+
+---
+
+## The core idea: “same meaning, different words”
+
+Example concept:
+
+- In **schema.org**, a person is `schema:Person`
+- In **FOAF**, a person is `foaf:Person`
+
+Those two classes can represent the same real-world thing (a person), just in different vocabularies.
+
+Similarly for properties:
+
+- `schema:name` ≈ `foaf:name`
+- `schema:givenName` ≈ `foaf:givenName`
+- `schema:familyName` ≈ `foaf:familyName`
+
+A mapping is just a **set of rules** that says:
+
+> “If you see X in schema.org, you can also produce Y in FOAF.”
+
+---
+
+## What is N3 (Notation3) and what are N3 rules?
+
+**N3** is a compact RDF syntax that also supports **rules**.
+
+A rule looks like:
+
+- **Left side (condition):** patterns you look for in your data
+- **Right side (conclusion):** triples you can _generate_ when the condition matches
+
+General shape:
+
+```n3
+{  # IF you find these triples...
+  ...patterns...
+}
+=>
+{  # THEN you may add these triples...
+  ...new triples...
+}.
+```
+
+This is sometimes called **forward-chaining**: you start with data you have, and rules _derive_ additional data.
+
+---
+
+## Example data in schema.org (RDF/Turtle)
+
+Imagine your dataset contains:
+
+```turtle
+@prefix schema: <https://schema.org/> .
+@prefix ex:     <https://example.org/> .
+
+ex:alice a schema:Person ;
+  schema:name "Alice Example" ;
+  schema:givenName "Alice" ;
+  schema:familyName "Example" .
+```
+
+This says:
+
+- `ex:alice` is a `schema:Person`
+- her full name is `"Alice Example"`
+- her given and family names are included too
+
+---
+
+## Mapping to FOAF using N3 rules
+
+Now we write rules that _derive_ FOAF triples.
+
+```n3
+@prefix schema: <https://schema.org/> .
+@prefix foaf:   <http://xmlns.com/foaf/0.1/> .
+
+# Rule 1: schema:Person -> foaf:Person
+{
+  ?p a schema:Person .
+}
+=>
+{
+  ?p a foaf:Person .
+}.
+
+# Rule 2: schema:name -> foaf:name
+{
+  ?p schema:name ?name .
+}
+=>
+{
+  ?p foaf:name ?name .
+}.
+
+# Rule 3: schema:givenName -> foaf:givenName
+{
+  ?p schema:givenName ?gn .
+}
+=>
+{
+  ?p foaf:givenName ?gn .
+}.
+
+# Rule 4: schema:familyName -> foaf:familyName
+{
+  ?p schema:familyName ?fn .
+}
+=>
+{
+  ?p foaf:familyName ?fn .
+}.
+```
+
+Read Rule 2 in plain English:
+
+> If a person `?p` has a `schema:name` value `?name`, then we can also say `?p` has a `foaf:name` value `?name`.
+
+---
+
+## What output do you get?
+
+After applying the rules, you still have your original schema.org data, **plus** extra FOAF triples like:
+
+```turtle
+@prefix foaf: <http://xmlns.com/foaf/0.1/> .
+@prefix ex:   <https://example.org/> .
+
+ex:alice a foaf:Person ;
+  foaf:name "Alice Example" ;
+  foaf:givenName "Alice" ;
+  foaf:familyName "Example" .
+```
+
+So now FOAF-based tools or queries can work, even though your “source of truth” is schema.org.
+
+---
+
+## Important beginner notes
+
+### 1) Mapping usually _adds_ data (it doesn’t delete or replace)
+
+Most rule-based mappings are “non-destructive”:
+
+- Keep the original triples
+- Derive additional triples in the target vocabulary
+
+### 2) 1-to-1 mappings are the easy case
+
+`schema:name -> foaf:name` is straightforward.
+
+But sometimes:
+
+- one term in schema.org maps to **multiple** terms in FOAF, or
+- the target expects a different structure (blank nodes, split names, etc.)
+
+### 3) “Same meaning” is a judgment call
+
+Two properties might be _similar_ but not truly identical in all contexts. Mapping works best when you understand the intended meaning of each term.
+
+---
+
+## A simple mental checklist for mapping
+
+1. **List the things** you have (classes + properties in schema.org)
+2. **Decide what you want** to support (FOAF terms you need)
+3. For each target term, ask:
+   - “Where can I get this information from in the source?”
+
+4. Write rules:
+   - **conditions** match the source triples
+   - **conclusions** emit the target triples
+
+5. Run a reasoner/rule engine and test with a few example resources
+
+---
+
+## Next step ideas (optional)
+
+- Map online profiles:
+  - `schema:sameAs` could help populate `foaf:page` or related links (careful: semantics differ).
+
+- Add type rules beyond `Person`
+- Write rules that create structured nodes (more advanced)
+
+---
+
+## Summary
+
+Mapping two models is about **translating meaning across vocabularies**.
+
+- You start with data described in **schema.org**
+- You write **N3 rules** that recognize schema.org patterns
+- You **derive FOAF triples**
+- The result is data that can be consumed as if it were FOAF, without rewriting your original dataset

package/examples/n3-delegation-access.n3

@@ -0,0 +1,153 @@
+# ====================================================================
+# N3 LINKS POLICY, PROVENANCE, AND INFERENCE
+#
+# Another “speaks for itself” case:
+#   Delegation-based trust + distributed authorization.
+#
+# What it shows (in one syntax):
+#   - Quoted claims from multiple web documents
+#   - A tiny trust policy that can *delegate* trust to other documents
+#   - Importing only trusted statements into the fact set
+#   - Reasoning across imported facts to derive permissions
+#   - Provenance output using singleton graph terms (formulas),
+#     and *not stored* as derived facts.
+#
+# Run:
+#   eyeling examples/n3-delegation-access.n3
+#
+# Output:
+#   - :report :trusts <doc>
+#   - :report :entails { <user> :canRead <resource>. }
+#   - { ... } :assertedBy <doc>    (singleton graph provenance)
+# ====================================================================
+
+@prefix :     <https://example.org/n3-delegation#>.
+@prefix id:   <https://example.org/id/>.
+@prefix foaf: <http://xmlns.com/foaf/0.1/>.
+@prefix log:  <http://www.w3.org/2000/10/swap/log#>.
+
+# ----------
+# Trust root
+# ----------
+
+:policy :trusts <https://root.example/policy.n3>.
+
+# ------------------------------
+# The Web "says" (quoted graphs)
+# ------------------------------
+
+# Root policy delegates trust outward.
+<https://root.example/policy.n3> :says {
+  :policy :delegatesTo <https://hr.example/policy.n3>.
+  :policy :delegatesTo <https://team.example/members.n3>.
+}.
+
+# HR publishes what groups may read what.
+<https://hr.example/policy.n3> :says {
+  :eng :mayRead :buildReport.
+  :eng :mayRead :roadmap.
+}.
+
+# Team publishes membership, and delegates further.
+<https://team.example/members.n3> :says {
+  id:alice foaf:name "Alice".
+  id:alice :memberOf :eng.
+
+  :policy :delegatesTo <https://interns.example/members.n3>.
+}.
+
+# Intern list becomes trusted only because Team delegated to it.
+<https://interns.example/members.n3> :says {
+  id:eve foaf:name "Eve".
+  id:eve :memberOf :eng.
+}.
+
+# Untrusted rumor: present as quoted data, but will not be imported.
+<http://shady.example/rumor.n3> :says {
+  id:mallory foaf:name "Mallory".
+  id:mallory :memberOf :eng.
+  :eng :mayRead :secrets.
+}.
+
+# --------------------------------
+# Trust can be delegated (forward)
+# --------------------------------
+
+{
+  :policy :trusts ?Doc.
+  ?Doc :says ?F.
+  ?F log:includes { :policy :delegatesTo ?Other. }.
+}
+=>
+{
+  :policy :trusts ?Other.
+}.
+
+# ----------------------------------
+# Import only trusted quoted triples
+# ----------------------------------
+{
+  :policy :trusts ?Doc.
+  ?Doc :says ?F.
+  ?F log:includes { ?S ?P ?O. }.
+}
+=>
+{
+  ?S ?P ?O.
+}.
+
+# ------------------------------------------------
+# Local meaning: membership + policy => permission
+# ------------------------------------------------
+{
+  ?U :memberOf ?G.
+  ?G :mayRead ?R.
+}
+=>
+{
+  ?U :canRead ?R.
+}.
+
+# ------
+# REPORT
+# ------
+
+# Which documents ended up trusted (root + delegated)
+{
+  :policy :trusts ?Doc.
+}
+log:query
+{
+  :report :trusts ?Doc.
+}.
+
+# What the system entails
+{
+  ?U :canRead ?R.
+}
+log:query
+{
+  :report :entails { ?U :canRead ?R. }.
+}.
+
+# Why (provenance), using singleton graph terms:
+# show the two supporting asserted statements and where they came from.
+{
+  ?U :canRead ?R.
+
+  ?U :memberOf ?G.
+  ?G :mayRead ?R.
+
+  :policy :trusts ?DocM.
+  ?DocM :says ?FM.
+  ?FM log:includes { ?U :memberOf ?G. }.
+
+  :policy :trusts ?DocP.
+  ?DocP :says ?FP.
+  ?FP log:includes { ?G :mayRead ?R. }.
+}
+log:query
+{
+  { ?U :memberOf ?G. } :assertedBy ?DocM.
+  { ?G :mayRead ?R. }  :assertedBy ?DocP.
+}.

package/examples/n3-speaks-for-itself.n3

@@ -0,0 +1,118 @@
+# ==========================================================
+# N3 SPEAKS FOR ITSELF
+#
+# One syntax does it all:
+#   - Names (URIs)
+#   - Claims (triples)
+#   - Quoted claims (formulas as data)
+#   - Policy (trust)
+#   - Reasoning (closure over links)
+#   - Provenance without reification (singleton graph terms)
+#
+# Run:
+#   eyeling examples/n3-speaks-for-itself.n3
+#
+# Output is just a few :report triples (no log:outputString).
+# ==========================================================
+
+@prefix :     <https://example.org/n3-speaks#>.
+@prefix id:   <https://example.org/id/>.
+@prefix foaf: <http://xmlns.com/foaf/0.1/>.
+@prefix log:  <http://www.w3.org/2000/10/swap/log#>.
+
+# --------------------------------
+# Policy: which documents we trust
+# --------------------------------
+
+:policy :trusts <https://alice.example/profile.n3>.
+:policy :trusts <https://bob.example/profile.n3>.
+:policy :trusts <https://carol.example/profile.n3>.
+
+# -------------------------------------
+# The Web "says" things (quoted graphs)
+# -------------------------------------
+
+<https://alice.example/profile.n3> :says {
+  id:alice foaf:name  "Alice".
+  id:alice foaf:knows id:bob.
+}.
+
+<https://bob.example/profile.n3> :says {
+  id:bob   foaf:name  "Bob".
+  id:bob   foaf:knows id:carol.
+}.
+
+<https://carol.example/profile.n3> :says {
+  id:carol foaf:name  "Carol".
+  id:carol foaf:knows id:dave.
+  id:dave  foaf:name  "Dave".
+}.
+
+# Untrusted rumor: present as quoted data, but policy won’t import it.
+<http://shady.example/rumor.n3> :says {
+  id:alice   foaf:knows id:mallory.
+  id:mallory foaf:name  "Mallory".
+}.
+
+# ----------------------------------------------------------------------------------
+# Import rule: trusted quotes become facts
+#
+# IMPORTANT:
+#   Do NOT derive provenance facts that *store* formula terms (like {..} :from ?Doc)
+#   in the forward-chaining store, because formula terms in rule heads may be
+#   generated as fresh nodes each time and can prevent fixpoint termination.
+#
+# We still *output* provenance later via log:query, computed directly from quotes.
+# ----------------------------------------------------------------------------------
+
+{
+  :policy :trusts ?Doc.
+  ?Doc :says ?F.
+  ?F log:includes { ?S ?P ?O. }.
+}
+=>
+{
+  ?S ?P ?O.
+}.
+
+# ----------------------------------------------------------
+# Meaning: knowsPlus is the transitive closure of foaf:knows
+# ----------------------------------------------------------
+
+{ ?A foaf:knows ?B. } => { ?A :knowsPlus ?B. }.
+{ ?A :knowsPlus ?B. ?B foaf:knows ?C. } => { ?A :knowsPlus ?C. }.
+
+# ---------------------------------------
+# REPORT: select only the “story” triples
+# ---------------------------------------
+
+# What we trust
+{
+  :policy :trusts ?Doc.
+}
+log:query
+{
+  :report :trusts ?Doc.
+}.
+
+# What we believed, and where it came from
+# (provenance emitted as singleton graph term, but not stored as derived facts)
+{
+  :policy :trusts ?Doc.
+  ?Doc :says ?F.
+  ?F log:includes { ?S ?P ?O. }.
+}
+log:query
+{
+  :report :believes { ?S ?P ?O. }.
+  { ?S ?P ?O. } :believedFromDoc ?Doc.
+}.
+
+# What logic adds: who Alice can reach by following links
+{
+  id:alice :knowsPlus ?Who.
+}
+log:query
+{
+  :report :aliceReaches ?Who.
+}.