Skip to main content

Machine-Readable Data Schemas

This reference documentation describes the formats and schemas of the compiled assets generated by the m docs export commands. These files are designed for consumption by Large Language Models (LLMs) and agentic code pipelines (e.g., Dify, LangChain, or custom RAG environments).

1. AST Type Metadata (core.jsonl)​

  • Export Command: m docs export core
  • Format: JSON Lines (.jsonl)
  • Purpose: Supplies the LLM with exact interface definitions, signatures, and docstrings of all core framework classes, protocols, and decorators.

Schema Structure​

Each line in core.jsonl represents either a class or a standalone function.

{
  "id": "core-libs-framework-m-core-src-framework_m_core-interfaces-sms_gateway-SMSGatewayProtocol",
  "type": "class",
  "name": "SMSGatewayProtocol",
  "docstring": "Protocol interface for SMS provider integrations.",
  "module": "framework_m_core.interfaces.sms_gateway",
  "file_path": "libs/framework-m-core/src/framework_m_core/interfaces/sms_gateway.py",
  "methods": [
    {
      "name": "send_sms",
      "signature": "async def send_sms(to: str, message: str, **kwargs: Any) -> None",
      "docstring": "Send an SMS message to a destination phone number.",
      "is_async": true
    }
  ]
}

2. Flattened OpenAPI Endpoints (openapi.jsonl)​

  • Export Command: m docs export openapi --flat
  • Format: JSON Lines (.jsonl)
  • Purpose: Deconstructs the monolithic OpenAPI spec into discrete endpoint-verb blocks, optimizing context retrieval for agent tool calling.

Schema Structure​

Each line is a self-contained API endpoint definition with resolved schemas (circular references dereferenced).

{
  "method": "POST",
  "path": "/api/v1/sms/send",
  "summary": "Send SMS Notification",
  "description": "Queues and dispatches an SMS via the configured gateway.",
  "operationId": "send_sms_notification",
  "parameters": [],
  "requestBody": {
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "properties": {
            "to": { "type": "string", "format": "phone" },
            "message": { "type": "string" }
          },
          "required": ["to", "message"]
        }
      }
    }
  },
  "responses": {
    "202": { "description": "SMS successfully queued" }
  },
  "tags": ["SMS"]
}

3. DocType Schema Definitions (doctypes.jsonl)​

  • Export Command: m docs export doctypes --flat --output ./docs/machine/doctypes.jsonl
  • Format: JSON Lines (.jsonl)
  • Purpose: Supplies representations of custom database models, field types, validation rules, hooks, and ACL definitions.

Schema Structure​

{
  "name": "Customer",
  "module": "crm",
  "docstring": "Represents a business customer account.",
  "file_path": "libs/crm/src/crm/doctypes/customer.py",
  "fields": [
    {
      "name": "customer_name",
      "fieldtype": "Data",
      "label": "Customer Name",
      "reqd": true
    }
  ],
  "meta": {
    "permissions": [
      { "role": "Sales User", "read": true, "write": true }
    ]
  }
}

4. Full Text RAG Corpus (corpus.jsonl)​

  • Export Command: m docs export corpus
  • Format: JSON Lines (.jsonl)
  • Purpose: General knowledge base containing all system guides, tutorials, ADRs, RFCs, and the golden component fixtures.

Schema Structure​

{
  "id": "doc-how-to-defining-doctypes",
  "type": "doc",
  "title": "How-To: Defining DocTypes",
  "content": "# Defining DocTypes\\n\\nDocTypes represent database tables...",
  "metadata": {
    "path": "docs/how-to/defining-doctypes.md"
  }
}

5. UI Primitives & Component Props (ui.jsonl)​

  • Export Command: m docs export ui --package-dir <dir>
  • Format: JSON Lines (.jsonl)
  • Purpose: Supplies the LLM with exact React/TypeScript component names, prop types, requirement flags, and descriptions.

Schema Structure​

Each line represents a single React Component prop interface:

{
  "name": "DatePicker",
  "package": "@framework-m/ui",
  "description": "Standard date selection input wrapped with custom theme styles.",
  "props": [
    {
      "name": "value",
      "type": "Date | null",
      "required": false,
      "description": "Currently selected date value."
    },
    {
      "name": "onChange",
      "type": "(date: Date) => void",
      "required": true,
      "description": "Callback function triggered on date selection."
    }
  ]
}