Dashboard Request Access
Developer & Product Reference

AgroLD Proxy Architecture

How VersaAgro bridges a CORS-constrained open-source academic SPARQL endpoint to browser-based search, alert enrichment, and NLP inference pipelines — without violating Same-Origin Policy or exposing credentials.

AgroLD v2 Integration SPARQL Proxy Pattern CORS Constraint Explained NLP → SPARQL Pipeline Federated Query Architecture
CORS Constraint: https://v2.agrold.org/sparql does not send Access-Control-Allow-Origin headers. Direct browser fetch() is blocked by Same-Origin Policy. This page documents the architecture for working around this constraint in production.
What This Is

AgroLD as VersaAgro's KG Source of Truth

AgroLD v2 is an open-source, SPARQL-queryable RDF knowledge graph developed by INRAE and Montpellier SupAgro that federates 8 major agronomic ontologies into a single queryable endpoint. VersaAgro uses AgroLD as the external ontological source of truth for grounding NLP queries, enriching alert recommendations, and providing verifiable IRI-attributed citations to end users.

Open-Source KG Source

AgroLD integrates Gene Ontology, Trait Ontology, Plant Ontology, Crop Ontology, NCBI Taxonomy, Gramene, OBO Relations, and AGROVOC — providing a single SPARQL endpoint across 8 ontologies and >100K agronomic relationships.

CORS-Constrained Endpoint

The AgroLD SPARQL endpoint (https://v2.agrold.org/sparql) does not include Access-Control-Allow-Origin headers, meaning browsers block direct fetch() calls. A server-side proxy is required for production use.

Two-Layer Architecture

The prototype uses a curated static layer — 36 entities with canonical IRIs in data/agrold-entities.json — for zero-latency, CORS-safe demo. Production routes through a server-side SPARQL proxy for live federated queries.

NLP → SPARQL Pipeline

User plain-language queries are classified by intent, entities are resolved against AgroLD IRIs, and SPARQL templates are hydrated and executed server-side. Results are merged with internal VersaAgro triple store data and returned as cited responses.

Canonical IRI Attribution

Every entity in the VersaAgro system retains its canonical AgroLD IRI (e.g., agrold:Aphis_glycines). This preserves full provenance linkage from a user-facing response back to the source ontology node — enabling academic-grade auditability.

Federated Query Design

Production SPARQL queries federate across: (1) AgroLD external endpoint for ontology data, (2) VersaAgro's internal triple store for sensor and field triples, and (3) open CORS-enabled APIs (Open-Meteo, GBIF) for real-time enrichment — all joined server-side.

The Constraint

The CORS Problem Explained

Browser Same-Origin Policy (SOP) is a W3C security mechanism that prevents JavaScript running on versaagro.com from making HTTP requests to v2.agrold.org unless the server at v2.agrold.org explicitly opts in via CORS response headers.

What Happens Without a Proxy: When a browser calls fetch('https://v2.agrold.org/sparql?query=...'), the browser first makes a preflight OPTIONS request. AgroLD's server returns the query result but does not include Access-Control-Allow-Origin: * in the response headers. The browser intercepts the response and throws: "Cross-Origin Request Blocked: The Same Origin Policy disallows reading the remote resource." The JavaScript fetch() rejects. No data is returned to the page.
What Fails (Browser Direct)
// ✗ BLOCKED by browser CORS policy
const res = await fetch(
  'https://v2.agrold.org/sparql?' +
  'query=SELECT...'
);
// NetworkError: Cross-Origin Request Blocked
// Headers received: none (CORS headers missing)
// Result: 0 bytes returned to page
What Works (Server-Side Proxy)
// ✓ Browser calls VersaAgro API (same domain)
const res = await fetch(
  '/api/kg/query', {
    method: 'POST',
    body: JSON.stringify({ nlp, field_id })
  }
);
// Server proxies to AgroLD (server-to-server)
// No CORS issue — server is not a browser

CORS-Safe APIs VersaAgro Can Use Directly From the Browser

Open-Meteo
Weather forecasts · CORS-enabled · Free · Used in water stress alerts
GBIF API
Biodiversity occurrences · CORS-enabled · Pest species range data
AGROVOC SPARQL
FAO thesaurus · CORS headers present · Direct queries possible
Sentinel Hub (OAuth)
ESA Sentinel-2 · API-key auth · Proxy recommended for key security
Architecture

Full Architecture Flow

The two-layer architecture separates the static prototype layer (used in this demo) from the production SPARQL proxy layer. Both layers preserve canonical AgroLD IRIs in all responses.

Layer 1 — Static Dataset (Current Prototype)
Browser Client
knowledge-graph.html · search input · AgroLD Explorer section
fetch('data/agrold-entities.json')
Local static file · Same origin · No CORS issues
JavaScript Client-Side Filter
Label · scientific · tags · description matching
Attributed Results — Canonical IRIs Preserved
Type badges · AgroLD IRI links · SPARQL examples · VersaAgro signals
Zero CORS issues — local JSON fetch. Zero latency — cached after first load. 36 entities with canonical IRIs, SPARQL examples, VersaAgro signal descriptions.
Layer 2 — Production SPARQL Proxy
Browser Client
POST /api/kg/query · {nlp: "query text", field_id: "NE-847"}
VersaAgro API Gateway
CORS-enabled · Auth JWT validated · Rate-limited · Logged
NLP → SPARQL Translator
Intent classification · AgroLD entity resolution · Template hydration
AgroLD SPARQL
Server-to-server · No CORS block
VA Triple Store
IoT + satellite triples
↓ SPARQL UNION / JOIN ↓
Merged Response — Full IRI Attribution
Cited answer · Source IRIs (AgroLD + sensor + satellite) · <200ms
CORS is bypassed because the server-side proxy runs Node.js/Python — not a browser. Server-to-server HTTP is unrestricted. The browser only ever calls /api/kg/query on the same VersaAgro domain.
Implementation

Code Examples

Reference implementations for both the static layer (current prototype) and the production server-side SPARQL proxy pattern.

Static Layer Implementation — Fetches data/agrold-entities.json and performs client-side fuzzy matching. Canonical AgroLD IRIs are preserved in every result, ensuring production-ready provenance linkage from day one. This is the current implementation in knowledge-graph.html.

// data/agrold-entities.json — curated static snapshot // Each entity retains canonical AgroLD IRI for provenance let entityCache = null; async function loadAgroLDEntities() { if (entityCache) return entityCache; const res = await fetch('data/agrold-entities.json'); const json = await res.json(); entityCache = json.entities || []; return entityCache; } async function searchAgroLD(query) { const entities = await loadAgroLDEntities(); const q = query.toLowerCase(); return entities.filter(e => e.label.toLowerCase().includes(q) || (e.scientific && e.scientific.toLowerCase().includes(q)) || (e.tags && e.tags.some(t => t.includes(q))) || (e.description && e.description.toLowerCase().includes(q)) ); } // Each result preserves: // entity.iri → "https://v2.agrold.org/resource/Aphis_glycines" // entity.sparql_example → production SPARQL query template // entity.versaagro_signal → alert signal description

Browser Client Call — In production, the browser calls VersaAgro's own CORS-enabled API rather than the AgroLD endpoint directly. The server handles SPARQL execution and returns merged, cited results. This pattern avoids exposing any API keys or backend credentials to the browser.

// Browser client — calls VersaAgro API (same domain, CORS-enabled) async function queryKnowledgeGraph(nlpQuery, fieldId) { const res = await fetch('/api/kg/query', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ nlp: nlpQuery, field_id: fieldId, include_agrold: true, include_sensor_data: true }) }); if (!res.ok) throw new Error(`KG query failed: ${res.status}`); return await res.json(); } // Response structure: // { // answer: "Zones 4, 7, and 11 exceed the 250 aphid/plant threshold...", // sources: [ // { type: "agrold", iri: "https://v2.agrold.org/resource/Aphis_glycines" }, // { type: "sensor", id: "SENSOR-NE847-Z07" }, // { type: "satellite", obs: "S2-2026-05-01" } // ] // }

Server-Side SPARQL Proxy (Node.js) — The proxy runs on the VersaAgro backend. It receives the translated SPARQL query, calls the AgroLD endpoint server-to-server (no CORS restriction), and returns results to the client. Express.js with node-fetch or Axios handles the outbound call.

// VersaAgro API — server/routes/kg-query.js (Node.js + Express) const express = require('express'); const { sparqlQuery } = require('../services/agrold-proxy'); const { nlpToSparql } = require('../services/nlp-translator'); const { queryTripleStore } = require('../services/triple-store'); const router = express.Router(); router.post('/api/kg/query', async (req, res) => { const { nlp, field_id, include_agrold } = req.body; // 1. Translate NLP → SPARQL template const { sparql, entities } = await nlpToSparql(nlp); // 2. Query AgroLD (server-to-server, no CORS block) let agroldResults = []; if (include_agrold) { agroldResults = await sparqlQuery( 'https://v2.agrold.org/sparql', sparql ); } // 3. Query VersaAgro internal triple store const internalResults = await queryTripleStore( sparql, field_id ); // 4. Merge + cite sources const merged = mergeAndCite(agroldResults, internalResults, entities); res.json(merged); }); // agrold-proxy.js — outbound SPARQL call async function sparqlQuery(endpoint, sparql) { const url = `${endpoint}?query=${encodeURIComponent(sparql)}&format=json`; const res = await fetch(url); // server-to-server — unrestricted return (await res.json()).results.bindings; }

NLP → SPARQL Translator — The translator maps intent-classified query components to SPARQL template slots, resolves entity names against AgroLD entity IRIs from the curated dataset, and hydrates a SPARQL 1.1 query. The resolved IRI ensures the response cites the canonical ontology source.

// nlp-translator.js — simplified AEO pipeline const ENTITY_IRI_MAP = { // Loaded from data/agrold-entities.json at startup 'soybean aphid': 'https://v2.agrold.org/resource/Aphis_glycines', 'aphid': 'https://v2.agrold.org/resource/Aphis_glycines', 'drought stress': 'https://v2.agrold.org/resource/DroughtStress', 'wheat': 'https://v2.agrold.org/resource/TriticumAestivum', 'ndvi': 'https://v2.agrold.org/resource/NDVI', }; const SPARQL_TEMPLATES = { 'pest-risk': ` PREFIX to: <http://purl.obolibrary.org/obo/TO_> PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> SELECT ?trait ?label WHERE { <{{IRI}}> to:associated_with ?trait . ?trait rdfs:label ?label . } LIMIT 20`, 'crop-stage': ` PREFIX po: <http://purl.obolibrary.org/obo/PO_> SELECT ?stage ?gdd WHERE { <{{IRI}}> po:has_developmental_stage ?stage . ?stage rdfs:comment ?gdd . }` }; async function nlpToSparql(nlpQuery) { const intent = await classifyIntent(nlpQuery); // LLM call const entityName = extractEntity(nlpQuery); const iri = ENTITY_IRI_MAP[entityName.toLowerCase()] || null; const template = SPARQL_TEMPLATES[intent] || SPARQL_TEMPLATES['pest-risk']; const sparql = template.replace('{{IRI}}', iri); return { sparql, entities: [{ name: entityName, iri }] }; }

Federated SPARQL JOIN — A single SPARQL 1.1 federated query can join VersaAgro's internal triple store with the AgroLD endpoint in one query using the SERVICE keyword. This is the most elegant production pattern but requires VersaAgro's own SPARQL endpoint to support SERVICE federation. The server-side proxy ensures no browser CORS issues arise.

# SPARQL 1.1 Federated Query — executed server-side # Joins VersaAgro internal triples with AgroLD live endpoint PREFIX va: <https://versaagro.com/ontology/> PREFIX to: <http://purl.obolibrary.org/obo/TO_> PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> PREFIX geo: <http://www.opengis.net/ont/geosparql#> SELECT ?zone ?riskScore ?agroldTrait ?traitLabel WHERE { # Query VersaAgro internal triple store (zone risk data) ?zone va:hasRiskScore ?riskScore ; va:affectedBy <https://v2.agrold.org/resource/Aphis_glycines> . FILTER (?riskScore > 65) # Federate: query AgroLD for trait associations of Aphis glycines SERVICE <https://v2.agrold.org/sparql> { <https://v2.agrold.org/resource/Aphis_glycines> to:associated_with ?agroldTrait . ?agroldTrait rdfs:label ?traitLabel . } } ORDER BY DESC(?riskScore) LIMIT 10 # Result: internal zone risk scores JOINED with AgroLD trait data # zone | riskScore | agroldTrait | traitLabel # zone:NE847-Z07 | 82 | TO:0000276 | "drought tolerance"
SPARQL Reference

SPARQL Query Templates by Use Case

Production-ready SPARQL query templates hydrated from AgroLD entity IRIs. All queries are executed server-side by the proxy layer.

"Which traits make this zone susceptible to aphid damage?"
Pest
PREFIX to: <http://purl.obolibrary.org/obo/TO_> PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> SELECT ?trait ?label WHERE { <https://v2.agrold.org/resource/Aphis_glycines> to:associated_with ?trait . ?trait rdfs:label ?label . } LIMIT 20
"What growth stages does wheat have and their GDD requirements?"
Crop
PREFIX po: <http://purl.obolibrary.org/obo/PO_> PREFIX to: <http://purl.obolibrary.org/obo/TO_> SELECT ?stage ?stageLabel WHERE { <https://v2.agrold.org/resource/TriticumAestivum> po:has_developmental_stage ?stage . ?stage rdfs:label ?stageLabel . OPTIONAL { ?stage to:requires_gdd ?gdd } } ORDER BY ?stage
"What genes confer resistance to Fusarium Head Blight?"
Disease
PREFIX to: <http://purl.obolibrary.org/obo/TO_> PREFIX rdfs: <http://www.w3.org/2000/01/rdf-schema#> SELECT ?gene ?resistance WHERE { ?gene to:confers_resistance_to <https://v2.agrold.org/resource/Fusarium_graminearum> . ?gene rdfs:label ?resistance . } LIMIT 15
"What are the NDVI-correlated yield traits for soybean?"
Trait
PREFIX to: <http://purl.obolibrary.org/obo/TO_> PREFIX co: <http://purl.obolibrary.org/obo/CO_> SELECT ?trait ?traitLabel ?correlation WHERE { <https://v2.agrold.org/resource/GlycineMax> to:has_trait ?trait . ?trait rdfs:label ?traitLabel . FILTER CONTAINS(?traitLabel, "yield") OPTIONAL { ?trait co:ndvi_correlation ?correlation } }
Data Sources

Ontologies Integrated via AgroLD v2

AgroLD federates 8 authoritative open ontologies into a single SPARQL endpoint. VersaAgro's curated entity dataset preserves the source ontology reference for each entity.

Gene Ontology (GO)
geneontology.org · OBO Foundry
Biological Processes Molecular Functions Cellular Components
Trait Ontology (TO)
gramene.org/plant-ontology · OBO
Agronomic Traits Yield Components Stress Tolerance
Plant Ontology (PO)
plantontology.org · OBO
Plant Structures Developmental Stages Anatomy
Crop Ontology (CO)
cropontology.org · CGIAR
Crop-Specific Traits Breeding Descriptors Field Observations
NCBI Taxonomy
ncbi.nlm.nih.gov/taxonomy
Species Classification TaxID References Phylogenetics
Gramene / Ensembl Plants
gramene.org · EMBL-EBI
Gene-to-Trait Links QTL Loci Genomics
OBO Relations (RO)
obofoundry.org/ontology/ro · OBO
Semantic Relations part_of, has_input causally_related_to
AGROVOC
agrovoc.fao.org · FAO / AIMS
Multilingual Thesaurus Agri Concepts ~40,000 terms
Reference Data

Curated Entity Catalogue

The data/agrold-entities.json static snapshot contains 36 entities across 8 types. All entities are searchable via the Knowledge Graph Explorer. Each entry retains its canonical AgroLD IRI, ontology source, SPARQL query example, and VersaAgro signal description.

Pests (6 entities)
LabelScientific NameOntologyCanonical IRIVersaAgro Signal
Soybean AphidAphis glycines MatsumuraNCBI Taxonomy + TOagrold:Aphis_glycinesNDVI drop >0.05 + temp >21°C
Fall ArmywormSpodoptera frugiperdaNCBI Taxonomy + TOagrold:Spodoptera_frugiperdaIrregular NDVI depletion + warm >28°C + wind trajectory
Coffee Berry BorerHypothenemus hampeiNCBI Taxonomy + COagrold:Hypothenemus_hampeiTemp 20–30°C for 15+ days + >75% humidity
Diseases (3 entities)
LabelScientific NameOntologyCanonical IRIKey Signal
Fusarium Head BlightFusarium graminearumNCBI Taxonomy + GOagrold:Fusarium_graminearumHumidity >85% × 3 days at anthesis
Stripe RustPuccinia striiformis f. sp. triticiNCBI Taxonomy + TOagrold:Puccinia_striiformisNDVI 0.45–0.60 canopy yellowing + cool/humid
Coffee Leaf RustHemileia vastatrixNCBI Taxonomy + TOagrold:Hemileia_vastatrixLAI decline >15% + EVI drop + wet season onset
Key Crops (selection)
LabelScientific NameOntologyCanonical IRI
Common WheatTriticum aestivum L.NCBI + CO + TOagrold:TriticumAestivum
SoybeanGlycine max (L.) Merr.NCBI + CO + TOagrold:GlycineMax
Blue AgaveAgave tequilana WeberNCBI + AGROVOCagrold:AgaveTequilana
Arabica CoffeeCoffea arabica L.NCBI + CO + GOagrold:CoffeaArabica
Full entity dataset: All 36 entities with complete SPARQL examples, VersaAgro signal descriptions, ontology cross-references, and economic thresholds are available in data/agrold-entities.json and searchable via the interactive Knowledge Graph Explorer.
Implementation Phases

Static Layer → Production SPARQL Proxy

The architecture is designed for a clear two-phase implementation: a demo-ready static layer that already shows the full data model, evolving to live SPARQL federation in production.

Phase 1 — Static Layer (Complete)
Current prototype · Demo-ready · Investor-facing
  • 36 curated AgroLD entities in data/agrold-entities.json
  • Canonical IRIs preserved in every entity
  • Client-side fuzzy search in knowledge-graph.html
  • Entity detail panel with SPARQL examples + attribution
  • KG Source chips on all 3 alert cards in alerts.html
  • AgroLD attribution on 6 glossary term cards
  • Zero CORS issues — fully CORS-safe implementation
Phase 2 — Production SPARQL Proxy
Beta pilot · Live federated queries · Full AgroLD corpus
  • Node.js/Python SPARQL proxy at /api/kg/query
  • NLP → SPARQL translator (LLM-backed intent classification)
  • VersaAgro internal SPARQL triple store (Apache Jena / Blazegraph)
  • Federated JOIN with AgroLD live endpoint (SERVICE keyword)
  • Real-time alert enrichment with AgroLD trait associations
  • Caching layer (Redis) for frequent AgroLD queries — <50ms
  • GBIF + Open-Meteo real-time enrichment via direct browser calls