Skip to content

Relationship Types

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

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

.mif/config.yaml
relationship_types:
# Core types (RECOMMENDED for interoperability)
- name: RelatesTo
description: General semantic relationship
symmetric: true
icon: 🔗
- name: DerivedFrom
description: Concept created based on source
inverse: Derives
icon: ⬅️
- name: Supersedes
description: Replaces an older concept
inverse: SupersededBy
icon: ⏫
- name: ConflictsWith
description: Contradicts another concept
symmetric: true
icon: ⚠️
- name: PartOf
description: Component of a larger whole
inverse: Contains
icon: 🧩
- name: Implements
description: Realizes a concept or pattern
inverse: ImplementedBy
icon: ✅
- name: Uses
description: Utilizes a technology or tool
inverse: UsedBy
icon: 🔧
- name: Created
description: Authored by an entity
inverse: CreatedBy
icon: ✍️
- name: MentionedIn
description: Referenced within a concept
inverse: Mentions
icon: 📎
# Custom types (domain-specific)
- name: Reinforces
namespace: subcog
description: Strengthens confidence in another concept
inverse: ReinforcedBy
icon: 💪
- name: Contradicts
namespace: subcog
description: Provides evidence against another concept
inverse: ContradictedBy
icon: ❌
- name: BreedsWith
namespace: farm
description: Animal breeding relationship
symmetric: false
properties:
- name: breeding_date
type: date
- name: success
type: boolean

A declared name (and inverse) is a PascalCase display name, as schema/relationship-types-config.schema.json requires. The token that is stored in frontmatter relationships[].type, written in the body mirror (Relationship Syntax), and emitted in JSON-LD is derived from it mechanically:

  1. Insert a hyphen before every uppercase letter except the first character, then lowercase the result: DerivedFrom → derived-from, ConflictsWith → conflicts-with, Uses → uses.
  2. If the declaration has a namespace, prefix the token with <namespace>:. For example, name: BreedsWith with namespace: farm becomes farm:breeds-with. Core types have no namespace and no prefix.
  3. An inverse maps by the same rule, under the same namespace prefix as its type: Derives (inverse of DerivedFrom) becomes derives, and ReinforcedBy (inverse of subcog’s Reinforces) becomes subcog:reinforced-by. A symmetric type is its own inverse.

Every token produced this way matches the schema’s Relationship.type pattern, ^[a-z0-9][a-z0-9-]*(:[a-z0-9][a-z0-9-]*)?$. Rule 1 splits at every capital, so names SHOULD NOT contain consecutive capitals: write HttpProxy (→ http-proxy), not HTTPProxy (→ h-t-t-p-proxy).

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

Type Description Inverse Symmetric
RelatesTo General relationship RelatesTo Yes
DerivedFrom Created based on source Derives No
Supersedes Replaces older concept SupersededBy No
ConflictsWith Contradicts another concept ConflictsWith Yes
PartOf Component of larger whole Contains No
Implements Realizes a concept/pattern ImplementedBy No
Uses Utilizes a technology/tool UsedBy No
Created Authored by entity CreatedBy No
MentionedIn Referenced in concept Mentions No

Providers MAY define additional relationship types using namespaced URIs:

# Custom relationship type definition
relationship_types:
- name: BreedsWith
namespace: farm # Results in type token: farm:breeds-with (§8.1.1)
description: Animal breeding relationship
symmetric: false
properties:
- name: breeding_date
type: date
- name: success
type: boolean

JSON-LD representation of custom relationship types

Section titled “JSON-LD representation of custom relationship types”
{
"@context": [
"https://mif-spec.dev/schema/context.jsonld",
{"farm": "https://example.org/farm/"}
],
"relationships": [
{
"type": "farm:breeds-with",
"target": "urn:mif:entity:animal:ram-001",
"strength": 1.0,
"metadata": {
"farm:breeding_date": "2025-10-15",
"farm:success": true
}
}
]
}

Relationships are mirrored in the body as standard markdown links under a ## Relationships section:

## Relationships
- relates-to [Other Concept](/semantic/other-concept.md)
- derived-from [Source Concept](/episodic/source-concept.md)
- supersedes [Old Concept](/semantic/old-concept.md)
- conflicts-with [Contradicting Concept](/semantic/contradicting-concept.md)
- part-of [Parent Concept](/semantic/parent-concept.md)

Each line is - <type> [Text](<target>). The type is a kebab-case token derived from the configured type name (Type Tokens); the target is a bundle-relative path to the target concept or a urn:mif: identifier. The frontmatter relationships[] array is authoritative; the body links are its OKF-legible mirror.

Same-bundle targets SHOULD be bundle-relative paths, with urn:mif: targets reserved for out-of-bundle concepts (Relationship Syntax).

The matching frontmatter (one entry per body link):

relationships:
- type: relates-to
target: /semantic/other-concept.md
- type: derived-from
target: /episodic/source-concept.md
- type: supersedes
target: /semantic/old-concept.md
- type: conflicts-with
target: /semantic/contradicting-concept.md
- type: part-of
target: /semantic/parent-concept.md

The JSON-LD projection carries each target unchanged from frontmatter. A same-bundle target stays a bundle-relative path; only an out-of-bundle target is a urn:mif:<uuid>:

"relationships": [
{
"type": "derived-from",
"target": "/episodic/source-concept.md",
"strength": 0.9,
"metadata": {
"reason": "Extracted key insight",
"extractedAt": "2026-01-15T10:30:00Z"
}
}
]
Property Type Required Description
type String Yes Type identifier (kebab-case; optional ns: prefix)
target String Yes Bundle-relative path to the target concept, or a urn:mif: identifier
strength Decimal No Relationship strength (0.0-1.0)
metadata Object No Additional relationship metadata