Context Object Specification (COS)

Version: 0.2
Chapter: 510 — Best Practices
Status: Informative
Category: Adoption & Evolution

1. Purpose

This chapter defines recommended practices for implementing and extending the Context Object Specification (COS).

These practices help maintain:

• Core stability
• Semantic consistency
• Plugin interoperability
• Long-term ecosystem evolution

2. Core Philosophy

COS follows the principle:

Keep the Core minimal, keep Extensions flexible, keep Capabilities composable.

A healthy COS implementation should preserve:

• Stable Core
• Flexible Extensions
• Composable Plugins

3. Keep Core Model Stable

3.1 Principle

The Core Model represents universal concepts.

Core fields SHOULD only contain concepts shared across domains.

Good:

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

Bad:

interface Selection {
  pdfPageNumber:number;
  domPath:string;
  codeSymbol:string;
}

3.2 Rule

Before adding a Core field, ask:

Does every COS implementation need this concept?

If the answer is no:

Use Extension.

4. Prefer Extension Over Core Modification

Domain-specific information SHOULD be placed in Extensions.

Example:

PDF:

{
  "extensions": [
    {
      "namespace": "org.example.pdf",
      "version": "1.0.0",
      "payload": {
        "page": 12
      }
    }
  ]
}

Code:

{
  "extensions": [
    {
      "namespace": "org.example.code",
      "version": "1.0.0",
      "payload": {
        "symbol": "calculate"
      }
    }
  ]
}

Do not introduce:

Document {
  pdfInfo;
  codeInfo;
}

5. Keep Plugin Boundaries Clear

A Plugin provides capabilities.

A Plugin SHOULD NOT become:

• application logic container
• business workflow engine
• AI orchestration layer

Correct:

Plugin
↓
Capability
↓
Context Enrichment

Incorrect:

Plugin
↓
Complete Application

6. Use Adapter for Translation

Adapters exist at system boundaries.

Their responsibility:

External Representation
        ↓
COS Representation

Adapters SHOULD:

• normalize data
• preserve source information
• translate events

Adapters SHOULD NOT:

• perform reasoning
• generate recommendations
• call AI models directly

7. Keep Pipeline Stages Focused

Each Pipeline Stage SHOULD have a single responsibility.

Good:

Selection Stage
↓
Source Stage
↓
Context Stage

Bad:

AI Stage

does:

- parsing
- analysis
- recommendation
- storage
- UI rendering

8. Progressive Context Enrichment

Context Objects SHOULD be enriched progressively.

Recommended:

Selection Created
        ↓
Source Attached
        ↓
Context Segments Added
        ↓
Relations Added

Avoid blocking the entire Context Object until all processing completes.

9. Preserve Original Context

The original user context SHOULD remain unchanged.

Example:

Original:

{
 "selection":{
   "text":"original text"
 }
}

AI result:

{
 "extensions":{
   "summary":"generated summary"
 }
}

Do not overwrite:

{
 "selection":{
   "text":"AI rewritten text"
 }
}

10. AI Should Be a Consumer

AI is a capability consumer, not the foundation of COS.

Relationship:

Context Object
        ↓
AI Consumer
        ↓
Result

COS SHOULD NOT depend on:

• specific LLM providers
• prompt formats
• model versions

11. Prefer Capability-Based Design

Consumers SHOULD request capabilities.

Preferred:

Requires:

semantic.analysis

Avoid:

Requires:

OpenAIPluginV3

Capabilities allow:

• multiple implementations
• easier replacement of implementation providers
• ecosystem growth

12. Design for Partial Availability

A Context Object does not need every field populated.

Example:

Available:

Selection

Source

context.segments

Later:

context.relations

extensions or meta

Systems SHOULD handle partial contexts gracefully.

13. Avoid Context Overloading

Context Object SHOULD represent:

User attention and relevant information.

It SHOULD NOT become:

• application state
• database model
• user profile
• workflow state

Bad:

{
 "context":{
   "userSettings":{},
   "shoppingCart":{},
   "permissions":{}
 }
}

14. Version Extensions Independently

Extensions SHOULD maintain independent evolution.

Example:

COS

v0.2


PDF Extension

v1.5

Do not require:

COS update

for every Extension change

15. Design for Observability

Implementations SHOULD provide visibility into:

• Context lifecycle
• Pipeline stages
• Plugin execution
• Extension generation

Example:

context.created
↓
context.relations.completed
↓
extensions.updated

16. Handle Failure Gracefully

A failed enrichment SHOULD NOT destroy existing context.

Example:

Optional Enrichment Failed
        ↓
Context remains usable

Prefer:

{
 "status":"partial",
 "available":[
   "selection",
   "source",
   "context.segments"
 ]
}

17. Security Considerations

Implementations SHOULD:

• validate external input
• isolate plugins
• control extension access
• protect sensitive context data
• minimize captured data to the active Selection and required surrounding context
• redact or omit sensitive source fields when transport does not require them
• preserve browser security boundaries, including Content Security Policy constraints
• avoid exposing raw DOM nodes, live editor objects, credentials, cookies, or authentication headers
• sandbox Plugin and Adapter execution when they process untrusted source content

Browser-based implementations SHOULD treat page URL, title, DOM path, selected text, and surrounding text as potentially sensitive.

Consumers SHOULD request only the Context Object fields and Extension namespaces required for their task.

18. Performance Guidance

Implementations SHOULD make basic context available quickly and defer expensive enrichment.

Recommended behavior:

• Structural Pipeline stages SHOULD run synchronously or with minimal delay when possible
• optional extension or product recommendation stages MAY run asynchronously
• large source documents SHOULD be represented by anchors and nearby context rather than full-document payloads
• Extensions SHOULD avoid duplicating core fields
• Meta SHOULD record minimal stages when useful

Implementations MAY define local size and latency budgets.

When a budget is exceeded, the Pipeline SHOULD emit a partial Context Object instead of blocking availability.

19. Recommended Architecture

A recommended COS implementation:

                 Consumer
                    ↑
             Context Object
                    ↑
               Pipeline
                    ↑
              Adapter
                    ↑
             External System

Plugins extend capabilities without breaking this structure.

20. Common Mistakes

Mistake 1

Putting domain fields into Core.

Solution:

Use Extension.

Mistake 2

Making Plugin responsible for everything.

Solution:

Separate Adapter, Pipeline, Consumer.

Mistake 3

Embedding AI concepts into protocol.

Solution:

Keep AI as Consumer.

Mistake 4

Treating Context as database storage.

Solution:

Keep Context focused on active user attention.

21. Summary

Best Practices ensure that COS remains:

• stable
• extensible
• interoperable
• AI-ready

The fundamental rule:

Preserve the Core, extend through Plugins, enrich through Pipeline, and consume through Context-aware systems.