Conversion Rules

Markdown is canonical; the JSON-LD projection is regenerated from it. The round trip MUST be lossless.

Markdown to JSON-LD

1. Parse the YAML frontmatter, including the authoritative relationships[], and map each property into the JSON-LD projection: id becomes @id (urn:mif:<id>), type becomes conceptType, and the remaining fields pass through under the context.
2. Take the full Markdown body, verbatim, as the content field. The OKF-legible ## Relationships body mirror is part of the body, so it is carried inside content.
3. Add the projection mirror fields the converter always emits: timestamp (= modified, else created) and, when summary is present, description (= summary).

JSON-LD to Markdown

1. Recover the frontmatter from the JSON-LD properties: @id (urn:mif:<uuid>) becomes id (<uuid>), conceptType becomes type, and the remaining properties (including relationships[]) pass through.
2. Write the content field back as the Markdown body, verbatim. Any ## Relationships body mirror is authored content preserved unchanged, which is what keeps the round trip lossless.

Example Conversion

Input (JSON-LD):

{
  "@context": "https://mif-spec.dev/schema/context.jsonld",
  "@type": "Concept",
  "conceptType": "semantic",
  "@id": "urn:mif:550e8400-e29b-41d4-a716-446655440000",
  "title": "Dark Mode",
  "content": "User prefers dark mode\n\n## Relationships\n\n- relates-to [UI Preferences](/semantic/ui-prefs.md)",
  "created": "2026-01-15T10:30:00Z",
  "relationships": [
    {"type": "relates-to", "target": "/semantic/ui-prefs.md"}
  ]
}

Output (Markdown):

---
id: 550e8400-e29b-41d4-a716-446655440000
type: semantic
created: 2026-01-15T10:30:00Z
title: Dark Mode
relationships:
  - type: relates-to
    target: /semantic/ui-prefs.md
---

User prefers dark mode

## Relationships

- relates-to [UI Preferences](/semantic/ui-prefs.md)

Citations Conversion

citations is authored in frontmatter in its final shape and passes through to the JSON-LD projection verbatim (it is part of the converter’s passthrough set, so the frontmatter and projection forms are identical). Each entry is a Citation object: @type, citationType, citationRole, title, and url are required; author, date, accessed, relevance, and note are optional. The author value is plain text, an EntityReference, or an array of EntityReference (for multiple authors), and is preserved as written. Any ## Citations body mirror is authored content carried inside content.

Example (frontmatter, identical in the JSON-LD projection):

citations:
  - "@type": Citation
    citationType: article
    citationRole: supports
    title: "Research Paper"
    url: https://example.com/paper
    author: "Jane Smith"
    date: "2025-11-15"
    accessed: "2026-01-18"
    relevance: 0.92