============================================================ SCHEMA SPECIFICATION: Technical Documentation ============================================================ Name: Technical Documentation Slug: technical-documentation Status: registered Default: No Pages using this schema: 1 Created: 2026-04-10T21:32:02.167165+00:00 Updated: 2026-04-10T22:21:05.626008+00:00 --- DESCRIPTION --- Schema for a technical documentation page --- REQUIREMENTS --- - Public route shape: /docs/:slug - Route ownership: isolated - Canonical frontend URL: https://service-cms.com - Temporary frontend URLs allowed: Yes - Preferred page discovery: schema-scoped-api - Published pages API: https://service-cms.jay-rathjen55.workers.dev/api/schemas/technical-documentation/pages --- DO NOT CHANGE --- - Keep the implementation isolated to the configured route space. Do not replace unrelated dynamic routes. - Confirm the final production frontend URL before registration whenever possible. --- DATA SOURCE --- Use the schema-scoped published pages API instead of inferring schema membership from raw table reads whenever possible. GET https://service-cms.jay-rathjen55.workers.dev/api/schemas/technical-documentation/pages Returns only these fields for published pages: - id - slug - name - status - content - domain_url - updated_at --- SCHEMA DEFINITION --- { "faq": { "type": "array", "items": { "type": "object", "properties": { "answer": { "type": "ContentBlock[]", "description": "FAQ answer.", "meta_description": "Rich answer content. Can include paragraphs, lists, and short clarifications." }, "question": { "type": "string", "description": "FAQ question.", "placeholder": "Does this support self-hosting?", "meta_description": "Question phrased the way a technical buyer or developer would ask it." } } }, "description": "Frequently asked questions.", "meta_description": "Reader-focused FAQs that address adoption, integration, pricing model, hosting model, or technical behavior." }, "seo": { "type": "object", "properties": { "og_image": { "type": "media", "description": "Social preview image.", "meta_description": "Optional Open Graph image for link sharing." }, "meta_title": { "type": "string", "description": "SEO title.", "placeholder": "Specy Docs: API, Integrations, and Deployment", "meta_description": "Search-engine-friendly title. Can differ slightly from the main page title." }, "meta_description": { "type": "string", "description": "SEO description.", "placeholder": "Technical documentation for integrating and deploying Specy.", "meta_description": "Short summary used for search results and social previews." } }, "description": "Search and sharing metadata.", "meta_description": "Optional metadata for search engines and social previews." }, "hero": { "type": "object", "required": true, "properties": { "title": { "type": "string", "description": "Main documentation title.", "placeholder": "e.g. Specy API Documentation", "meta_description": "Primary H1 for the documentation page. Should clearly identify the product or subsystem." }, "badges": { "type": "array", "items": { "type": "string", "placeholder": "e.g. Open Source", "meta_description": "One short badge label." }, "description": "Optional highlight badges.", "meta_description": "Short metadata chips such as Open Source, Edge Native, Self-Hosted, MCP Compatible." }, "status": { "enum": [ "alpha", "beta", "stable", "deprecated" ], "type": "string", "description": "Lifecycle state of the docs or product.", "meta_description": "Lifecycle marker indicating maturity of the documented feature set." }, "eyebrow": { "type": "string", "description": "Small label above the title.", "placeholder": "e.g. Developer Docs", "meta_description": "Short contextual label shown above the main title. Useful for product line, documentation area, or audience." }, "summary": { "type": "ContentBlock[]", "description": "Short overview of the product and documentation scope.", "meta_description": "Introductory content explaining what the product does, who this documentation is for, and what readers can accomplish here." }, "version": { "type": "string", "description": "Displayed product or docs version.", "placeholder": "e.g. v1.4.0", "meta_description": "Version string for the documented release or API version." } }, "description": "Top section of the documentation page.", "meta_description": "Primary documentation header. Should clearly identify the product, its purpose, and the current documentation version. This section anchors the page and gives readers immediate orientation." }, "guides": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Guide title.", "placeholder": "e.g. Deploy to Cloudflare Workers", "meta_description": "Name of the tutorial or implementation guide." }, "content": { "type": "ContentBlock[]", "description": "Guide explanation.", "meta_description": "Main narrative and instructional content of the guide." }, "audience": { "enum": [ "developer", "admin", "platform-engineer", "integrator" ], "type": "string", "description": "Intended reader.", "meta_description": "Primary audience for this guide." } } }, "description": "Task-based implementation guides.", "meta_description": "Use this for practical workflows such as authentication setup, deployment, observability, or plugin development." }, "sidebar": { "type": "object", "properties": { "resource_links": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "description": "Destination URL.", "placeholder": "https://github.com/example/repo", "meta_description": "Absolute URL for the resource." }, "label": { "type": "string", "description": "Link label.", "placeholder": "GitHub Repository", "meta_description": "Visible text for the link." } } }, "description": "Helpful external or internal links.", "meta_description": "Links to GitHub, API reference, changelog, support, roadmap, or SDK docs." }, "table_of_contents_title": { "type": "string", "description": "TOC heading.", "placeholder": "On this page", "meta_description": "Sidebar label for the table of contents." } }, "description": "Sidebar metadata and navigation helpers.", "meta_description": "Optional metadata used by the frontend to render secondary documentation context such as links, doc anchors, or support channels." }, "quickstart": { "type": "object", "required": true, "properties": { "intro": { "type": "ContentBlock[]", "description": "Brief setup explanation.", "meta_description": "Short explanation of what will be installed or configured and what the expected outcome is." }, "steps": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "CodeBlock[]", "items": { "type": "object", "properties": { "code": { "type": "string", "required": true, "description": "Actual code snippet.", "placeholder": "npm install your-package", "meta_description": "Exact source code or shell command. Preserve formatting and indentation." }, "label": { "type": "string", "description": "Visible snippet label.", "placeholder": "e.g. npm", "meta_description": "Short label naming the snippet variant." }, "language": { "enum": [ "bash", "typescript", "javascript", "json", "yaml", "python" ], "type": "string", "required": true, "meta_description": "Syntax highlighting token for the code snippet." }, "frameworks": { "type": "array", "items": { "enum": [ "node", "react", "nextjs", "sveltekit", "hono", "docker" ], "type": "string" }, "description": "Optional framework tags.", "meta_description": "Framework or runtime tags used to filter or group the snippet." } } }, "description": "Code samples for this step.", "meta_description": "One or more code snippets demonstrating the exact commands or code required for this step." }, "title": { "type": "string", "description": "Step title.", "placeholder": "e.g. Install the CLI", "meta_description": "Short imperative instruction naming the step." }, "description": { "type": "ContentBlock[]", "description": "Step explanation.", "meta_description": "Explain what the step does and what the developer should expect." } } }, "description": "Ordered quickstart steps.", "meta_description": "Step-by-step onboarding list. Each item should represent one meaningful action in the getting-started flow." }, "title": { "type": "string", "description": "Section heading.", "placeholder": "e.g. Quickstart", "meta_description": "Heading for the quickstart block." } }, "description": "Fast onboarding section for first-time users.", "meta_description": "A high-priority section that gets a developer from zero to first success quickly. Should focus on the minimum viable setup path." }, "architecture": { "type": "object", "properties": { "title": { "type": "string", "description": "Section title.", "placeholder": "e.g. Architecture", "meta_description": "Heading for the architecture section." }, "overview": { "type": "ContentBlock[]", "description": "Narrative architecture explanation.", "meta_description": "Textual explanation of system boundaries, responsibilities, and major design decisions." }, "components": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Component name.", "placeholder": "e.g. API Gateway", "meta_description": "Name of the subsystem or architectural component." }, "responsibility": { "type": "string", "description": "What this component does.", "placeholder": "Routes authenticated requests to internal services", "meta_description": "Concise statement of the component's purpose." } } }, "description": "Major system components.", "meta_description": "List of subsystems and their responsibilities." } }, "description": "Technical architecture overview.", "meta_description": "Explains the system layout, runtime components, and how data flows through the product." }, "installation": { "type": "object", "properties": { "title": { "type": "string", "description": "Section heading.", "placeholder": "e.g. Installation", "meta_description": "Heading for the installation section." }, "prerequisites": { "type": "array", "items": { "type": "string", "placeholder": "e.g. Node.js 20+", "meta_description": "One prerequisite item." }, "description": "Required tools or accounts.", "meta_description": "List of dependencies a developer must have before starting installation." }, "environment_variables": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Environment variable name.", "placeholder": "e.g. API_URL", "meta_description": "Exact environment variable identifier." }, "example": { "type": "string", "description": "Example value.", "placeholder": "https://api.example.com", "meta_description": "Safe example value for documentation." }, "required": { "type": "boolean", "description": "Whether this variable is mandatory.", "meta_description": "True when setup cannot function without this environment variable." }, "description": { "type": "string", "description": "Meaning of the variable.", "placeholder": "Base URL for the backend API", "meta_description": "Short explanation of the variable's purpose." } } }, "description": "Environment variable reference.", "meta_description": "Structured list of required or optional environment variables for local and production setup." } }, "description": "Installation and environment setup details.", "meta_description": "More complete setup documentation covering package installation, required services, and environment variables." }, "api_reference": { "type": "object", "properties": { "title": { "type": "string", "description": "Section heading.", "placeholder": "e.g. API Reference", "meta_description": "Heading for the API reference block." }, "endpoints": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "description": "Endpoint or command path.", "placeholder": "/api/projects/:id", "meta_description": "Exact route path or command identifier." }, "method": { "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE", "RPC", "CLI" ], "type": "string", "description": "HTTP verb or operation type.", "meta_description": "Operation method or command category." }, "summary": { "type": "string", "description": "Short description.", "placeholder": "Returns one project by ID", "meta_description": "Concise explanation of the operation." } } }, "description": "Documented endpoint summary.", "meta_description": "Compact list of important endpoints or operations exposed by the product." } }, "description": "Compact API or interface summary.", "meta_description": "Reference-style section for key endpoints, methods, or operations. Intended as a high-signal summary rather than a full OpenAPI replacement." }, "troubleshooting": { "type": "array", "items": { "type": "object", "properties": { "cause": { "type": "ContentBlock[]", "description": "Root cause explanation.", "meta_description": "Explain why the issue happens, including likely misconfiguration or integration mismatch." }, "problem": { "type": "string", "description": "Observed issue.", "placeholder": "Revalidation returns 401", "meta_description": "Short statement of the symptom or failure case." }, "resolution": { "type": "ContentBlock[]", "description": "Fix instructions.", "meta_description": "Steps or checks the user should perform to resolve the issue." } } }, "description": "Common issues and resolutions.", "meta_description": "Support-oriented section for fast diagnosis of frequent problems. Good for operational and onboarding friction points." }, "feature_sections": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Feature title.", "placeholder": "e.g. Agent Integration", "meta_description": "Name of the documented capability." }, "summary": { "type": "ContentBlock[]", "description": "Overview of the feature.", "meta_description": "High-level explanation of what the feature does and why it matters." }, "highlights": { "type": "array", "items": { "type": "string", "placeholder": "e.g. Supports MCP and REST side by side", "meta_description": "One short feature highlight." }, "description": "Key bullets or benefits.", "meta_description": "Important implementation points, guarantees, or selling points." }, "example_code": { "type": "CodeBlock[]", "items": { "type": "object", "properties": { "code": { "type": "string", "required": true, "description": "Code snippet.", "placeholder": "const client = createClient(...)", "meta_description": "Exact example code." }, "label": { "type": "string", "description": "Snippet title.", "placeholder": "e.g. Basic usage", "meta_description": "Display label for this code example." }, "pattern": { "enum": [ "basic", "advanced", "server-action", "api-route", "cli", "config" ], "type": "string", "description": "Implementation style.", "meta_description": "Optional label for the implementation pattern." }, "language": { "enum": [ "typescript", "javascript", "bash", "json", "yaml", "python" ], "type": "string", "required": true, "meta_description": "Syntax highlighting token." } } }, "description": "Example snippets for this feature.", "meta_description": "Reference implementation or usage snippets showing how to use the capability in practice." } } }, "required": true, "description": "Main capability sections of the product.", "meta_description": "Structured documentation blocks for core capabilities. Good for conceptual explanation plus implementation examples." } } --- CONTENT BLOCK TYPES --- ContentBlock is a union type. Each block has { id: string, type: string } plus type-specific fields: text: { content: string } heading: { content: string, level: "heading1" | "heading2" | "heading3" | "heading4" | "heading5" | "heading6" } image: { src: string, alt: string, caption?: string, width?: number, height?: number } quote: { text: string, author?: string, source?: string } list: { style: "ordered" | "unordered", items: string[] } video: { src: string, provider: "youtube" | "vimeo" | "other", caption?: string } Block IDs follow the pattern: ${prefix}-${timestamp}-${random} --- REVALIDATION --- - The CMS derives the full route path from slug_structure and the stored page slug. - Your revalidation endpoint should accept Authorization: Bearer . - The CMS sends ?path= and ?slug=. - Use the full path as the primary invalidation target. --- FRONTEND INFO --- Frontend URL: https://service-cms.com Slug Structure: /docs/:slug Revalidation Endpoint: /api/revalidate ============================================================ --- CODE BLOCK FIELD TYPE --- Schemas may also use the custom field type "CodeBlock[]" for structured code examples. Each item is typically stored as: { id: string, language: string, code: string, label?: string, pattern?: string, frameworks?: string[] } The optional items.properties definition can be used to configure placeholders, help text, required flags, and enum options for language, pattern, frameworks, or extra metadata fields. If frameworks.items.enum is provided, the Page Builder renders a multi-select checkbox group for frameworks. ============================================================