Schema Reference

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

Overview

MIF provides three 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

All schemas use JSON Schema Draft 2020-12.

---

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	"Memory" or array containing "Memory"	Document type
@id	string (pattern: ^urn:mif:)	Unique identifier
memoryType	enum	Memory classification
content	string (minLength: 1)	Memory content
created	string (date-time)	Creation timestamp

Memory Types

MIF uses three base memory types:

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

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
modified	date-time	Last modification timestamp
namespace	string (pattern)	Hierarchical scope
tags	array of strings	Classification tags
aliases	array of strings	Alternative names

Ontology Reference

"ontology": {
  "@type": "OntologyReference",
  "id": "ontology-identifier",
  "version": "1.0.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 memory context

Relationships

"relationships": [
  {
    "@type": "Relationship",
    "relationshipType": "DerivedFrom",
    "target": { "@id": "urn:mif:memory:source-id" },
    "strength": 0.9,
    "metadata": { "reason": "Extracted insight" }
  }
]

Field	Required	Description
@type	Yes	Must be "Relationship"
relationshipType	Yes	See relationship types below
target	Yes	Object with @id (pattern: ^urn:mif:)
strength	No	0.0-1.0 relationship strength
metadata	No	Additional properties

Relationship Types:

Type	Description
RelatesTo	General relationship
DerivedFrom	Created based on source
Supersedes	Replaces older memory
ConflictsWith	Contradicts another memory
PartOf	Component of larger whole
Implements	Realizes a concept/pattern
Uses	Utilizes a technology/tool
Created	Authored by entity
MentionedIn	Referenced in memory

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
accessCount	integer	Times accessed
lastAccessed	date-time	Last access time

Recommended Half-Life Values:

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

These values are pragmatic validity/freshness defaults. The cognitive-memory rationale for tuning them lives in the AI Memory profile. See the Specification 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 memory 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 memory
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: "1.0.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 memory 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

# Install
npm install -g ajv-cli

# Validate MIF document
npx ajv validate -s https://mif-spec.dev/schema/mif.schema.json -d memory.json

# Validate with verbose output
npx ajv validate -s https://mif-spec.dev/schema/mif.schema.json -d memory.json --verbose

# Validate multiple files
npx ajv validate -s https://mif-spec.dev/schema/mif.schema.json -d "memories/*.json"

Using Python

import json
import jsonschema

# Load schema
with open('schema/mif.schema.json') as f:
    schema = json.load(f)

# Load document
with open('memory.json') as f:
    document = json.load(f)

# Validate
jsonschema.validate(document, schema)

Common Validation Errors

Error	Cause	Fix
@id must match pattern	Invalid URN format	Use urn:mif: prefix
memoryType must be equal to one of	Invalid type	Use valid memory 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

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/context.jsonld (JSON-LD context)
• https://mif-spec.dev/schema/ontology/ontology.schema.json