Entity References

What is an EntityRef?

An EntityRef is a structured reference to another entity, used inside properties or relationship metadata. Any object with a pi field is treated as an EntityRef.

interface EntityRef {
  pi: string;       // Required - persistent identifier (entity ID)
  type?: string;    // Optional - type hint (e.g. "file", "user")
  label?: string;   // Optional - display hint (e.g. "My Document")
}

Usage

EntityRefs let you embed references to other entities inside property values:

{
  "properties": {
    "author": {
      "pi": "01JUSER...",
      "type": "user",
      "label": "Alice Smith"
    },
    "source_document": {
      "pi": "01JFILE...",
      "type": "file",
      "label": "Original Report.pdf"
    }
  }
}

EntityRef vs Relationships

Rule of thumb: Use relationships for structural connections that should be traversable. Use EntityRefs for metadata references that are informational.

Detection

The system automatically detects EntityRefs by looking for objects with a pi field. No special annotation is needed -- just include pi and it's treated as a reference.