Conversion Rules
Markdown is canonical; the JSON-LD projection is regenerated from it (Invariant 2). The round trip MUST be lossless (Invariant 4).
Markdown to JSON-LD
Section titled “Markdown to JSON-LD”- Parse the YAML frontmatter, including the authoritative
relationships[]andentities[], and map each property into the JSON-LD projection:idbecomes@id(urn:mif:<id>),typebecomesconceptType, and the remaining fields pass through under the context. - Take the full Markdown body, verbatim, as the
contentfield. The OKF-legible## Relationshipsbody mirror is part of the body, so it is carried insidecontent. - Add the projection mirror fields the converter always emits:
timestamp(=modified, elsecreated) and, whensummaryis present,description(=summary).
JSON-LD to Markdown
Section titled “JSON-LD to Markdown”- Recover the frontmatter from the JSON-LD properties:
@id(urn:mif:<uuid>) becomesid(<uuid>),conceptTypebecomestype, and the remaining properties (includingrelationships[]) pass through. - Write the
contentfield back as the Markdown body, verbatim. Any## Relationshipsbody mirror is authored content preserved unchanged, which is what keeps the round trip lossless.
Example Conversion
Section titled “Example Conversion”Input (JSON-LD)
Section titled “Input (JSON-LD)”{ "@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"} ]}Output (Markdown)
Section titled “Output (Markdown)”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-446655440000type: semanticcreated: 2026-01-15T10:30:00Ztitle: Dark Moderelationships: - type: relates-to target: /semantic/ui-prefs.md---
# Dark Mode
User prefers dark mode
## Relationships
- relates-to [UI Preferences](/semantic/ui-prefs.md)Citations Conversion
Section titled “Citations Conversion”Markdown to JSON-LD
Section titled “Markdown to JSON-LD”- Parse the frontmatter
citationsarray. Each entry is already aCitationobject authored in its final shape (@type: Citation,citationType,citationRole,title,url, …). - 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). - Any
## Citationsbody section is authored content carried insidecontent; the frontmattercitationsarray remains authoritative.
JSON-LD to Markdown
Section titled “JSON-LD to Markdown”- Write the
citationsarray back to frontmatter verbatim — each entry is already aCitationobject (@type: Citation,citationType,citationRole, …) withauthoras plain text or anEntityReference; the converter performs no rewriting. - Any
## Citationsbody section is authored content carried insidecontentand 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).
Example
Section titled “Example”# Frontmattercitations: - "@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 SmithConverts 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" }}]