Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

fix(export): keep JSON-LD payloads in the default graph

FABIOTESS60eb595d6216
diff --git a/semantica/export/json_exporter.py b/semantica/export/json_exporter.py
index c9c587de..c1906250 100644
--- a/semantica/export/json_exporter.py
+++ b/semantica/export/json_exporter.py
@@ -34,6 +34,25 @@ from ..utils.progress_tracker import get_progress_tracker
from .rdf_exporter import SEMANTICA_NS, mint_entity_iri, mint_relationship_iri
+def _is_jsonld_document(data: Dict[str, Any]) -> bool:
+ """
+ Report whether a dictionary is already a JSON-LD document.
+
+ ``export_knowledge_graph`` converts a knowledge graph to JSON-LD and then
+ hands the finished document to ``export()``, which converted it a second
+ time. The converted document no longer carries ``entities``/
+ ``relationships`` keys, so the second pass treated it as an opaque value and
+ buried it inside ``@graph``.
+
+ Args:
+ data: Dictionary to test
+
+ Returns:
+ True when the dictionary declares a JSON-LD context
+ """
+ return "@context" in data
+
+
class JSONExporter:
"""
JSON exporter for knowledge graphs and semantic data.
@@ -397,7 +416,16 @@ class JSONExporter:
# Convert data based on type
if isinstance(data, dict):
- if "entities" in data or "relationships" in data:
+ if _is_jsonld_document(data):
+ # Already JSON-LD: merge it rather than nesting it. Wrapping a
+ # converted document in @graph re-typed the payload as a named
+ # graph and doubled the @context, which is what happened when
+ # export_knowledge_graph handed its own output back to export().
+ context = data.get("@context")
+ if isinstance(context, dict):
+ jsonld["@context"].update(context)
+ jsonld.update({k: v for k, v in data.items() if k != "@context"})
+ elif "entities" in data or "relationships" in data:
# Knowledge graph structure - use specialized conversion
jsonld.update(self._convert_kg_to_jsonld(data, **options))
else:
@@ -412,13 +440,46 @@ class JSONExporter:
# Add metadata and provenance if requested
if include_metadata:
- jsonld["@id"] = f"https://semantica.dev/data/{utc_now_iso()}"
- if include_provenance:
- jsonld["semantica:exportedAt"] = utc_now_iso()
- jsonld["semantica:format"] = "json-ld"
+ self._attach_document_metadata(jsonld, include_provenance)
return jsonld
+ @staticmethod
+ def _attach_document_metadata(
+ jsonld: Dict[str, Any], include_provenance: bool
+ ) -> None:
+ """
+ Attach the export's own metadata without naming the graph.
+
+ A top-level ``@id`` alongside a top-level ``@graph`` is a *named graph*:
+ the members of ``@graph`` become quads named by that ``@id`` and leave
+ the default graph empty. ``rdflib.Graph.parse()`` keeps only the default
+ graph, so every statement in the export was discarded without an error
+ (2 of 21 statements survived a two-entity knowledge graph). When the
+ payload lives in ``@graph``, the document node goes in beside it as one
+ more node; otherwise it is the document itself.
+
+ Args:
+ jsonld: Document being built, modified in place
+ include_provenance: Whether to record how and when it was exported
+ """
+ document: Dict[str, Any] = {}
+ # Do not overwrite an identifier the payload already carries: the
+ # knowledge-graph conversion names its own document node.
+ if "@id" not in jsonld:
+ document["@id"] = f"https://semantica.dev/data/{utc_now_iso()}"
+ if include_provenance:
+ document["semantica:exportedAt"] = utc_now_iso()
+ document["semantica:format"] = "json-ld"
+
+ if "@graph" in jsonld:
+ document.setdefault(
+ "@id", f"https://semantica.dev/data/{utc_now_iso()}"
+ )
+ jsonld["@graph"] = list(jsonld["@graph"]) + [document]
+ else:
+ jsonld.update(document)
+
def _convert_kg_to_json(self, kg: Dict[str, Any], **options) -> Dict[str, Any]:
"""
Convert knowledge graph to JSON format.
diff --git a/tests/export/test_jsonld_default_graph.py b/tests/export/test_jsonld_default_graph.py
new file mode 100644
index 00000000..8d3f08a6
--- /dev/null
+++ b/tests/export/test_jsonld_default_graph.py
@@ -0,0 +1,143 @@
+"""Every JSON-LD export must put its payload in the default graph.
+
+A JSON-LD document carrying a top-level ``@id`` *and* a top-level ``@graph`` is
+a **named graph**: the contents of ``@graph`` are quads named by that ``@id``,
+not triples in the default graph. ``rdflib.Graph.parse()`` — the ordinary way a
+Python consumer loads RDF — keeps the default graph and discards the rest,
+without an error. ``JSONExporter`` emitted exactly that shape:
+
+* ``_convert_to_jsonld`` wrote the payload into ``@graph`` and then stamped a
+ document ``@id`` beside it, so every list export and every generic-dict
+ export was named;
+* ``export_knowledge_graph`` converted the graph to JSON-LD and handed the
+ finished document back to ``export()``, which converted it a *second* time.
+ The converted document no longer has ``entities``/``relationships`` keys, so
+ the second pass treated it as opaque and wrapped it in ``@graph`` — burying
+ a whole knowledge graph, entities, relationships and all, inside a named
+ graph whose name is a wall-clock timestamp.
+
+Measured on v0.6.6: a two-entity, one-relationship graph exported to JSON-LD
+parsed as **2 triples** with ``Graph()`` and 21 quads with ``Dataset()``. The 19
+missing triples were the entire knowledge graph, and nothing reported a
+problem. Semantica's own reader has the mirror of this bug (#1129), so the
+export could not even be read back by Semantica.
+"""
+
+import json
+
+import pytest
+from rdflib import Dataset, Graph
+
+from semantica.export.json_exporter import JSONExporter
+
+KG = {
+ "entities": [
+ {"id": "https://example.org/e1", "text": "Acme Corp", "type": "ORG"},
+ {"id": "https://example.org/e2", "text": "Jane Roe", "type": "PERSON"},
+ ],
+ "relationships": [
+ {
+ "source_id": "https://example.org/e1",
+ "target_id": "https://example.org/e2",
+ "type": "employs",
+ }
+ ],
+ "metadata": {"source_document": "contract.pdf"},
+}
+
+RDFS_LABEL = "http://www.w3.org/2000/01/rdf-schema#label"
+
+PAYLOADS = {
+ "knowledge_graph": KG,
+ "list": [
+ {"@id": "https://example.org/a", RDFS_LABEL: "A"},
+ {"@id": "https://example.org/b", RDFS_LABEL: "B"},
+ ],
+ "generic_dict": {"@id": "https://example.org/x", RDFS_LABEL: "X"},
+}
+
+
+def _write(payload, tmp_path, name="out.jsonld", **options):
+ path = tmp_path / name
+ JSONExporter().export(payload, path, format="json-ld", **options)
+ return path
+
+
+def _counts(path):
+ """Triples a default-graph reader sees, and quads a quad reader sees."""
+ graph = Graph()
+ graph.parse(str(path), format="json-ld")
+ dataset = Dataset()
+ dataset.parse(str(path), format="json-ld")
+ return len(graph), sum(1 for _ in dataset.quads((None, None, None, None)))
+
+
[email protected]("name", sorted(PAYLOADS))
+def test_no_export_hides_its_payload_in_a_named_graph(name, tmp_path):
+ """A top-level @id beside a top-level @graph names the graph."""
+ path = _write(PAYLOADS[name], tmp_path, f"{name}.jsonld")
+ document = json.loads(path.read_text())
+
+ assert not ("@id" in document and "@graph" in document), (
+ f"{name}: @id + @graph at the top level makes a named graph, "
+ "which a default-graph reader discards in full"
+ )
+
+
[email protected]("name", sorted(PAYLOADS))
+def test_a_plain_graph_reader_loses_nothing(name, tmp_path):
+ """Graph() and Dataset() must agree: no triple may live outside the default graph."""
+ path = _write(PAYLOADS[name], tmp_path, f"{name}.jsonld")
+ triples, quads = _counts(path)
+
+ assert triples == quads, (
+ f"{name}: Graph() read {triples} of {quads} statements; "
+ f"{quads - triples} were dropped silently"
+ )
+
+
+def test_exported_knowledge_graph_survives_a_default_graph_read(tmp_path):
+ """The entities and the relationship must be there after a plain parse."""
+ path = tmp_path / "kg.jsonld"
+ JSONExporter().export_knowledge_graph(KG, path, format="json-ld")
+
+ graph = Graph()
+ graph.parse(str(path), format="json-ld")
+ subjects = {str(s) for s in graph.subjects()}
+ objects = {str(o) for o in graph.objects()}
+
+ assert "https://example.org/e1" in subjects
+ assert "https://example.org/e2" in subjects
+ assert "Acme Corp" in objects
+ assert "Jane Roe" in objects
+ assert "employs" in objects
+
+
+def test_knowledge_graph_is_not_converted_twice(tmp_path):
+ """A nested @context is the signature of the document being re-converted."""
+ path = tmp_path / "kg.jsonld"
+ JSONExporter().export_knowledge_graph(KG, path, format="json-ld")
+ document = json.loads(path.read_text())
+
+ nested = [
+ node
+ for node in document.get("@graph", [])
+ if isinstance(node, dict) and "@context" in node
+ ]
+ assert nested == [], "the knowledge graph was converted, then converted again"
+
+
+def test_document_provenance_still_reaches_the_default_graph(tmp_path):
+ """Keeping the payload readable must not cost the export its own metadata."""
+ path = _write(PAYLOADS["list"], tmp_path)
+
+ graph = Graph()
+ graph.parse(str(path), format="json-ld")
+ predicates = {str(p) for p in graph.predicates()}
+
+ assert "https://semantica.dev/ns#exportedAt" in predicates
+ assert "https://semantica.dev/ns#format" in predicates
+ assert {"https://example.org/a", "https://example.org/b"} <= {
+ str(s) for s in graph.subjects()
+ }
+ assert {"A", "B"} <= {str(o) for o in graph.objects()}