kme_content_adapter/specs/003-kme-content-fetch/data-model.md

Data Model: KME Article Content Fetch (003)

Phase 1 output for 003-kme-content-fetch

---

Entities

1. KME Article Content

Represents a single article fetched from the KME Content Service.

Field	Type	Source	Notes
vkm:url	string	KME Content Service JSON-LD	Identifies the article; used as the fetch target (kmeURL param)
vkm:articleBody	string | null	KME Content Service JSON-LD	HTML body of the article; may be absent, null, or empty

Validation rules:

• vkm:articleBody must be a non-empty, non-whitespace string to constitute a valid article body.
• Absent, null, empty string, and whitespace-only string are all treated as "article body not present" → 404.

State transitions: None. This is a read-only fetch — no mutations, no lifecycle.

---

2. OIDC Token

Short-lived bearer credential used to authenticate upstream requests to the KME Content Service.

Field	Type	Storage	Notes
id_token	string	Redis hash authorization:token	The OIDC id_token value
expiry	number (Unix epoch, seconds)	Redis hash authorization:expiry	Expiry timestamp; compared to Date.now() / 1000

Validation rules:

• Token is valid if cachedToken !== null && Date.now() / 1000 < expiry.
• Managed exclusively by getValidToken() in kmeContentSourceAdapterHelpers.js. Not modified by contentFetchFlow().

Managed by: getValidToken() (existing helper — unmodified).

---

3. Proxy Request

Incoming HTTP request received by the adapter, carrying routing signals and parameters.

Field	Type	Source	Notes
req.url	string	Node.js http.IncomingMessage	Relative path + query string, e.g. /?kmeURL=https://...
req.method	string	Node.js http.IncomingMessage	Always GET for content-fetch flow
kmeURL (extracted)	string	new URL(req.url, 'http://localhost').searchParams.get('kmeURL')	The verbatim target URL for upstream fetch

Validation rules for kmeURL:

1. Absent or empty: !kmeURL.trim() → 400 Bad Request (FR-007)
2. Malformed or non-absolute: new URL(kmeURL) throws, or protocol is not http:/https: → 400 Bad Request (FR-008)
3. Valid: passes both guards → proceed to token acquisition + upstream fetch

---

Data Flow

Incoming request (req.url contains ?kmeURL=...)
          │
          ▼
  Extract kmeURL from query string
  (new URL(req.url, 'http://localhost').searchParams.get('kmeURL'))
          │
          ▼
  ┌── Validate kmeURL ──────────────────────────────────────┐
  │  absent/empty?  ──────────────────────────────► 400     │
  │  malformed/non-https? ────────────────────────► 400     │
  └─────────────────────────────────────────────────────────┘
          │ valid
          ▼
  getValidToken() → OIDC token (from Redis cache or fresh fetch)
          │
          │  token fetch failed? ──────────────────► 502
          ▼
  axios.get(kmeURL, { Authorization: OIDC_id_token {token}, timeout: 10000 })
          │
          │  timeout?           ──────────────────► 502
          │  upstream 4xx?      ──────────────────► 404
          │  upstream 5xx?      ──────────────────► 502
          │  network error?     ──────────────────► 502
          ▼
  Parse response.data as JSON-LD object
          │
          │  unparseable?       ──────────────────► 502
          │  non-object?        ──────────────────► 502
          ▼
  extractArticleBody(data) → vkm:articleBody string or null
          │
          │  null (absent/empty/whitespace)? ─────► 404
          ▼
  res.writeHead(200, { 'Content-Type': 'text/html' })
  res.end(articleBody)

---

Helper: extractArticleBody(data)

Location: src/globalVariables/kmeContentSourceAdapterHelpers.js
Type: Pure function — no side effects, no state, no injected globals required
Added to exports: return { ..., extractArticleBody }

Signature:

function extractArticleBody(data) → string | null

Input/output contract:

Input	Output
{ 'vkm:articleBody': '<p>Hello</p>' }	'<p>Hello</p>'
{ 'vkm:articleBody': '' }	null
{ 'vkm:articleBody': ' ' }	null
{ 'vkm:articleBody': null }	null
{} (field absent)	null
null	null
'a string' (non-object)	null

Implementation:

function extractArticleBody(data) {
  if (!data || typeof data !== 'object') return null;
  const body = data['vkm:articleBody'];
  if (body == null || typeof body !== 'string' || body.trim() === '') return null;
  return body;
}

---

KME Content Service Response Shape

The KME Content Service returns a JSON-LD document. Only vkm:articleBody is consumed by this feature. Example:

{
  "@context": "https://vocabs.kme.example/context.jsonld",
  "@type": "vkm:Article",
  "vkm:url": "https://content.kme.example/articles/123",
  "vkm:articleBody": "<p>Article content here...</p>",
  "vkm:title": "Example Article"
}

All other fields are ignored by extractArticleBody. The proxy passes the raw HTML string of vkm:articleBody directly as the response body — no transformation, sanitisation, or re-encoding.

---

Settings Used (from kme_CSA_settings)

The content-fetch flow reads the same OIDC settings as oidcAuthFlow and sitemapFlow:

Field	Purpose
tokenUrl	OIDC token endpoint
username	OIDC username credential
password	OIDC password credential
clientId	OIDC client identifier
scope	OIDC requested scope

These are validated via kmeContentSourceAdapterHelpers.validateSettings() before calling getValidToken(). Missing fields produce a 500 Configuration Error response.