Skip to content

File Format

Extension Format MIME Type
.md Markdown (canonical) text/markdown; variant=mif
.jsonld JSON-LD (derived projection) application/ld+json; profile="https://mif-spec.dev"

Concept files use the .md extension only. The derived JSON-LD projection uses .jsonld (never .md), so OKF’s *.md glob never ingests it.

A concept’s OKF identity is its bundle-relative path minus the .md extension, so concept files SHOULD use human-readable, path-meaningful slugs. The stable UUID lives in the frontmatter id (Concept), not in the filename, so identity survives the concept being moved or renamed; the id is MIF-only and invisible to OKF:

semantic/dark-mode-preference.md

A UUID filename (550e8400-e29b-41d4-a716-446655440000.md) MAY be used, but it adds nothing the frontmatter id does not already carry.

The JSON-LD projection is not stored beside its source. It is derived output (Invariant 2), emitted on demand into a separate directory:

Terminal window
python scripts/mif_convert.py emit-jsonld <bundle> --out-dir dist/jsonld

which writes dist/jsonld/<bundle>/<type>/<slug>.jsonld, mirroring each source path. Emitted .jsonld files SHOULD NOT be committed to the bundle.

A MIF bundle SHOULD follow this structure:

bundle/
├── .mif/ # MIF configuration
│ ├── config.yaml # Bundle configuration
│ ├── context.jsonld # Local JSON-LD context
│ └── entities/ # Entity definitions
│ ├── person/
│ ├── organization/
│ ├── technology/
│ ├── concept/
│ └── file/
├── index.md # OKF reserved filename (optional)
├── semantic/ # One directory per base type
│ └── {slug}.md
├── episodic/
│ └── {slug}.md
└── procedural/
└── {slug}.md

Every .md file in the bundle other than the OKF reserved filenames index.md and log.md is a concept and needs concept frontmatter. Bundle documentation therefore belongs in index.md; a frontmatter-less README.md at the bundle root would be read as an invalid concept.

Concepts MAY be nested in subdirectories below their type directory (for example semantic/preferences/dark-mode-preference.md). Directory placement is independent of the frontmatter namespace: semantic/rate-limit-policy.md may declare namespace: _semantic/policies. A bundle has no memories/ root and contains no .jsonld concept files.

Keys in .mif/ configuration files (config.yaml, namespace and entity definition files) use snake_case, e.g. relationship_types, default_ttl, conformance_level. Concept frontmatter fields use camelCase, e.g. validFrom, sourceType, compressedAt. The keys inside the free-form extensions and relationship metadata objects are not constrained by either convention.