Schema Reference

This document provides a complete reference for all MIF JSON Schemas.

Overview

MIF provides three primary JSON Schemas for validation:

Schema	Purpose	Location
`mif.schema.json`	Complete MIF document validation	`https://mif-spec.dev/schema/mif.schema.json`
`citation.schema.json`	Standalone citation validation	`https://mif-spec.dev/schema/citation.schema.json`
`ontology.schema.json`	Ontology definition validation	`https://mif-spec.dev/schema/ontology/ontology.schema.json`

Supporting schemas cover the rest of the format: definitions/entity-reference.schema.json (entity references, $ref’d by the two schemas above), document-reference.schema.json (standalone DocumentReference, ADR-014), container.schema.json (the optional Container Profile, ADR-021), and relationship-types-config.schema.json (custom relationship types declared in .mif/config.yaml). Each is served under https://mif-spec.dev/schema/.

All schemas use JSON Schema Draft 2020-12. Canonical $id values are unversioned and stable; each MIF release also publishes an immutable versioned mirror (for example https://mif-spec.dev/schema/1.4.2/mif.schema.json, plus latest/ and the major alias v1/) for consumers that need to pin a version. This page tracks MIF specification 1.4.2.

MIF Document Schema

ID: https://mif-spec.dev/schema/mif.schema.json

Required Fields

Field	Type	Description
`@context`	string/array/object	JSON-LD context
`@type`	`"Concept"` (or array containing `"Concept"`; the deprecated alias `"Memory"` is also accepted)	Document type
`@id`	string (pattern: `^urn:mif:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$`)	Concept URN `urn:mif:<uuid>`; `<uuid>` is the frontmatter `id` (Specification §6.1)
`conceptType`	enum	Knowledge taxonomy classification
`content`	string (minLength: 1)	Concept content: the Markdown body of the `.md` file, a named property only in the JSON-LD projection
`created`	string (date-time)	Creation timestamp

memoryType is a deprecated v0.1 alias for conceptType, retained for backward compatibility. New documents MUST use conceptType. The schema requires one of the two: a document carrying only memoryType still satisfies the type check.

Knowledge Types

MIF uses three base knowledge types:

"conceptType": {
  "enum": [
    "semantic",    // Facts, concepts, decisions, preferences, knowledge
    "episodic",    // Events, experiences, sessions, incidents
    "procedural"   // Processes, runbooks, patterns, how-to guides
  ]
}

(The deprecated v0.1 alias memoryType accepts the same enum.)

Type	Description	Use For
`semantic`	Declarative knowledge	Facts, decisions, preferences, concepts
`episodic`	Time-bound experiences	Incidents, sessions, conversations
`procedural`	How-to knowledge	Runbooks, patterns, migration guides

Ontologies can define extended types that map to these base types via namespace conventions (e.g., _semantic/decisions, _episodic/incidents).

Optional Fields

Basic Metadata

Field	Type	Description
`title`	string	Human-readable title
`description`	string	OKF-recommended description (mapped from MIF `summary`)
`modified`	date-time	Last modification timestamp
`timestamp`	date-time	OKF-recommended mirror of `modified` (or `created`)
`namespace`	string (pattern)	Hierarchical scope
`tags`	array of strings	Classification tags
`aliases`	array of strings	Alternative names
`documents`	array of `DocumentReference`	Source documents carried by reference, not embedded (ADR-014). Each entry has `@type: "DocumentReference"` plus a `url` or an `id`; optional `documentType`, `hash` and other integrity metadata
`properties`	object (string → string/number/boolean/null)	First-class scalar key/value pairs (e.g. from a knowledge-graph literal-object triple) with no concept target, so they cannot be a relationship. Values MUST be scalar; nested objects/arrays are out of scope at Level 1

Ontology Reference

"ontology": {
  "@type": "OntologyReference",
  "id": "ontology-identifier",
  "version": "0.1.0",
  "uri": "https://example.com/ontology.yaml"
}

Field	Required	Description
`id`	Yes	Ontology identifier (pattern: `^[a-z][a-z0-9-]*$`)
`version`	No	Semantic version (pattern: `^\d+\.\d+\.\d+.*$`)
`uri`	No	URL to ontology definition

Entities

"entities": [
  {
    "@type": "EntityReference",
    "entity": { "@id": "urn:mif:entity:person:jane-doe" },
    "entityType": "Person",
    "name": "Jane Doe",
    "role": "author"
  }
]

Field	Required	Description
`@type`	Yes	Must be `"EntityReference"`
`entity`	Yes	Object with `@id` (pattern: `^urn:mif:entity:`)
`entityType`	No	`Person`, `Organization`, `Technology`, `Concept`, `File`
`name`	No	Display name
`role`	No	Role in the concept’s context

Relationships

"relationships": [
  {
    "type": "derived-from",
    "target": "/episodic/source-concept.md",
    "strength": 0.9,
    "metadata": { "reason": "Extracted insight" }
  }
]

Field	Required	Description
`type`	Yes	Kebab-case token (e.g. `derived-from`); optional `ns:` prefix
`target`	Yes	The related concept: a bundle-relative path (e.g. `/semantic/policy.md`) for a concept in the same bundle (RECOMMENDED), or `urn:mif:<uuid>` for one outside it
`strength`	No	0.0-1.0 relationship strength
`metadata`	No	Additional properties

Relationship Types:

Type	Description
`relates-to`	General relationship
`derived-from`	Created based on source
`supersedes`	Replaces an older concept
`conflicts-with`	Contradicts another concept
`part-of`	Component of larger whole
`implements`	Realizes a concept/pattern
`uses`	Utilizes a technology/tool
`created`	Authored by entity
`mentioned-in`	Referenced in a concept

Temporal Metadata

"temporal": {
  "@type": "TemporalMetadata",
  "validFrom": "2026-01-26T00:00:00Z",
  "validUntil": null,
  "recordedAt": "2026-01-26T10:00:00Z",
  "ttl": "P90D",
  "decay": {
    "model": "exponential",
    "halfLife": "P7D",
    "currentStrength": 0.85
  },
  "accessCount": 5,
  "lastAccessed": "2026-01-26T14:00:00Z"
}

Field	Type	Description
`validFrom`	date-time or null	When fact becomes valid
`validUntil`	date-time or null	When fact expires
`recordedAt`	date-time	Transaction time
`ttl`	ISO 8601 duration	Time-to-live
`decay.model`	enum	`none`, `linear`, `exponential`, `step`
`decay.halfLife`	ISO 8601 duration	Decay half-life
`decay.currentStrength`	0.0-1.0	Current strength (alias: `strength` in Markdown frontmatter)
`decay.lastReinforced`	date-time	When the concept was last reinforced
`accessCount`	integer	Times accessed
`lastAccessed`	date-time	Last access time
`reinforcementHistory`	array	Array of reinforcement events (see below)

Reinforcement History Entry:

Field	Required	Type	Description
`timestamp`	Yes	date-time	When reinforcement occurred
`event`	Yes	string	What triggered the reinforcement
`strengthDelta`	No	number	Strength change amount
`context`	No	string	Additional context about the reinforcement

Recommended Half-Life Values:

Duration	Use Case
`P7D`	Short-term context, episodic records
`P14D`	Medium-term project context
`P30D`	Long-term knowledge, semantic facts

These are pragmatic freshness defaults for how quickly knowledge of a given kind loses currency, not prescriptive values; the cognitive-memory rationale behind them lives in the AI Memory profile. See Specification §9.3, Freshness Rationale for detailed rationale.

Provenance

"provenance": {
  "@type": "prov:Entity",
  "sourceType": "user_explicit",
  "confidence": 0.95,
  "trustLevel": "user_stated"
}

Field	Values	Description
`sourceType`	`user_explicit`, `user_implicit`, `agent_inferred`, `external_import`, `system_generated`	How the concept was created
`confidence`	0.0-1.0	Confidence score
`trustLevel`	`verified`, `user_stated`, `high_confidence`, `moderate_confidence`, `low_confidence`, `uncertain`	Trust classification

Embedding Reference

"embedding": {
  "@type": "EmbeddingReference",
  "model": "text-embedding-3-small",
  "modelVersion": "2024-01",
  "dimensions": 1536,
  "sourceText": "The text that was embedded",
  "vectorUri": "urn:mif:vector:memory-id",
  "normalized": true
}

Citations

"citations": [
  {
    "@type": "Citation",
    "citationType": "article",
    "citationRole": "supports",
    "title": "Research Paper Title",
    "url": "https://example.com/paper",
    "author": "Jane Smith et al.",
    "date": "2024-06-15",
    "accessed": "2026-01-20",
    "relevance": 0.95,
    "note": "Key supporting evidence"
  }
]

See Citation Schema for full details.

Compression (Level 3)

Field	Type	Description
`summary`	string (max 500 chars)	Compressed content summary
`compressedAt`	date-time	When compression was applied

Extensions

"extensions": {
  "subcog": {
    "domain": "user",
    "hash": "sha256:abc123..."
  },
  "custom_provider": {
    "custom_field": "value"
  }
}

Citation Schema

ID: https://mif-spec.dev/schema/citation.schema.json

Required Fields

Field	Type	Description
`@type`	`"Citation"`	Must be Citation
`citationType`	enum or namespaced	Source category
`citationRole`	enum or namespaced	Relationship to the concept
`title`	string (minLength: 1)	Citation title
`url`	URI	Citation URL

Citation Types

Type	Description
`article`	Journal article, blog post
`book`	Published book
`paper`	Conference/research paper
`website`	General website
`documentation`	Technical documentation
`repository`	Code repository
`video`	Video content
`podcast`	Podcast episode
`specification`	Technical specification
`dataset`	Data source
`tool`	Software tool or service
`other`	Miscellaneous

Custom types use namespace prefix: acme:memo, research:lab-notes

Citation Roles

Role	Description
`supports`	Provides supporting evidence
`refutes`	Contradicts or disputes
`background`	General context/reference
`methodology`	Method or approach source
`contradicts`	Conflicts with claims
`extends`	Builds upon cited work
`derived`	Direct derivation source
`source`	Primary source material
`example`	Illustrative example
`review`	Critical review/analysis

Custom roles use namespace prefix: legal:precedent, research:replicates

Optional Fields

Field	Type	Description
`author`	EntityReference, array, or string	Author(s)
`date`	date (YYYY-MM-DD)	Publication date
`accessed`	date (YYYY-MM-DD)	Access date
`relevance`	0.0-1.0	Relevance score
`note`	string (max 1000 chars)	Annotation

Example

{
  "@type": "Citation",
  "citationType": "article",
  "citationRole": "supports",
  "title": "Memory Systems in AI Agents",
  "url": "https://arxiv.org/abs/2024.12345",
  "author": {
    "@type": "EntityReference",
    "entity": { "@id": "urn:mif:entity:person:jane-smith" },
    "entityType": "Person",
    "name": "Jane Smith"
  },
  "date": "2024-06-15",
  "accessed": "2026-01-20",
  "relevance": 0.95,
  "note": "Foundational paper on semantic memory"
}

Ontology Schema

ID: https://mif-spec.dev/schema/ontology/ontology.schema.json

Structure

ontology:
  id: my-ontology
  version: "0.1.0"
  description: "Description"
  schema_url: https://example.com/schema

namespaces:
  semantic:
    description: "Facts and concepts"
    type_hint: semantic
    children:
      decisions: {}
      knowledge: {}

entity_types:
  - name: component
    base: semantic
    traits: [versioned, documented]
    schema:
      required: [name]
      properties:
        name: { type: string }

traits:
  versioned:
    description: "Supports versioning"
    fields:
      version: { type: string }

relationships:
  implements:
    description: "Realizes a concept"
    from: [component]
    to: [concept]
    symmetric: false

discovery:
  enabled: true
  confidence_threshold: 0.8
  patterns:
    - content_pattern: "\\b(PostgreSQL|MySQL)\\b"
      suggest_entity: technology
      suggest_namespace: _semantic/entities

Ontology Metadata

Field	Required	Description
`id`	Yes	Identifier (pattern: `^[a-z][a-z0-9-]*$`)
`version`	Yes	Semantic version
`description`	No	Human description
`schema_url`	No	External schema URL

Namespace Definition

Field	Description
`description`	Namespace description
`type_hint`	Default base knowledge type: `semantic`, `episodic`, `procedural`
`replaces`	Base namespace this replaces
`children`	Child namespaces (recursive)

Entity Type Definition

Field	Required	Description
`name`	Yes	Type name (pattern: `^[a-z][a-z0-9-]*$`)
`base`	Yes	Base type: `semantic`, `episodic`, `procedural`
`description`	No	Type description
`traits`	No	Array of trait names
`schema`	No	JSON Schema for entity fields

Trait Definition

Field	Description
`description`	Trait description
`fields`	Field definitions (JSON Schema)
`requires`	Required MIF fields

Relationship Definition

Field	Description
`description`	Relationship description
`from`	Source entity types
`to`	Target entity types
`symmetric`	Whether bidirectional

Discovery Pattern

Field	Required	Description
`content_pattern`	No	Regex to match content
`file_pattern`	No	Glob to match files
`suggest_entity`	Yes	Entity type to suggest
`suggest_namespace`	No	Namespace to suggest

Validation

Using ajv-cli

The commands below run from a checkout of the MIF repository, which holds the schema files and scripts/mif_convert.py.

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

# Validate MIF document (ajv-cli reads .json)
npx ajv validate -s schema/mif.schema.json -r "schema/definitions/*.schema.json" \
  -d memory.json --spec=draft2020 -c ajv-formats

# Validate with verbose output
npx ajv validate -s schema/mif.schema.json -r "schema/definitions/*.schema.json" \
  -d memory.json --spec=draft2020 -c ajv-formats --verbose

# Validate a whole bundle: emit its JSON-LD projections, copy each to .json,
# then validate the copies
python scripts/mif_convert.py emit-jsonld my-bundle --out-dir dist/jsonld
find dist/jsonld -name '*.jsonld' -exec sh -c 'cp "$1" "${1%.jsonld}.json"' _ {} \;
npx ajv validate -s schema/mif.schema.json -r "schema/definitions/*.schema.json" \
  -d "dist/jsonld/**/*.json" --spec=draft2020 -c ajv-formats

Using Python

import json
from pathlib import Path

from jsonschema import Draft202012Validator, FormatChecker
from referencing import Registry, Resource

# Run from a checkout of the MIF repository. Register every local schema by
# its $id so relative $refs (e.g. ./definitions/entity-reference.schema.json)
# resolve offline, and check formats such as date-time and uri.
schemas = {p: json.loads(p.read_text()) for p in Path("schema").rglob("*.schema.json")}
registry = Registry().with_resources(
    (s["$id"], Resource.from_contents(s)) for s in schemas.values()
)

def validator_for(path: str) -> Draft202012Validator:
    return Draft202012Validator(
        schemas[Path(path)], registry=registry, format_checker=FormatChecker()
    )

document = json.loads(Path("memory.json").read_text())
for error in validator_for("schema/mif.schema.json").iter_errors(document):
    print(error.message)

FormatChecker needs the optional format dependencies to enforce date-time and uri (pip install "jsonschema[format]").

Common Validation Errors

Error	Cause	Fix
`@id must match pattern`	Invalid URN format	Use `urn:mif:<uuid>`, where `<uuid>` is the frontmatter `id`
`conceptType must be equal to one of`	Invalid type	Use valid concept type
`created must match format date-time`	Bad timestamp	Use ISO 8601 format
`namespace must match pattern`	Invalid namespace	Use alphanumeric with `/` separators

Schema URLs

Production schemas are available at:

https://mif-spec.dev/schema/mif.schema.json
https://mif-spec.dev/schema/citation.schema.json
https://mif-spec.dev/schema/ontology/ontology.schema.json
https://mif-spec.dev/schema/definitions/entity-reference.schema.json
https://mif-spec.dev/schema/document-reference.schema.json
https://mif-spec.dev/schema/container.schema.json
https://mif-spec.dev/schema/relationship-types-config.schema.json
https://mif-spec.dev/schema/context.jsonld (JSON-LD context)

During development, reference local files from a checkout of the MIF repository.