Context Object Specification (COS)

Version: 0.2
Chapter: 230 — Hierarchy
Status: Informative — Supporting
Category: Core Model

1. Purpose

This chapter defines the Hierarchy Model within a Document in the Context Object Specification (COS).

Hierarchy describes how content is structurally organized and how meaning is distributed across nested units of a Document.

This model is independent of visual layout and rendering systems.

2. Conceptual Role

Hierarchy represents the structural skeleton of a Document.

If:

• Document defines the space
• Content defines the material

Then:

Hierarchy defines the structure of meaning within that space.

3. Definition

A Hierarchy is a tree-structured representation of logical content organization inside a Document.

It defines:

• containment relationships
• structural nesting
• logical segmentation

Hierarchy does NOT define:

• visual appearance
• layout rules
• rendering behavior

4. Core Principle

Hierarchy in COS is:

Logical Structure, not Visual Structure

This distinction is fundamental.

A visually similar layout MAY represent different hierarchy.

A structurally identical hierarchy MAY render differently.

5. Hierarchy Model (Conceptual)

A Document Hierarchy is defined as a tree:

interface Hierarchy {
  root: HierarchyNode;
}

6. Hierarchy Node

A Hierarchy Node represents a structural unit in a Document.

interface HierarchyNode {
  id: string;
  type: HierarchyType;
  title?: string;
  children?: HierarchyNode[];
  parentId?: string;
  depth: number;
}

7. Hierarchy Type

Hierarchy nodes MUST declare their type:

type HierarchyType =
  | "document"
  | "section"
  | "subsection"
  | "paragraph"
  | "list"
  | "table"
  | "codeblock";

This type represents logical role, not rendering format.

8. Tree Structure Constraint

Hierarchy MUST form a strict tree structure.

Rules:

• Each node MAY have only one parent
• Root node MUST be unique
• Cycles are NOT allowed
• Depth MUST be deterministic

9. Relationship to Document

Hierarchy is a sub-component of Document:

Document
   │
   └── Hierarchy
          │
          └── Nodes (Tree)

When an implementation uses this conceptual model, a Document SHOULD contain one Hierarchy root.

10. Relationship to Selection

A Selection MAY reference logical node identifiers supplied by an internal Hierarchy. Exchange-format conformance does not require a serialized Hierarchy.

A Selection is always anchored to a Hierarchy Node.

This ensures:

• structural traceability
• semantic consistency
• reproducible context extraction

11. Structural vs Semantic Separation

Hierarchy defines structure only.

It does NOT define meaning.

Example:

A section node:

• defines grouping
• does NOT define semantic interpretation

Semantic meaning is handled in Chapter 240.

12. Depth Semantics

Depth represents structural nesting level.

Rules:

• root depth = 0
• children increment depth by 1
• depth MUST be consistent across traversal

Depth is used for:

• structural reasoning
• context expansion
• selection anchoring

13. Hierarchy Integrity Rules

A valid Hierarchy MUST satisfy:

• single root node
• acyclic structure
• consistent parent-child relationships
• deterministic traversal order

14. Immutability Principle

Hierarchy MUST NOT change during a Pipeline execution.

If modification is required:

• a new Hierarchy MUST be created
• existing Selection references MUST remain valid

15. Informal Example

{
  "root": {
    "id": "doc-root",
    "type": "document",
    "depth": 0,
    "children": [
      {
        "id": "sec-1",
        "type": "section",
        "title": "Introduction",
        "depth": 1,
        "children": [
          {
            "id": "p-1",
            "type": "paragraph",
            "depth": 2
          }
        ]
      }
    ]
  }
}

16. Design Notes

Hierarchy is intentionally strict to ensure:

• predictable traversal
• stable Selection mapping
• deterministic Context Object generation

Although real-world documents may behave like graphs, COS enforces a tree model in v0.2 for simplicity and consistency.

Future versions MAY extend this to graph-based relationships, cross-references, citations, footnotes, and other non-tree structural links.

17. Summary

Hierarchy defines the structural organization of a Document.

It provides the backbone for Selection anchoring and later semantic interpretation.

Within the Context Object Specification, Hierarchy is the bridge between raw document space and semantic understanding.