Skip to content
MIF

Getting Started

This guide walks you through implementing the Modeled Information Format (MIF) in your project. It tracks MIF specification 1.4.2.

Prerequisites

  • Basic understanding of YAML and Markdown (JSON-LD is optional)
  • A text editor or IDE
  • (Optional) Python 3.10+ and Node.js 22+ for the tooling in the MIF repository

Quick Start

Step 1: Create Your First Concept

A MIF concept is a Markdown file with YAML frontmatter, stored in an OKF bundle (a directory of .md concept files). The Markdown file is canonical; JSON-LD is a projection derived from it. Start with the required fields:

---
id: 550e8400-e29b-41d4-a716-446655440000
type: semantic
created: 2026-01-26T10:00:00Z
---


User prefers dark mode for all applications.

The id is a UUID: it is the concept’s stable identity and survives the file being moved or renamed. Save the file inside your bundle as semantic/dark-mode-preference.md. Its OKF identity is that bundle-relative path minus .md, so use a readable, path-meaningful slug for the filename.

Step 2: Add Metadata

Expand with recommended fields:

---
id: 550e8400-e29b-41d4-a716-446655440000
type: semantic
created: 2026-01-26T10:00:00Z
modified: 2026-01-26T10:00:00Z
namespace: _semantic/preferences
title: "Dark Mode Preference"
tags:
  - ui
  - accessibility
  - preference
---


# Dark Mode Preference


User prefers dark mode for all applications including:
- IDE and code editors
- Terminal emulators
- Web applications
- Mobile apps

Step 3: Declare an Ontology (Optional)

If using a custom ontology, declare it:

---
id: 3f2a9c4e-8b1d-4e6f-a5c7-9d0b2e4f6a81
type: semantic
created: 2026-01-26T10:00:00Z
ontology:
  id: regenerative-agriculture
  version: "0.1.0"
namespace: _semantic/livestock
---


Herd of 85 Angus-cross beef cattle managed with adaptive multi-paddock grazing.

Knowledge Types

MIF uses three base knowledge types, a general taxonomy of how knowledge is structured:

Type Description Use For
semantic Facts, concepts, and knowledge Decisions, preferences, facts, domain knowledge
episodic Events and experiences Incidents, sessions, conversations, timelines
procedural How-to processes Runbooks, patterns, migration guides, workflows

Specific categorization is expressed through namespaces (e.g., _semantic/decisions, _episodic/incidents).

Conformance Levels

MIF supports three conformance levels.

Level 1: Core (Minimal)

Level 1 requires a valid OKF bundle (a directory of .md concept files), the id (UUID), type, and created frontmatter fields, a non-empty Markdown body, and relationship edges (when a concept has any) written as markdown links in a ## Relationships section, as in the Level 2 example below. A JSON-LD file on its own is not Level 1 conformant.

---
id: 9a4e2b7c-1d3f-4c5a-8e6b-0f2d4a6c8e10
type: semantic
created: 2026-01-26T10:00:00Z
---


Concept content here.

Add namespaces, entities, and relationships:

---
id: 7b3c1e90-5a2f-4c8d-9e10-2f6a4b8c1d3e
type: semantic
created: 2026-01-26T10:00:00Z
modified: 2026-01-26T10:00:00Z
namespace: _semantic/decisions
title: "Use PostgreSQL for Data Storage"
tags:
  - database
  - architecture
relationships:
  - type: relates-to
    target: /semantic/database-requirements.md
  - type: supersedes
    target: /semantic/sqlite-investigation.md
entities:
  - "@type": EntityReference
    entity: { "@id": urn:mif:entity:technology:postgresql }
    entityType: Technology
    name: PostgreSQL
  - "@type": EntityReference
    entity: { "@id": urn:mif:entity:technology:mysql }
    entityType: Technology
    name: MySQL
---


# Use PostgreSQL for Data Storage


## Context


We need a relational database for the new service.


## Decision


PostgreSQL for:
- Strong JSON support
- Excellent performance
- Team familiarity


## Relationships


- relates-to [Database Requirements](/semantic/database-requirements.md)
- supersedes [SQLite Investigation](/semantic/sqlite-investigation.md)

Relationships are authoritative in frontmatter and mirrored as OKF-legible body markdown links, so a generic OKF consumer sees every edge. A target in the same bundle is a bundle-relative path, as above; a concept outside the bundle is referenced as urn:mif:<uuid>.

Level 3: Full

Add temporal metadata, provenance, and citations:

---
id: 2c8e4a6f-0b1d-4f3a-9c5e-7d9b1f3a5c70
type: semantic
created: 2026-01-26T10:00:00Z
temporal:
  validFrom: 2026-01-26T00:00:00Z
  recordedAt: 2026-01-26T10:00:00Z
  ttl: P365D
  decay:
    model: exponential
    halfLife: P30D
    strength: 1.0
provenance:
  sourceType: user_explicit
  agent: claude-opus-4
  confidence: 0.95
  trustLevel: user_stated
citations:
  - "@type": Citation
    citationType: documentation
    citationRole: background
    title: "PostgreSQL Documentation"
    url: https://www.postgresql.org/docs/
    relevance: 0.9
---


Concept content here.

Freshness Values: The halfLife: P30D means freshness strength halves every 30 days. Common values: P7D (short-term), P14D (medium-term), P30D (long-term). These are pragmatic freshness defaults, not prescriptive values; the cognitive-memory rationale behind them lives in the AI Memory profile. See Specification §9.3, Freshness Rationale for details.

Naming Convention: Concept frontmatter fields use camelCase, and so does the JSON-LD projection (e.g. validFrom, recordedAt, sourceType, trustLevel, citationType). The temporal, provenance, embedding, and citations blocks are carried into the projection unchanged, so author them with the schema’s camelCase field names. Keys in .mif/ configuration files (such as config.yaml) use snake_case instead.

Directory Structure

Organize your MIF bundle with one directory per base type. A bundle has no memories/ root:

my-bundle/
├── .mif/
│   ├── config.yaml           # Bundle configuration
│   └── entities/             # Entity definitions
├── index.md                  # OKF reserved filename (optional bundle docs)
├── semantic/                 # Facts, concepts, knowledge
│   ├── dark-mode-preference.md
│   └── decisions/
├── episodic/                 # Events, experiences
│   └── incidents/
├── procedural/               # Processes, how-to
│   └── runbooks/
└── my-project.ontology.yaml  # Custom ontology (optional)

Every .md file in the bundle other than the OKF reserved filenames index.md and log.md is a concept and needs concept frontmatter, so put bundle documentation in index.md, not a frontmatter-less README.md. Directory placement is independent of the frontmatter namespace: semantic/dark-mode-preference.md can declare namespace: _semantic/preferences.

Using Custom Ontologies

Create an Ontology

my-project.ontology.yaml
ontology:
  id: my-project
  version: "0.1.0"
  description: "Custom ontology for my project"


namespaces:
  features:
    description: "Product features"
    type_hint: semantic
  sprints:
    description: "Sprint records"
    type_hint: episodic


entity_types:
  - name: feature
    base: semantic
    traits: [lifecycle]
    schema:
      required: [name, status]
      properties:
        name: { type: string }
        status: { type: string, enum: [planned, active, deprecated] }

Reference in Concepts

---
id: 5e7a9c1b-3d5f-4a7c-9e1b-3d5f7a9c1b20
type: semantic
created: 2026-01-26T10:00:00Z
ontology:
  id: my-project
  version: "0.1.0"
namespace: _semantic/features
aliases:
  - feature-dark-mode
---


# Dark Mode Feature


Status: active
Priority: high

JSON-LD Projection

For machine processing, derive the JSON-LD projection from the Markdown source rather than authoring it by hand:

Terminal window
# From a checkout of the MIF repository
python scripts/mif_convert.py emit-jsonld my-bundle --out-dir dist/jsonld

This writes one .jsonld file per concept to dist/jsonld/<bundle>/<type>/<slug>.jsonld, mirroring the source paths (here, dist/jsonld/my-bundle/semantic/dark-mode-preference.jsonld). The emitted files are build output; do not commit them to the bundle. The projection of the Step 2 concept looks like this (content abbreviated):

{
  "@context": "https://mif-spec.dev/schema/context.jsonld",
  "@type": "Concept",
  "@id": "urn:mif:550e8400-e29b-41d4-a716-446655440000",
  "conceptType": "semantic",
  "title": "Dark Mode Preference",
  "content": "# Dark Mode Preference\n\nUser prefers dark mode for all applications including: ...",
  "created": "2026-01-26T10:00:00Z",
  "modified": "2026-01-26T10:00:00Z",
  "timestamp": "2026-01-26T10:00:00Z",
  "namespace": "_semantic/preferences",
  "tags": ["ui", "accessibility", "preference"]
}

The concept @id is always urn:mif:<uuid>, where <uuid> is the frontmatter id. The frontmatter type becomes conceptType; memoryType and @type: "Memory" are deprecated aliases that are still accepted but should not be emitted.

Validation

Validate a bundle and its projections from a checkout of the MIF repository:

Terminal window
# OKF bundle shape and relationship links
python scripts/okf_validate.py my-bundle


# Install ajv-cli + ajv-formats
npm install -g ajv-cli ajv-formats


# Validate the JSON-LD projection of a concept.
# The converter emits .jsonld; ajv-cli reads .json, so validate a .json copy.
python scripts/mif_convert.py emit-jsonld my-bundle --out-dir dist/jsonld
cp dist/jsonld/my-bundle/semantic/dark-mode-preference.jsonld dark-mode-preference.json
npx ajv validate -s schema/mif.schema.json -r "schema/definitions/*.schema.json" \
  -d dark-mode-preference.json --spec=draft2020 -c ajv-formats


# Validate a citation
npx ajv validate -s schema/citation.schema.json -r "schema/definitions/*.schema.json" \
  -d citation.json --spec=draft2020 -c ajv-formats


# Validate ontology files (ajv-cli does not read YAML; use the project validator).
# Pass --path: with no --path the script looks for the MIF repo's own
# ontologies/ directory, which moved to the ontologies repo (ADR-018).
python scripts/validate-ontologies.py --path my-bundle

Converting Ontologies

Convert YAML ontologies to JSON-LD:

Terminal window
# Single file
python scripts/yaml2jsonld.py my-project.ontology.yaml


# Every *.ontology.yaml under a directory
python scripts/yaml2jsonld.py --all --path <path-to-directory>

The published ontology corpus lives in the ontologies repository and is served at mif-spec.dev/ontologies/.

Next Steps

Getting Help