Context Object Specification (COS)

Version: 0.2
Chapter: 200 — Context Object
Status: Normative
Category: Core Model

1. Purpose

This chapter defines the Context Object of the Context Object Specification (COS).

The Context Object is the portable data object handed from a Producer to a Consumer.

Its purpose is simple:

Preserve what the user selected, where it came from, and the minimum source-grounded context needed to use it correctly.

2. First Principle

COS exists because raw selected text is not enough.

Raw selected text answers only:

What characters did the user select?

A Context Object answers:

• what was selected
• where it came from
• what local context surrounds it
• what deterministic relationships make it meaningful

COS MUST optimize for Consumer usefulness, not protocol ceremony.

3. Definition

A Context Object is a JSON-compatible object representing a user Selection together with source and context.

It MUST be:

• concise
• deterministic
• source-grounded
• easy for Consumers to read
• independent of UI rendering and AI prompt formats

It MUST NOT include:

• prompt text
• generated answers
• reasoning chains
• execution plans
• UI state
• inferred user intent

4. Lean Core Model

COS v0.2 defines the following lean core shape:

interface ContextObject {
  version: "0.2";
  source: SourceContext;
  selection: Selection;
  context: Context;
  meta?: Meta;
  extensions?: ExtensionEntry[];
}

The core object intentionally has few top-level fields.

Top-level fields SHOULD NOT duplicate the same source, structure, or lifecycle information in multiple places.

5. Source

source describes the origin of the selected content.

interface SourceContext {
  type: "webpage" | "pdf" | "markdown" | "editor" | "richtext" | "unknown";
  id?: string;
  uri?: string;
  title?: string;
  app?: string;
  language?: string;
}

source is the single place for origin information in the emitted Context Object.

Consumers SHOULD use source to answer:

Where did this selected content come from?

6. Selection

selection describes the exact user-selected text and optional range.

interface Selection {
  text: string;
  range?: SelectionRange;
}

Selection MUST preserve the selected text as observed by the Producer.

Selection SHOULD NOT carry duplicated source metadata. Source belongs to the top-level source field.

7. Context

context describes the source-grounded local context that makes the Selection usable.

interface Context {
  scope: "inline" | "container" | "multi-container";
  segments: ContextSegment[];
  relations?: ContextRelation[];
}

context.segments is the primary context surface for Consumers.

Each segment describes one logical source container covered by the Selection.

context.relations describes deterministic relationships that apply to the whole Selection or summarize covered relationships.

The normative definition of Context is provided in Chapter 225.

8. Meta

meta describes minimal system-level information about object generation.

interface Meta {
  createdAt?: number;
  adapter?: string;
  stages?: string[];
}

COS v0.2 keeps meta intentionally small.

createdAt is the number of milliseconds since the Unix epoch, equivalent to JavaScript Date.now().

stages MAY list the minimal generation stages that contributed to the object, such as selection, source, context, and relations.

Detailed pipeline traces, integrity hashes, and debug data SHOULD be placed in Extensions unless a Consumer explicitly requires them.

9. Extensions

extensions provide platform-specific or implementation-specific data.

Examples:

• browser DOM path
• selected HTML
• PDF coordinates
• editor block IDs
• debug pipeline trace

Extensions MUST NOT be required to understand the core Context Object.

10. Output Shape Rule

The emitted COS v0.2 object MUST use only the lean top-level fields defined in this chapter:

version
source
selection
context
meta?
extensions?

Supporting concepts in later chapters explain how Producers derive these fields.

They MUST NOT introduce additional top-level domains.

This keeps the emitted object easy to consume without cross-field joins.

11. Example: Table Cell

{
  "version": "0.2",
  "source": {
    "type": "webpage",
    "title": "Product Table",
    "uri": "about:srcdoc"
  },
  "selection": {
    "text": "$19"
  },
  "context": {
    "scope": "container",
    "segments": [
      {
        "id": "cell-1",
        "type": "table",
        "text": "$19",
        "selectedText": "$19",
        "relations": [
          { "type": "column_header", "label": "Base price" },
          { "type": "row_header", "label": "Starter" }
        ]
      }
    ]
  },
  "meta": {
    "adapter": "web-adapter"
  }
}

12. Example: Multi-Container Selection

{
  "version": "0.2",
  "source": {
    "type": "webpage",
    "title": "Mixed Article"
  },
  "selection": {
    "text": "adapter should preserve nearby context...\nSelections can begin..."
  },
  "context": {
    "scope": "multi-container",
    "segments": [
      {
        "id": "p1",
        "type": "paragraph",
        "text": "The adapter should preserve nearby context without turning the selection into a prompt.",
        "selectedText": "adapter should preserve nearby context without turning the selection into a prompt.",
        "beforeText": "The "
      },
      {
        "id": "li1",
        "type": "list",
        "text": "Selections can begin in ordinary prose.",
        "selectedText": "Selections can begin in ordinary prose."
      }
    ],
    "relations": [
      { "type": "section", "label": "Pricing Rules" }
    ]
  }
}

13. Consumer Rule

Consumers SHOULD be able to use a Context Object by reading only:

source
selection.text
context.segments
context.relations

If a Consumer must inspect Extensions to understand the selected content, the Producer has failed to provide sufficient core context.

14. Summary

The Context Object is not a protocol showcase.

It is the smallest useful object that lets Consumers understand selected content without guessing.