JSON Mapping

pg_ripple's JSON mapping feature provides a bidirectional bridge between JSON payloads and the RDF knowledge graph. Register a named JSON-LD context once with register_json_mapping(), then use it for both ingest and export.

Registration

SELECT pg_ripple.register_json_mapping(
    'contacts',
    '{"contact_id": "http://schema.org/identifier",
      "full_name":  "http://schema.org/name",
      "email_addr": "http://schema.org/email"}'::jsonb
);

Parameters:

Ingest (JSON → RDF)

SELECT pg_ripple.ingest_json(
    '{"contact_id": "c001", "full_name": "Alice Smith"}'::jsonb,
    'https://example.com/contacts/c001',
    'contacts'
);

Modes: 'append' (default), 'upsert', 'diff'.

Export (RDF → JSON)

SELECT pg_ripple.export_json_node(subject_id, 'contacts');

Relational Writeback (v0.128.0)

v0.128.0 adds the ability to write RDF graph changes back to the originating relational table — completing the full round-trip.

Configuration

Configure the relational target through the validated public API. This checks the relation, key columns, conflict policy, privileges, and target PostgreSQL types, then caches the casts atomically. Direct updates to _pg_ripple are not part of the public API.

SELECT pg_ripple.configure_json_writeback(
    'contacts', 'public', 'contacts', ARRAY['contact_id'], 'replace'
);

Inspect the resolved target, cached column types, enabled state, and queue health:

SELECT * FROM pg_ripple.writeback_inspect('contacts');

Conflict Policies

Direct Writeback

-- Write a single subject back to the relational table.
SELECT pg_ripple.writeback_json_row('contacts', 'https://example.com/contacts/c001');

-- Delete a subject from the relational table.
SELECT pg_ripple.writeback_json_row_delete('contacts', 'https://example.com/contacts/c001');

Trigger-Based Automation

Enable VP delta triggers for automatic async writeback:

SELECT pg_ripple.enable_json_writeback('contacts');

The background merge worker drains the queue in batches (controlled by pg_ripple.json_writeback_batch_size, default 100).

Monitor queue status:

SELECT * FROM pg_ripple.json_writeback_status();
--  mapping_name | pending | errors | last_error | last_processed_at

HTTP Writeback

The HTTP companion exposes the same writeback path for applications that do not call SQL directly:

curl -X POST http://localhost:7878/json-mapping/contacts/writeback \
    -H "Authorization: Bearer $TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"subject_iri":"https://example.com/contacts/c001"}'

Successful synchronous writeback returns:

{"rows_affected": 1}

Queue status for one mapping is available over HTTP as well:

curl http://localhost:7878/json-mapping/contacts/writeback/status \
    -H "Authorization: Bearer $TOKEN"

The status response mirrors json_writeback_status() for the selected mapping:

{
    "mapping_name": "contacts",
    "pending": 0,
    "errors": 0,
    "last_error": null,
    "last_processed_at": null
}

Validated writeback configuration and queue health are also available at:

curl http://localhost:7878/json-mapping/contacts/writeback/config \
    -H "Authorization: Bearer $TOKEN"

Disable triggers:

SELECT pg_ripple.disable_json_writeback('contacts');

Both enable_json_writeback() and disable_json_writeback() are idempotent.

Error Codes

See Also

• JSON-LD Reverse Mapping blog post
• JSON Writeback, and What It Took to Make It Actually Work
• GUC reference: json_writeback_batch_size
• HTTP API Reference
• R2RML for complex ETL