# Knowledge Graph (Jarroba Tools) — a guide for AIs

This guide is for an **AI to generate a knowledge graph** that a person can **paste** into the `/kg`
tool (**Data** tab), visualise and query with SPARQL — all in the browser, with no server.

## What the tool accepts

Paste RDF data in any of these formats (pick it under "Format"):

| Format | MIME | When to use it |
|---|---|---|
| **Turtle** (`.ttl`) | `text/turtle` | **Recommended**: the most readable one for AI authoring |
| JSON-LD (`.jsonld`) | `application/ld+json` | If you already have the data as JSON |
| N-Triples (`.nt`) | `application/n-triples` | One triple per line, no prefixes |
| N-Quads (`.nq`) | `application/n-quads` | N-Triples + graph |
| TriG (`.trig`) | `application/trig` | Turtle + named graphs |
| RDF/XML (`.rdf`) | `application/rdf+xml` | Interoperating with XML tooling |

## How to model it (an RDF refresher)

A graph is made of **triples**: `subject  predicate  object .`
- **Subject/predicate**: always IRIs (resources). **Object**: an IRI (another resource) or a
  **literal** (text/number/date).
- Declare **prefixes** to shorten IRIs. Reuse standard vocabularies where they exist:
  `rdf:`, `rdfs:`, `owl:`, `xsd:`, `schema:` (schema.org), `foaf:`, `skos:`, `dcterms:`.
- Type resources with `a` (an alias for `rdf:type`): `ex:ada a schema:Person .`
- Label them with `rdfs:label` or `schema:name`; add a language with `"text"@en`.
- Type the literals: `"36"^^xsd:integer`, `"2010-05-01"^^xsd:date`, `"true"^^xsd:boolean`.

### Minimal template (Turtle)

```turtle
@prefix rdf:    <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix rdfs:   <http://www.w3.org/2000/01/rdf-schema#> .
@prefix schema: <http://schema.org/> .
@prefix ex:     <http://example.org/> .

ex:ada a schema:Person ;
  schema:name "Ada Lovelace"@en ;
  schema:birthDate "1815-12-10"^^<http://www.w3.org/2001/XMLSchema#date> ;
  schema:knows ex:babbage .

ex:babbage a schema:Person ; schema:name "Charles Babbage" .
```

### Adding a light ontology (optional; it powers "Reason (RDFS)")

If you include RDFS axioms, the tool's **Reason (RDFS)** button will infer new types and
hierarchies (it materialises the closure: transitive `subClassOf`/`subPropertyOf`, types via
`subClassOf`, `rdfs:domain`/`rdfs:range`).

```turtle
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix ex:   <http://example.org/> .

ex:Dog    rdfs:subClassOf ex:Animal .
ex:Puppy  rdfs:subClassOf ex:Dog .
ex:hasMother rdfs:domain ex:Animal ; rdfs:range ex:Animal .

ex:rex a ex:Puppy ; ex:hasMother ex:bella .   # after reasoning: rex is a Dog and an Animal
```

## Querying (SPARQL 1.1)

In the **Query** tab. The tool autocompletes prefixes, classes and properties from your own data.
Typical shapes:

```sparql
PREFIX schema: <http://schema.org/>
SELECT ?name ?born WHERE {
  ?p a schema:Person ; schema:name ?name .
  OPTIONAL { ?p schema:birthDate ?born }
}
ORDER BY ?name
```

- `SELECT` → a table (matching resources are highlighted in the graph). `ASK` → yes/no.
  `CONSTRUCT`/`DESCRIBE` → a subgraph.
- You can switch **Source** to **Wikidata** or **DBpedia** to query public data (both support
  CORS). With **Wikidata** use `wdt:`/`wd:` and the label service
  `SERVICE wikibase:label { bd:serviceParam wikibase:language "en,es". }`.

## Semantic layer (glossary + metrics)

In the **Semantics** tab. It complements the ontology: where the ontology says *what a customer is*
(classes, relations, rules), the semantic layer says *what revenue means* (the agreed business
vocabulary and metrics). The rule of thumb: **the semantic layer is for *finding*; the ontology is
for *reasoning*.**

- **Glossary**: maps a business term to a real predicate/class, with synonyms. E.g. "friend" →
  `foaf:knows`. It feeds the **AI Assistant**: write your own term in natural language and it
  recognises the right predicate.
- **Metrics**: **named** SPARQL queries, defined once and reused. They accept `{{param}}`
  parameters filled in at call time. That way everyone — you, the assistant, and an agent over MCP —
  computes the same number instead of improvising the SPARQL (the "one fact, three figures"
  problem).

## Use by an AI (MCP server)

The MCP server (`mcp/`) exposes these graph tools, reusing the very same services:

- `kg_query` — runs SPARQL 1.1 over in-memory RDF data (Oxigraph WASM).
- `kg_validate` — validates RDF data against SHACL-core shapes.
- `kg_semantic_validate` — validates a **semantic layer** document (`{ glossary, metrics }`):
  structure, required fields and unique metric names. Validate BEFORE trusting it.
- `kg_metric` — runs a **named metric** from the semantic layer against RDF data, instantiating its
  `{{param}}` parameters with `args`. Returns the effective SPARQL and the result, or the
  parameters that are missing. This is the "semantics as code" payoff: define the metric once, and
  the agent computes with the agreed definition.

## Tips for an AI

- Use **stable, consistent IRIs** (same prefix/base for the same domain).
- Prefer **standard vocabularies** (schema.org, FOAF, SKOS) over inventing properties.
- Do not stuff in huge literals; the graph reads better with clear nodes and relations.
- For the **Ontology** view to have anything in it, **type** your resources (`rdf:type`).
- The **Share** button encodes data + query in the URL: handy for sending a ready-made example.