Entity Types

MIF provides an extensible entity type system. Implementations SHOULD support the core types for interoperability, but MAY define custom types for domain-specific needs.

Entity Type Architecture

Entity types are not hard-coded. They are defined in bundle configuration and can be extended per-project:

.mif/config.yaml

entity_types:
  # Core types (RECOMMENDED for interoperability)
  - name: Person
    description: Human individual
    icon: "\U0001F464"
    color: blue
  - name: Organization
    description: Company, team, or group
    icon: "\U0001F3E2"
    color: purple
  - name: Technology
    description: Tool, language, or framework
    icon: "\U0001F527"
    color: green
  - name: Concept
    description: Abstract idea or topic
    icon: "\U0001F4A1"
    color: yellow
  - name: File
    description: Document or code file
    icon: "\U0001F4C4"
    color: gray

  # Custom types (domain-specific)
  - name: Project
    description: Work initiative or product
    icon: "\U0001F4E6"
    color: orange
  - name: Event
    description: Meeting, deadline, or occurrence
    icon: "\U0001F4C5"
    color: red
  - name: Location
    description: Physical or virtual place
    icon: "\U0001F4CD"
    color: teal

Core Entity Types (Recommended)

For maximum interoperability, implementations SHOULD recognize these five core types:

Type	Description	Example	URI
Person	Human individual	User, team member	mif:Person
Organization	Company, team, or group	Acme Corp	mif:Organization
Technology	Tool, language, or framework	Python, React	mif:Technology
Concept	Abstract idea or topic	Dark Mode	mif:Concept
File	Document or code file	src/main.py	mif:File

Custom Entity Types

Providers MAY define additional entity types using namespaced URIs:

# Custom type definition
entity_types:
  - name: Animal
    namespace: farm        # Results in URI: farm:Animal
    description: Livestock or pet
    properties:
      - name: breed
        type: string
      - name: birth_date
        type: date
      - name: registry_id
        type: string

JSON-LD representation of custom types:

{
  "@context": [
    "https://mif-spec.dev/schema/context.jsonld",
    {"farm": "https://example.org/farm/"}
  ],
  "@type": "farm:Animal",
  "@id": "urn:mif:entity:animal:sheep-001",
  "name": "Dolly",
  "farm:breed": "Dorper",
  "farm:birth_date": "2025-03-15"
}

Entity Subtyping (subtype_of)

An entity type MAY declare subtype_of, naming one or more parent entity types it specializes. A subtype is substitutable for any of its supertypes wherever the supertype is admissible — most notably a relationship endpoint domain: an edge whose from/to names a parent type also admits any of its subtypes.

entity_types:
  - name: incident-report
    base: episodic
  - name: security-incident
    base: episodic
    subtype_of: [incident-report]   # substitutable wherever incident-report is admissible

Rules (enforced by scripts/validate-ontologies.py):

• Every parent MUST resolve to a declared entity type — in this ontology, or in one it extends (resolved across the full extends chain).
• A subtype’s required set MUST include every required field of each parent (substitutability). A subtype SHOULD add, not retype, parent fields (retyping is not machine-checked).
• The subtype_of graph MUST be acyclic, and a type cannot be its own subtype.

subtype_of is optional and additive; ontologies that omit it are unaffected. It projects to JSON-LD as mif:subtypeOf (a set of entity-type @ids).

Entity Schema

Markdown (in .mif/entities/ directory):

.mif/entities/person/jane-doe.yaml

id: jane-doe
type: Person
name: Jane Doe
aliases:
  - J. Doe
  - jdoe
properties:
  email: jane@example.com
  role: Engineer

JSON-LD:

{
  "@context": "https://mif-spec.dev/schema/context.jsonld",
  "@type": "Person",
  "@id": "urn:mif:entity:person:jane-doe",
  "name": "Jane Doe",
  "aliases": ["J. Doe", "jdoe"],
  "properties": {
    "email": "jane@example.com",
    "role": "Engineer"
  }
}

Entity References in Memories

Entity references are declared in the frontmatter entities[] array as EntityReference objects.

Frontmatter:

entities:
  - "@type": EntityReference
    entity: { "@id": urn:mif:entity:person:jane-doe }
    entityType: Person
    name: Jane Doe
    role: mentions
  - "@type": EntityReference
    entity: { "@id": urn:mif:entity:technology:python }
    entityType: Technology
    name: Python
    role: uses

JSON-LD:

"entities": [
  {
    "@type": "EntityReference",
    "entity": {"@id": "urn:mif:entity:person:jane-doe"},
    "role": "mentions"
  }
]