Skip to content

Conversion Rules

Markdown is canonical; the JSON-LD projection is regenerated from it (Invariant 2). The round trip MUST be lossless (Invariant 4).

  1. Parse the YAML frontmatter, including the authoritative relationships[] and entities[], 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).
  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.
{
"@context": "https://mif-spec.dev/schema/context.jsonld",
"@type": "Concept",
"@id": "urn:mif:550e8400-e29b-41d4-a716-446655440000",
"conceptType": "semantic",
"title": "Dark Mode",
"content": "# Dark Mode\n\nUser prefers dark mode\n\n## Relationships\n\n- relates-to [UI Preferences](/semantic/ui-prefs.md)",
"created": "2026-01-15T10:30:00Z",
"timestamp": "2026-01-15T10:30:00Z",
"relationships": [
{"type": "relates-to", "target": "/semantic/ui-prefs.md"}
]
}

The content field is written back verbatim as the body; relationships[] passes through to frontmatter; the derived timestamp mirror (Structure) is dropped, since Markdown never stores it. The round trip is lossless:

---
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
---
# Dark Mode
User prefers dark mode
## Relationships
- relates-to [UI Preferences](/semantic/ui-prefs.md)
  1. Parse the frontmatter citations array. Each entry is already a Citation object authored in its final shape (@type: Citation, citationType, citationRole, title, url, …).
  2. Pass each citation through to the JSON-LD projection verbatim — the converter performs no field renaming. Author values are preserved as written (plain text or an EntityReference).
  3. Any ## Citations body section is authored content carried inside content; the frontmatter citations array remains authoritative.
  1. Write the citations array back to frontmatter verbatim — each entry is already a Citation object (@type: Citation, citationType, citationRole, …) with author as plain text or an EntityReference; the converter performs no rewriting.
  2. Any ## Citations body section is authored content carried inside content and is preserved unchanged.

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).

# Frontmatter
citations:
- "@type": Citation
citationType: article
title: "Research Paper"
url: https://example.com/paper
citationRole: supports
author:
"@type": EntityReference
entity: { "@id": urn:mif:entity:person:jane-smith }
entityType: Person
name: Jane Smith

Converts to (passed through verbatim, so the fields are identical):

"citations": [{
"@type": "Citation",
"citationType": "article",
"title": "Research Paper",
"url": "https://example.com/paper",
"citationRole": "supports",
"author": {
"@type": "EntityReference",
"entity": {"@id": "urn:mif:entity:person:jane-smith"},
"entityType": "Person",
"name": "Jane Smith"
}
}]