Context Object Specification (COS)

Version: 0.2
Chapter: 240 — Semantic
Status: Informative — Supporting
Category: Core Model

1. Purpose

This chapter defines optional semantic classification guidance for the Context Object Specification (COS).

In COS v0.2 lean core, semantic classification is represented by context.segments[].type and optional context.segments[].role.

This chapter exists to explain classification constraints. It does not define a required top-level semantic field.

2. Conceptual Role

If:

• Document = space
• Hierarchy = structure
• Selection = input anchor

Then:

Semantic = meaning attribution layer

It answers:

“What does this part of the document represent?”

3. Definition

A Semantic Context is a structured annotation that assigns interpretability to a node or region within a Document.

It does NOT interpret meaning in natural language terms.

It assigns categorical, structural, or functional meaning.

4. Core Principle

Semantic in COS is:

Classification of meaning, not explanation of meaning

This is critical.

Semantic layer MUST NOT:

• generate explanations
• produce summaries
• infer user intent
• perform reasoning

It ONLY classifies content.

5. Semantic Scope

Semantic annotations MAY apply to:

• text nodes
• hierarchy nodes
• selections
• document fragments

But semantic MUST always reference a structural anchor (Hierarchy Node or Selection).

6. Lean Core Representation

interface ContextSegment {
  type: SemanticType;
  role?: SemanticRole;
}

7. Semantic Type

SemanticType defines what kind of content this is structurally.

type SemanticType =
  | "text"
  | "code"
  | "table"
  | "list"
  | "heading"
  | "quote"
  | "formula";

These types are intentionally closed in v0.2 to ensure stability.

Metadata-like source fields, such as HTML meta tags or document front matter, MUST NOT use a separate SemanticType in v0.2.

They SHOULD be represented as ordinary content when selected, or as Document Metadata / Extension data when they describe system or source attributes.

8. Semantic Role

SemanticRole defines functional meaning inside a system context.

type SemanticRole =
  | "definition"
  | "example"
  | "instruction"
  | "argument"
  | "reference"
  | "output"
  | "code_snippet";

Role is optional and context-dependent.

9. Anchoring Rule

Every SemanticContext MUST be anchored to:

• a Hierarchy Node OR
• a Selection-derived Node

Unanchored semantic data is invalid.

This ensures traceability.

10. Whole-Selection Classification

When a SemanticContext is attached to a Selection, it represents a deterministic classification of the Selection as a whole.

If a Selection spans multiple structural nodes with the same SemanticType, Producers MAY emit one SemanticContext anchored to a Selection-derived or Hierarchy node.

If a Selection spans multiple structural nodes with different SemanticTypes, Producers MUST NOT collapse the result into text.

In such cases, Producers SHOULD omit SemanticContext and allow Consumers to inspect document.content.children and Hierarchy for the mixed structure.

This preserves the distinction between:

• a Selection that is semantically ordinary text
• a Selection whose structure is mixed and therefore cannot be assigned one deterministic SemanticType

11. Separation from Hierarchy

Hierarchy answers:

“Where is this?”

Semantic answers:

“What is this?”

Example:

They MUST NOT be merged.

12. Deterministic Constraint

Semantic classification SHOULD be deterministic under identical inputs.

If nondeterminism exists (e.g., ML inference), confidence MUST be provided.

13. No Reasoning Rule

Semantic layer MUST NOT include:

• reasoning chains
• explanations
• interpretations of intent
• natural language summaries

Those belong to Consumer Layer (AI or external systems).

14. Relationship to Context Object

Semantic classification is embedded in Context Segments:

Context Object
   └── context
        └── segments[]
             ├── type
             └── role?

15. Example (Informative)

{
  "nodeId": "p-1",
  "type": "code",
  "role": "definition",
  "confidence": 0.97
}

16. Design Notes

Semantic layer is intentionally minimal in v0.2.

Its purpose is to:

• enable downstream reasoning systems
• standardize content classification
• avoid coupling with AI-specific logic

Future versions MAY expand role taxonomy or introduce graph-based semantic relations.

17. Summary

Semantic layer defines what content is, not what content means in natural language.

It is the bridge between structural representation and higher-level interpretation systems.

Within COS, it is the first layer that introduces meaning classification without reasoning.