JSON-LD for HATEOAS — Semantic Hypermedia with Linked Data Contexts

{
  "@context": {
    "@vocab": "https://schema.dodatech.com/ns/",
    "schema": "https://schema.org/",
    "name": "schema:name",
    "description": "schema:description",
    "dateCreated": "schema:dateCreated",
    "threat": {
      "@id": "https://schema.dodatech.com/ns/Threat",
      "@type": "@id"
    },
    "severity": {
      "@id": "https://schema.dodatech.com/ns/severity",
      "@type": "https://schema.org/Text"
    },
    "device": {
      "@id": "https://schema.dodatech.com/ns/device",
      "@type": "@id"
    },
    "critical": "https://schema.dodatech.com/ns/critical",
    "high": "https://schema.dodatech.com/ns/high",
    "medium": "https://schema.dodatech.com/ns/medium"
  },
  "@id": "/threats/101",
  "@type": "threat",
  "name": "Ransomware-X",
  "description": "A critical ransomware variant detected on Office-PC",
  "severity": "critical",
  "dateCreated": "2026-06-28T10:00:00Z",
  "device": "/devices/1",
  "threat": "/threats/101/analysis"
}

const express = require('express');
const app = express();

const CONTEXT_URL = 'https://schema.dodatech.com/context.jsonld';

const context = {
  '@context': {
    '@vocab': 'https://schema.dodatech.com/ns/',
    'schema': 'https://schema.org/',
    'name': 'schema:name',
    'description': 'schema:description',
    'dateCreated': 'schema:dateCreated',
    'severity': {
      '@id': 'https://schema.dodatech.com/ns/severity',
    },
    'device': { '@type': '@id' },
    'threat': { '@type': '@id' },
  },
};

// Serve the context document
app.get('/context.jsonld', (req, res) => {
  res.json({
    '@context': {
      ...context['@context'],
      // Add vocabulary documentation
      '@vocab': 'https://schema.dodatech.com/ns/',
      'threat': 'https://schema.dodatech.com/ns/Threat',
      'device': 'https://schema.dodatech.com/ns/Device',
      'severity': {
        '@id': 'https://schema.dodatech.com/ns/severity',
        '@range': 'xsd:string',
        'critical': 'https://schema.dodatech.com/ns/critical',
        'high': 'https://schema.dodatech.com/ns/high',
        'medium': 'https://schema.dodatech.com/ns/medium',
        'low': 'https://schema.dodatech.com/ns/low',
      },
    },
  });
});

function jsonldResource(id, type, properties, links) {
  const resource = {
    '@context': CONTEXT_URL,
    '@id': id,
    '@type': type,
    ...properties,
  };
  
  // Add links as properties with @id type
  for (const [rel, href] of Object.entries(links)) {
    resource[rel] = href;
  }
  
  return resource;
}

app.get('/threats/:id', (req, res) => {
  const threat = getThreat(req.params.id);
  
  res.json(jsonldResource(
    `/threats/${threat.id}`,
    'threat',
    {
      name: threat.name,
      description: threat.description,
      severity: threat.severity,
      dateCreated: threat.createdAt,
    },
    {
      device: `/devices/${threat.deviceId}`,
      analysis: `/threats/${threat.id}/analysis`,
    },
  ));
});

// Collection with JSON-LD
app.get('/threats', (req, res) => {
  const threats = getAllThreats();
  
  res.json(jsonldResource('/threats', 'Collection', {
    name: 'Threat Collection',
    total: threats.length,
    items: threats.map(t => ({
      '@id': `/threats/${t.id}`,
      '@type': 'threat',
      name: t.name,
      severity: t.severity,
    })),
  }));
});

class JsonLdClient {
  constructor(baseUrl) {
    this.baseUrl = baseUrl;
    this.contextCache = new Map();
  }
  
  async fetch(url) {
    const res = await fetch(`${this.baseUrl}${url}`);
    return res.json();
  }
  
  async resolveContext(doc) {
    if (!doc['@context']) return doc;
    
    let context = doc['@context'];
    if (typeof context === 'string') {
      // Fetch remote context
      if (!this.contextCache.has(context)) {
        const res = await fetch(context);
        const ctx = await res.json();
        this.contextCache.set(context, ctx['@context'] || ctx);
      }
      context = this.contextCache.get(context);
    }
    
    // Expand properties using context
    const expanded = { ...doc };
    delete expanded['@context'];
    
    for (const [key, value] of Object.entries(doc)) {
      if (key.startsWith('@')) continue;
      
      // Look up property meaning in context
      const def = context[key];
      if (typeof def === 'string') {
        console.log(`Property '${key}' maps to: ${def}`);
      } else if (def && def['@id']) {
        console.log(`Property '${key}' has IRI: ${def['@id']}`);
        if (def['@type'] === '@id' && typeof value === 'string') {
          // This is a link to another resource
          expanded[`_link_${key}`] = value;
        }
      }
    }
    
    return expanded;
  }
  
  async navigate() {
    // Fetch threat and understand its structure semantically
    const raw = await this.fetch('/threats/101');
    const expanded = await this.resolveContext(raw);
    
    console.log('Resource type:', expanded['@type']);
    console.log('Properties:', Object.keys(expanded)
      .filter(k => !k.startsWith('@')));
    
    // Follow semantic links
    if (expanded.device) {
      console.log(`Linked to device: ${expanded.device}`);
      const device = await this.fetch(expanded.device);
      console.log('Device:', device.name);
    }
    
    // Severity is typed - client understands the values
    const severity = expanded.severity;
    if (severity === 'critical' || severity === 'high') {
      console.log('Alert: High severity threat detected');
    }
  }
}