TriadicFrameworks
अवलोकन

RTT Absolute module.json Identity Specification

Version 1.0 — Canon‑Locked Protocol#

1. Purpose#

This specification defines the absolute identity protocol for RTT module.json files.

Its goals:

  • Guarantee global resolvability of module metadata
  • Enable cross‑substrate agentic behavior (GitHub, Docsbook.io, mirrors, etc.)
  • Prevent drift caused by renderer‑relative paths
  • Lock in a canonical identity surface for all RTT modules

This spec is normative for all RTT‑aligned modules.

2. Identity Object#

Each RTT module exposes a single identity object:

  • File name: module.json
  • Location: inside the module’s directory (e.g. /docs/ai/, /docs/Structural_Detection/)
  • Access: via a canonical absolute URL to the raw file

Example identity URL:

https://raw.githubusercontent.com/<user>/<repo>/main/docs/My_Module/module.json

This URL is the canonical identity of the module.

3. Absolute URL Requirement#

3.1 Normative Rule#

All RTT module.json references used for agentic behavior MUST be:

  • absolute URLs
  • pointing to the raw content
  • stable across renderers and hosts

Form:

https://raw.githubusercontent.com/<user>/<repo>/main/<path>/module.json

3.2 Rationale#

Absolute URLs:

  • decouple metadata from any specific renderer
  • ensure AI agents can always dereference the module
  • prevent path resolution errors in foreign substrates
  • make the module a portable service descriptor

Relative paths (e.g. ./module.json) MUST NOT be used for agentic metadata resolution.

Modules expose their identity via a link element in their primary document (e.g. README.md, index.html):

<!-- RTT Agentic Module Identity -->
<link rel="rtt-module"
      href="https://raw.githubusercontent.com/<user>/<repo>/main/<path>/module.json">

Normative requirements:

  • rel="rtt-module" — fixed, reserved value
  • href — MUST be the canonical absolute URL to module.json
  • Only one primary identity link per module document SHOULD be present

This is the standard discovery mechanism for RTT‑aware tools.

5. Canonical URL Shape#

The canonical identity URL MUST conform to:

https://raw.githubusercontent.com/<user>/<repo>/<branch>/<path>/module.json

Recommended defaults:

  • <branch>: main
  • <path>: path from repo root to module directory

Example:

https://raw.githubusercontent.com/umaywant2/TriadicFrameworks/main/docs/ai/ai_module.json

If a repository uses a different default branch, that branch name MUST be reflected in the URL.

6. Identity Invariants#

For a module.json to be considered identity‑stable, the following invariants MUST hold:

  1. Single Canonical URL per module

    • A module may have mirrors, but one URL is designated canonical.

  2. Content Stability

    • Changes to module.json SHOULD be versioned via the version field.
    • Breaking changes MUST increment the version appropriately.

  3. Location Stability

    • The path to module.json SHOULD NOT be moved casually.
    • If moved, all rel="rtt-module" links MUST be updated.

  4. Renderer Independence

    • No renderer‑specific query parameters or host‑dependent paths are allowed in the canonical URL.

7. Relative vs Absolute Path Policy#

To preserve cross‑substrate behavior:

  • Absolute paths

    • ONLY for module.json and other RTT metadata endpoints
    • Used in href attributes for rel="rtt-module"

  • Relative paths

    • For all internal content links (markdown pages, examples, diagrams, etc.)
    • Keeps documentation portable across hosts and themes

This separation is normative:

  • Metadata → absolute
  • Content → relative

8. Minimal Identity Payload (Inside module.json)#

The identity file MUST at least contain:

{
  "module": "Module Name",
  "version": "1.0",
  "description": "Short description of the module.",
  "roles": ["profile"],
  "operators": ["substrate", "flow"],
  "files": {
    "README.md": "profile"
  }
}

Required fields:

  • module — canonical module name
  • version — semantic version string
  • description — concise purpose
  • roles — RTT file‑role grammar
  • operators — RTT operator grammar
  • files — file‑to‑role mapping

The identity protocol cares primarily that:

  • the file exists
  • the absolute URL resolves
  • the JSON is valid
  • the required fields are present

9. Cross‑Substrate Expectations#

Any RTT‑aware tool (AI agent, renderer, validator) MAY:

  1. Discover module.json via rel="rtt-module"

  2. Fetch the absolute URL

  3. Parse the JSON

  4. Use the identity to:

    • understand module purpose
    • map files to roles
    • reason about operators
    • integrate the module into larger systems

Tools MUST NOT assume:

  • a specific host (GitHub, Docsbook.io, etc.)
  • a specific visual theme
  • a specific documentation engine

Only the absolute URL + JSON schema are normative.

10. Compliance Checklist#

A module is compliant with the RTT Absolute module.json Identity spec if:

  • module.json exists in the module directory

  • A canonical absolute raw URL can be constructed

  • The primary document includes:

    <link rel="rtt-module"
      href="https://raw.githubusercontent.com/<user>/<repo>/main/<path>/module.json">

  • The URL resolves successfully

  • The JSON is valid and includes required fields

  • Internal content links remain relative

11. Versioning#

This is RTT Absolute module.json Identity Specification v1.0.

Future versions MAY:

  • add optional fields
  • define additional discovery mechanisms
  • extend identity semantics

They MUST NOT:

  • break existing absolute URL behavior
  • invalidate compliant v1.0 modules

Updated

द्वारा संचालित Docsbook
Absolute Module Identity — TriadicFrameworks