Schemas

Overview

OMI-AI ships two JSON Schemas, both written against JSON Schema Draft 2020-12 ($schema: https://json-schema.org/draft/2020-12/schema):

L0 Core — $id https://open-memory-interchange.example/schema/0.1/omi-l0.schema.json
L1 Interchange — $id https://open-memory-interchange.example/schema/0.1/omi-l1.schema.json

Both schemas validate the same envelope object. The top-level required list is format, version, and memories, and every record is validated against the shared record definition in $defs.

The schemas are deliberately lenient and open: additionalProperties is true at the envelope level, on every record, and on every reusable sub-object. Unknown top-level fields, unknown record fields, and unknown ext profiles do not cause rejection — they pass validation untouched. This matches the conformance rule that a consumer MUST NOT reject a record solely because optional, unknown, or unknown-extension fields are present.

The schemas are advisory. They define structural validation, while the prose defines semantics. Some conformance rules cannot be expressed portably in JSON Schema 2020-12 and are therefore checked outside the schema by an OMI-AI validator — notably record id uniqueness within a file, and (for L1) presence of an effective subject on every record. See Validation notes and the spec's validation model (§15).

Download L0 schema Download L1 schema

L0 Core vs L1 Interchange

Both schemas share the same envelope properties and the same set of reusable definitions in $defs. L1 adds exactly two structural constraints on top of L0:

An effective subject is required. L1 adds a top-level anyOf that is satisfied when either the envelope carries a subject, or every item in memories validates against the recordWithSubject definition (a record that additionally requires its own subject). L0 has no such constraint.
type is required on every record. The L0 record definition requires id, content, and created. The L1 record definition requires id, content, created, and type.

L0 — Core

Structural floor

Required record fields: id, content, created
No effective-subject constraint
Envelope subject is optional
Shares all $defs with L1 (no recordWithSubject)

L1 — Interchange

Core plus interchange guarantees

Required record fields: id, content, created, type
Top-level anyOf: envelope subject OR every record carries its own subject
Adds the recordWithSubject definition
Identical envelope properties and other $defs to L0

Aspect	L0 Core	L1 Interchange
Envelope `required`	`format`, `version`, `memories`	`format`, `version`, `memories`
Record `required`	`id`, `content`, `created`	`id`, `content`, `created`, `type`
Effective subject	Not enforced	Top-level `anyOf`: envelope `subject`, or every record via `recordWithSubject`
Shared `$defs`	Yes	Yes (plus `recordWithSubject`)
Envelope properties	Identical	Identical
`additionalProperties`	`true` (open)	`true` (open)

Envelope properties

The top-level object is the envelope. These are its properties in both schemas; format, version, and memories are the only required ones. Additional, unrecognized envelope keys are allowed.

Property	Type	Required	Description
`format`	`const` `"open-memory-interchange"`	Yes	Format identity. MUST be the literal string `"open-memory-interchange"`.
`version`	string, pattern `^[0-9]+\.[0-9]+$`	Yes	Format version as `major.minor`. This document defines `"0.1"`.
`serialization`	`enum` [`json`]	No	Serialization marker. `"json"` for `.omi.json`; defaults to `"json"` when absent in a JSON file.
`subject`	object (`$defs/subject`)	No (L0); effectively required at L1 unless every record carries its own	Default subject inherited by records that omit a record-level `subject`.
`id_namespace`	string, `minLength` 1	No	Optional namespace used to scope non-global record IDs during merge/import.
`generated_at`	date-time (`$defs/dateTime`)	No	When the export file was produced. RFC 3339 date-time.
`generator`	string	No	Producing tool and version, e.g. `"example-tool/1.4"`.
`memories`	array of `$defs/record`	Yes	Zero or more record objects. MAY be empty.
`ext`	object	No	File-level extension profiles.

Record properties

Each item of memories is validated against the record definition. At L0 the required fields are id, content, and created; at L1, type is also required. Records are open: unknown record fields are permitted.

Property	Type	Required	Description
`id`	string, `minLength` 1	Yes (L0 & L1)	Opaque non-empty record identifier. MUST be unique within the file at L1 (checked outside the schema).
`content`	string	Yes (L0 & L1)	The memory as human-readable text; may contain Markdown. The neutral anchor of a record.
`created`	date-time (`$defs/dateTime`)	Yes (L0 & L1)	When the memory was first recorded. RFC 3339 date-time.
`type`	string	L1 only	Open-vocabulary memory type. Optional at L0, required at L1.
`subject`	object (`$defs/subject`)	No	Record-level subject. Overrides the envelope subject for this record.
`updated`	date-time (`$defs/dateTime`)	No	When the record was last materially updated. RFC 3339 date-time if present.
`confidence`	number, `minimum` 0, `maximum` 1	No	Asserted belief strength or source confidence, in `[0.0, 1.0]`.
`lang`	string, pattern `^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$`	No	BCP 47 language tag for `content`, e.g. `en`, `ar`, `en-GB`.
`tags`	array of string	No	Free-form labels.
`source`	object (`$defs/source`)	No	Lightweight provenance / source hint.
`valid_from`	date or date-time (`$defs/dateOrDateTime`)	No	Start of real-world validity.
`valid_to`	date, date-time, or null (`$defs/dateOrDateTimeOrNull`)	No	End of real-world validity. `null` or absent means open/unknown.
`entities`	array of `$defs/entity`	No	Descriptive entity mentions or references.
`relations`	array of `$defs/relation`	No	Typed links to local records or external references.
`ext`	object	No	Record-level extension profiles.

Shared definitions ($defs)

Both schemas define a set of reusable subschemas under $defs. L0 and L1 share all of these; L1 adds one more, recordWithSubject.

date — a string with format: date and pattern ^\d{4}-\d{2}-\d{2}$ (calendar date).
dateTime — a string with format: date-time and an RFC 3339 date-time pattern (used by generated_at, created, updated).
dateOrDateTime — anyOf date or dateTime (used by valid_from).
dateOrDateTimeOrNull — anyOf date, dateTime, or null (used by valid_to).
subject — object that requires id (non-empty); optional type and label; open to extra keys.
source — object with optional platform, ref, and method strings; open to extra keys.
entity — object that requires id (non-empty); optional label and type; open to extra keys.
relation — object that requires type and target (both non-empty); optional label; open to extra keys.
record — the memory record object (required fields differ by level, as described above); open to extra keys.
recordWithSubject (L1 only) — allOf the record definition plus an additional required: ["subject"], used by the L1 effective-subject anyOf.

Validation notes

JSON Schema validates structural shape; some OMI-AI conformance rules need additional checks beyond the schema. Faithful to the spec's validation model (§15.1, §15.3):

What the schemas can enforce:

Required envelope fields (format, version, memories) and required record fields (L0: id, content, created; L1 also type).
Date-time field shape — but only when validators enable the format assertion (the schemas also back this with explicit patterns).
Validity boundary shape (valid_from / valid_to) via the date / date-time / null definitions, again with the format assertion enabled.
Effective subject — mostly. The L1 schema enforces "envelope subject, or record-level subjects on every record" for the JSON form via its top-level anyOf.

What the schemas cannot enforce (must be implemented by an OMI-AI validator outside pure JSON Schema):

Unique record IDs by the id property across memories[] — not portably expressible in JSON Schema 2020-12. L1 validators MUST implement this check separately.
Reference / relation target resolution — implemented by the OMI-AI validator, not the schema.
Merge conflict detection — implemented by merge tools.
Profile validation — each profile validates its own ext.<profile> block.

Note that the L1 effective-subject rule surfaces in the schema only as an opaque anyOf failure. For rules that JSON Schema cannot express clearly — notably ID uniqueness and effective subject — a validator SHOULD emit a human-readable diagnostic naming the specific failing rule rather than a raw schema-combinator error. In short, conformance checking goes beyond schema validation.

L0 Core schema

The complete omi-l0.schema.json, reproduced verbatim:

omi-l0.schema.json Download ↓

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://open-memory-interchange.example/schema/0.1/omi-l0.schema.json",
  "title": "Open Memory Interchange 0.1 L0 Core",
  "type": "object",
  "required": [
    "format",
    "version",
    "memories"
  ],
  "properties": {
    "format": {
      "const": "open-memory-interchange"
    },
    "version": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+$"
    },
    "serialization": {
      "enum": [
        "json"
      ]
    },
    "subject": {
      "$ref": "#/$defs/subject"
    },
    "id_namespace": {
      "type": "string",
      "minLength": 1
    },
    "generated_at": {
      "$ref": "#/$defs/dateTime"
    },
    "generator": {
      "type": "string"
    },
    "memories": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/record"
      }
    },
    "ext": {
      "type": "object"
    }
  },
  "$defs": {
    "date": {
      "type": "string",
      "format": "date",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "dateTime": {
      "type": "string",
      "format": "date-time",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$"
    },
    "dateOrDateTime": {
      "anyOf": [
        {
          "$ref": "#/$defs/date"
        },
        {
          "$ref": "#/$defs/dateTime"
        }
      ]
    },
    "dateOrDateTimeOrNull": {
      "anyOf": [
        {
          "$ref": "#/$defs/date"
        },
        {
          "$ref": "#/$defs/dateTime"
        },
        {
          "type": "null"
        }
      ]
    },
    "subject": {
      "type": "object",
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "type": {
          "type": "string",
          "minLength": 1
        },
        "label": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "source": {
      "type": "object",
      "properties": {
        "platform": {
          "type": "string"
        },
        "ref": {
          "type": "string"
        },
        "method": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "entity": {
      "type": "object",
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "label": {
          "type": "string"
        },
        "type": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "relation": {
      "type": "object",
      "required": [
        "type",
        "target"
      ],
      "properties": {
        "type": {
          "type": "string",
          "minLength": 1
        },
        "target": {
          "type": "string",
          "minLength": 1
        },
        "label": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "record": {
      "type": "object",
      "required": [
        "id",
        "content",
        "created"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "subject": {
          "$ref": "#/$defs/subject"
        },
        "content": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "created": {
          "$ref": "#/$defs/dateTime"
        },
        "updated": {
          "$ref": "#/$defs/dateTime"
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "lang": {
          "type": "string",
          "pattern": "^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "source": {
          "$ref": "#/$defs/source"
        },
        "valid_from": {
          "$ref": "#/$defs/dateOrDateTime"
        },
        "valid_to": {
          "$ref": "#/$defs/dateOrDateTimeOrNull"
        },
        "entities": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/entity"
          }
        },
        "relations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/relation"
          }
        },
        "ext": {
          "type": "object"
        }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true
}

L1 Interchange schema

The complete omi-l1.schema.json, reproduced verbatim:

omi-l1.schema.json Download ↓

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://open-memory-interchange.example/schema/0.1/omi-l1.schema.json",
  "title": "Open Memory Interchange 0.1 L1 Interchange",
  "type": "object",
  "required": [
    "format",
    "version",
    "memories"
  ],
  "properties": {
    "format": {
      "const": "open-memory-interchange"
    },
    "version": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+$"
    },
    "serialization": {
      "enum": [
        "json"
      ]
    },
    "subject": {
      "$ref": "#/$defs/subject"
    },
    "id_namespace": {
      "type": "string",
      "minLength": 1
    },
    "generated_at": {
      "$ref": "#/$defs/dateTime"
    },
    "generator": {
      "type": "string"
    },
    "memories": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/record"
      }
    },
    "ext": {
      "type": "object"
    }
  },
  "anyOf": [
    {
      "required": [
        "subject"
      ]
    },
    {
      "properties": {
        "memories": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/recordWithSubject"
          }
        }
      }
    }
  ],
  "$defs": {
    "date": {
      "type": "string",
      "format": "date",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
    },
    "dateTime": {
      "type": "string",
      "format": "date-time",
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$"
    },
    "dateOrDateTime": {
      "anyOf": [
        {
          "$ref": "#/$defs/date"
        },
        {
          "$ref": "#/$defs/dateTime"
        }
      ]
    },
    "dateOrDateTimeOrNull": {
      "anyOf": [
        {
          "$ref": "#/$defs/date"
        },
        {
          "$ref": "#/$defs/dateTime"
        },
        {
          "type": "null"
        }
      ]
    },
    "subject": {
      "type": "object",
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "type": {
          "type": "string",
          "minLength": 1
        },
        "label": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "source": {
      "type": "object",
      "properties": {
        "platform": {
          "type": "string"
        },
        "ref": {
          "type": "string"
        },
        "method": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "entity": {
      "type": "object",
      "required": [
        "id"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "label": {
          "type": "string"
        },
        "type": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "relation": {
      "type": "object",
      "required": [
        "type",
        "target"
      ],
      "properties": {
        "type": {
          "type": "string",
          "minLength": 1
        },
        "target": {
          "type": "string",
          "minLength": 1
        },
        "label": {
          "type": "string"
        }
      },
      "additionalProperties": true
    },
    "record": {
      "type": "object",
      "required": [
        "id",
        "content",
        "created",
        "type"
      ],
      "properties": {
        "id": {
          "type": "string",
          "minLength": 1
        },
        "subject": {
          "$ref": "#/$defs/subject"
        },
        "content": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "created": {
          "$ref": "#/$defs/dateTime"
        },
        "updated": {
          "$ref": "#/$defs/dateTime"
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        },
        "lang": {
          "type": "string",
          "pattern": "^[A-Za-z]{2,8}(-[A-Za-z0-9]{1,8})*$"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "source": {
          "$ref": "#/$defs/source"
        },
        "valid_from": {
          "$ref": "#/$defs/dateOrDateTime"
        },
        "valid_to": {
          "$ref": "#/$defs/dateOrDateTimeOrNull"
        },
        "entities": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/entity"
          }
        },
        "relations": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/relation"
          }
        },
        "ext": {
          "type": "object"
        }
      },
      "additionalProperties": true
    },
    "recordWithSubject": {
      "allOf": [
        { "$ref": "#/$defs/record" },
        { "required": ["subject"] }
      ]
    }
  },
  "additionalProperties": true
}