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	`schema/mif.schema.json`
`citation.schema.json`	Standalone citation validation	`schema/citation.schema.json`
`ontology.schema.json`	Ontology definition validation	`schema/ontology/ontology.schema.json`

All schemas use JSON Schema Draft 2020-12.

MIF Document Schema

File: schema/mif.schema.json 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 defaults inspired by Ebbinghaus’s forgetting curve research, adapted for AI memory systems. See the Specification for detailed rationale and scientific background.

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

File: schema/citation.schema.json 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

File: schema/ontology/ontology.schema.json 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 schema/mif.schema.json -d memory.json

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

# Validate multiple files
npx ajv validate -s 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

Production schemas will be 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)

During development, reference local files or GitHub raw URLs.