markitect-main/markitect/schemas/api-documentation-schema-v1.0.md

---
description: Schema for API documentation structure and content validation
domain: api-documentation
schema-id: https://markitect.dev/schemas/api-documentation/v1.0
status: stable
version: 1.0.0
---

# API Endpoint Documentation Schema v1.0.0

## Overview

Schema for API endpoint documentation with classification and content control

## Usage

```bash
markitect validate document.md --schema v1.0
```

## Schema Definition

```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "API Endpoint Documentation Schema",
  "description": "Schema for API endpoint documentation with classification and content control",
  "x-markitect-sections": {
    "ENDPOINT": {
      "classification": "required",
      "heading_level": 2,
      "position": "after_title",
      "content_instruction": "HTTP method and endpoint path (e.g., GET /api/v1/users)",
      "min_paragraphs": 1,
      "max_paragraphs": 3,
      "error_message": "ENDPOINT section must specify the HTTP method and path"
    },
    "DESCRIPTION": {
      "classification": "required",
      "heading_level": 2,
      "content_instruction": "What this endpoint does and when to use it",
      "min_paragraphs": 2,
      "error_message": "DESCRIPTION is required to explain endpoint functionality"
    },
    "AUTHENTICATION": {
      "classification": "required",
      "heading_level": 2,
      "content_instruction": "Authentication requirements (API key, OAuth, etc.)",
      "min_paragraphs": 1,
      "error_message": "AUTHENTICATION requirements must be documented"
    },
    "REQUEST PARAMETERS": {
      "classification": "recommended",
      "heading_level": 2,
      "content_instruction": "List all request parameters with types and descriptions",
      "alternatives": [
        "PARAMETERS",
        "REQUEST",
        "INPUT"
      ],
      "warning_if_missing": "Documenting request parameters helps API consumers use the endpoint correctly"
    },
    "RESPONSE": {
      "classification": "recommended",
      "heading_level": 2,
      "content_instruction": "Response format, status codes, and example responses",
      "min_code_blocks": 1,
      "warning_if_missing": "Response documentation with examples improves API usability"
    },
    "EXAMPLES": {
      "classification": "recommended",
      "heading_level": 2,
      "content_instruction": "Complete request/response examples",
      "min_code_blocks": 2,
      "warning_if_missing": "Examples make API documentation significantly more useful"
    },
    "ERROR CODES": {
      "classification": "recommended",
      "heading_level": 2,
      "content_instruction": "Possible error responses and how to handle them",
      "alternatives": [
        "ERRORS",
        "ERROR HANDLING"
      ],
      "warning_if_missing": "Error documentation helps developers handle failures gracefully"
    },
    "RATE LIMITING": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "Rate limit information for this endpoint"
    },
    "CHANGELOG": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "Version history and changes to this endpoint"
    },
    "SEE ALSO": {
      "classification": "optional",
      "heading_level": 2,
      "content_instruction": "Related endpoints and documentation"
    },
    "IMPLEMENTATION NOTES": {
      "classification": "discouraged",
      "heading_level": 2,
      "warning_if_missing": "Implementation details should be in developer documentation, not API docs"
    },
    "INTERNAL API": {
      "classification": "improper",
      "heading_level": 2,
      "error_message": "Internal API endpoints must not be in public documentation"
    },
    "EXPERIMENTAL": {
      "classification": "improper",
      "heading_level": 2,
      "error_message": "Experimental features must not be in stable API documentation"
    }
  },
  "x-markitect-content-control": {
    "endpoint": {
      "required_patterns": [
        "\\*\\*[A-Z]+\\*\\*",
        "`/api/",
        "\\*\\*[A-Z]+\\*\\*\\s+`/[^`]+`"
      ],
      "content_quality": {
        "min_words": 5,
        "max_words": 50,
        "readability_target": "technical"
      },
      "content_instructions": [
        "Format: **METHOD** `endpoint_path`",
        "Example: **GET** `/api/v1/users/{id}`",
        "Use bold for HTTP method",
        "Use code formatting for path",
        "Include path parameters in curly braces"
      ]
    },
    "description": {
      "discouraged_patterns": [
        "TODO",
        "FIXME",
        "TBD",
        "Coming soon"
      ],
      "forbidden_patterns": [
        "password",
        "secret",
        "api[_-]?key\\s*=",
        "token\\s*="
      ],
      "content_quality": {
        "min_words": 30,
        "max_words": 500,
        "readability_target": "technical",
        "min_sentences": 2
      },
      "content_instructions": [
        "Explain what the endpoint does",
        "Describe the main use case",
        "Mention any prerequisites",
        "Note any side effects",
        "Keep concise but complete"
      ]
    },
    "request_parameters": {
      "required_patterns": [
        "\\*\\*[a-z_]+\\*\\*",
        "\\*[A-Za-z]+\\*"
      ],
      "content_instructions": [
        "Use bold for parameter names",
        "Use italic for parameter types",
        "Include: name, type, required/optional, description",
        "Use definition list format",
        "Specify default values where applicable"
      ]
    },
    "response": {
      "required_patterns": [
        "```json",
        "200",
        "\\{[^}]*\\}"
      ],
      "content_quality": {
        "min_words": 50,
        "max_words": 500,
        "readability_target": "technical"
      },
      "content_instructions": [
        "Show example JSON response",
        "Document all status codes",
        "Explain response fields",
        "Include success and error examples",
        "Use proper JSON formatting in code blocks"
      ]
    },
    "examples": {
      "required_patterns": [
        "```bash",
        "curl",
        "```json"
      ],
      "content_quality": {
        "min_words": 100,
        "max_words": 1000,
        "readability_target": "general"
      },
      "content_instructions": [
        "Provide complete curl examples",
        "Show request headers",
        "Include example responses",
        "Add explanatory comments",
        "Cover common scenarios"
      ],
      "link_validation": {
        "check_internal": true,
        "check_external": true,
        "allow_fragments": true
      }
    }
  },
  "type": "object",
  "properties": {
    "headings": {
      "type": "object",
      "properties": {
        "level_1": {
          "type": "array",
          "minItems": 1,
          "maxItems": 1
        },
        "level_2": {
          "type": "array",
          "minItems": 3,
          "maxItems": 15
        },
        "level_3": {
          "type": "array",
          "minItems": 0,
          "maxItems": 30
        }
      }
    },
    "paragraphs": {
      "type": "array",
      "minItems": 8,
      "maxItems": 200
    },
    "code_blocks": {
      "type": "array",
      "minItems": 3,
      "maxItems": 30
    },
    "emphasis": {
      "type": "array",
      "minItems": 15,
      "maxItems": 200
    }
  },
  "version": "1.0.0",
  "$id": "https://markitect.dev/schemas/api-documentation/v1.0"
}
```

## Version History

### v1.0.0
- Initial version