File Format
File Extensions
Section titled “File Extensions”| 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.
File Naming
Section titled “File Naming”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.mdA 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:
python scripts/mif_convert.py emit-jsonld <bundle> --out-dir dist/jsonldwhich writes dist/jsonld/<bundle>/<type>/<slug>.jsonld, mirroring each
source path. Emitted .jsonld files SHOULD NOT be committed to the bundle.
Directory Structure
Section titled “Directory Structure”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}.mdEvery .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.