Context Object Specification (COS)

Version: 0.2
Chapter: 420 — Compatibility
Status: Normative — Plugin and Adapter Profiles
Category: Plugin Model

1. Purpose

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

The Compatibility Model specifies how COS implementations, Plugins, Adapters, and Extensions maintain interoperability across different versions and environments.

The goal of compatibility is to enable ecosystem evolution without breaking existing integrations.

2. Definition

Compatibility describes the ability of different COS components to work together while maintaining semantic correctness.

COS compatibility applies to:

• Core Model
• Pipeline
• Plugins
• Adapters
• Extensions
• Consumers

3. Core Principle

COS follows:

Capability-based Compatibility over Implementation-based Compatibility

Systems SHOULD depend on declared capabilities rather than specific implementations.

Example:

Preferred:

Requires:

pdf.annotation

Not:

Requires:

PDFPlugin v2.1

4. Compatibility Layers

COS v0.2 defines four compatibility layers:

Core Object Compatibility
        ↓
Plugin Compatibility
        ↓
Adapter Compatibility
        ↓
Extension Compatibility

Each layer has independent capability rules.

5. Core Object Compatibility

Core Object Compatibility means a system can consume the lean v0.2 Context Object shape.

Example:

source
selection
context
meta?
extensions?

Core compatibility MUST consider:

• data model changes
• interface changes
• lifecycle changes

6. Semantic Compatibility

Compatibility is not only structural.

Two systems are compatible only when they preserve the same meaning.

Example:

Compatible:

{
 "selection": {
   "text":"hello"
 }
}

Incompatible:

{
 "selection": {
   "text":"hello",
   "meaning":"translated"
 }
}

if the original semantic meaning changed.

7. Plugin Compatibility

Plugins MUST declare compatibility information.

Example:

interface PluginCompatibility {
  cosVersion: string;
  capabilities: string[];
}

Example:

{
 "plugin":"pdf-plugin",
 "version":"1.2.0",
 "cosVersion":"0.2",
 "capabilities":[
   "pdf.annotation"
 ]
}

8. Capability Negotiation

COS uses capability negotiation.

Before activation:

Runtime

     asks

Plugin Capabilities

     compares

Required Capabilities

Example:

Required:

[
 "annotation",
 "coordinate"
]

Plugin:

[
 "annotation",
 "coordinate",
 "render"
]

Result:

Compatible.

9. Version Negotiation

COS protocol versions and component versions use different formats.

The Context Object version and cosVersion identify a two-part protocol line:

major.minor

Example:

0.2

Plugin, Adapter, and Extension versions MUST use semantic versioning:

major.minor.patch

Compatibility rules:

Major Version

May contain breaking changes.

1.x

≠

2.x

Minor Version

Should preserve declared capabilities.

1.1

compatible with

1.2

Patch Version

Should contain fixes only.

1.1.1

compatible with

1.1.2

10. Unknown Extension Handling

Unknown extensions SHOULD be ignored safely.

Core Context Object fields MUST remain usable when an implementation does not understand an extension.

Example:

Context Object
  ├── source
  ├── selection
  ├── context
  └── extensions.unknown

The Consumer SHOULD read the core object and ignore the unknown extension.

Example:

{
 "extensions":[
   {
     "namespace":"org.example.future-capability",
     "version":"1.0.0",
     "payload":{}
   }
 ]
}

11. Extension Compatibility

Extensions MUST be isolated.

Example:

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

A system without PDF support SHOULD still process:

{
 "version":"0.2",
 "source":{"type":"pdf","title":"Report"},
 "selection":{"text":"Annotation"},
 "context":{
   "scope":"container",
   "segments":[{"type":"text","text":"Annotation"}]
 },
 "extensions":[{
   "namespace":"org.example.pdf",
   "version":"1.0.0",
   "payload":{"annotation":{}}
 }]
}

12. Adapter Compatibility

Adapters MUST declare:

source compatibility output compatibility capability support

Example:

{
 "source":"PDF.js",
 "supportedVersions":[
   "4.x",
   "5.x"
 ]
}

13. Deprecation Strategy

COS components SHOULD support controlled deprecation.

A deprecated capability SHOULD:

• remain available for a transition period
• provide replacement guidance when removing extension features
• announce removal version

Example:

Capability:

pdf.oldAnnotation

Status:

deprecated

Replacement:

pdf.annotation

14. Compatibility Checking

A COS Runtime SHOULD perform compatibility validation before execution.

Example:

Load Plugin
      ↓
Check Version
      ↓
Check Capability
      ↓
Activate

15. Compatibility Failure

Compatibility failures MUST be explicit.

Example:

{
 "status":"failed",
 "reason":"missing capability",
 "required":"pdf.annotation"
}

Failures SHOULD NOT silently degrade behavior.

16. Isolation Principle

A compatibility failure in one component MUST NOT affect unrelated components.

Example:

PDF Plugin incompatible
        ↓
PDF features unavailable
        ↓
Browser features continue working

17. Compatibility Matrix

Implementations MAY maintain compatibility matrices.

Example:

18. Relationship to Other Specifications

Compatibility completes the Plugin Model:

400 Plugin Specification
        ↓
410 Adapter
        ↓
420 Compatibility

19. Summary

Compatibility defines how COS evolves without breaking interoperability.

Through:

• capability negotiation
• semantic versioning
• isolation
• extension boundaries

COS enables a sustainable plugin ecosystem while preserving Core Model stability.