openapi: "3.1.0"
info:
  title: "XML Tree / PlatPhorm XML Registry"
  version: "1.0.0"
  description: "Canonical XML viewer, formatter, validator, tree explorer, XPath tester, XML registry, feed inspector, sitemap inspector, and XML conversion utility for the PlatPhormNews web mesh."
  contact:
    name: "PlatPhormNews"
    url: "https://platphormnews.com"
    email: "api@platphormnews.com"
servers:
  -
    url: "https://xml.platphormnews.com"
    description: "Production"
tags:
  -
    name: "XML Tools"
    description: "Public-safe XML parser, formatter, validator, inspector, and converter endpoints."
  -
    name: "XML Schema Registry"
    description: "Read-only public schema registry plus future protected mutation scaffold."
  -
    name: "MCP"
    description: "JSON-RPC 2.0 endpoint with 21 XML-focused tools."
  -
    name: "Platform"
    description: "Health, discovery, trust, and route standard endpoints."
paths:
  /api/health:
    get:
      tags:
        - "Platform"
      summary: "Public health summary"
      responses:
        200:
          description: "Health payload"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
  /api/v1/health:
    get:
      tags:
        - "Platform"
      summary: "Versioned public health summary"
      responses:
        200:
          description: "Health payload"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
  /api/mcp:
    get:
      tags:
        - "MCP"
      summary: "Public read-only MCP metadata and usage"
      responses:
        200:
          description: "MCP metadata"
    post:
      tags:
        - "MCP"
      summary: "JSON-RPC 2.0 MCP endpoint"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: "object"
      responses:
        200:
          description: "JSON-RPC 2.0 response"
  /api/v1/schemas:
    get:
      tags:
        - "XML Schema Registry"
      summary: "List public built-in XML schemas"
      responses:
        200:
          description: "Schema list"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
  /api/v1/schemas/{slug}:
    get:
      tags:
        - "XML Schema Registry"
      summary: "Read one public built-in XML schema"
      parameters:
        -
          name: "slug"
          in: "path"
          required: true
          schema:
            type: "string"
      responses:
        200:
          description: "Schema record"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
        404:
          description: "Schema not found"
  /api/v1/parse:
    post:
      tags:
        - "XML Tools"
      summary: "Parse XML into a tree and validation result."
      description: "Parse XML into a tree and validation result. Public-safe in Phase 1; future protected variants use PLATPHORM_API_KEY only."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XmlRequest"
      responses:
        200:
          description: "Operation result"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
  /api/v1/format:
    post:
      tags:
        - "XML Tools"
      summary: "Pretty-format XML with bounded indentation."
      description: "Pretty-format XML with bounded indentation. Public-safe in Phase 1; future protected variants use PLATPHORM_API_KEY only."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XmlRequest"
      responses:
        200:
          description: "Operation result"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
  /api/v1/minify:
    post:
      tags:
        - "XML Tools"
      summary: "Minify XML after real XML validation."
      description: "Minify XML after real XML validation. Public-safe in Phase 1; future protected variants use PLATPHORM_API_KEY only."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XmlRequest"
      responses:
        200:
          description: "Operation result"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
  /api/v1/validate:
    post:
      tags:
        - "XML Tools"
      summary: "Validate XML syntax and security constraints."
      description: "Validate XML syntax and security constraints. Public-safe in Phase 1; future protected variants use PLATPHORM_API_KEY only."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XmlRequest"
      responses:
        200:
          description: "Operation result"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
  /api/v1/stats:
    post:
      tags:
        - "XML Tools"
      summary: "Return XML node, line, namespace, and depth stats."
      description: "Return XML node, line, namespace, and depth stats. Public-safe in Phase 1; future protected variants use PLATPHORM_API_KEY only."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XmlRequest"
      responses:
        200:
          description: "Operation result"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
  /api/v1/xpath:
    post:
      tags:
        - "XML Tools"
      summary: "Run the Phase 1 bounded XPath subset."
      description: "Run the Phase 1 bounded XPath subset. Public-safe in Phase 1; future protected variants use PLATPHORM_API_KEY only."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XPathRequest"
      responses:
        200:
          description: "Operation result"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
  /api/v1/xsd/validate:
    post:
      tags:
        - "XML Tools"
      summary: "Run safe XML plus basic XSD root contract validation; reports degraded semantic coverage."
      description: "Run safe XML plus basic XSD root contract validation; reports degraded semantic coverage. Public-safe in Phase 1; future protected variants use PLATPHORM_API_KEY only."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XmlAndSchemaRequest"
      responses:
        200:
          description: "Operation result"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
  /api/v1/rss/inspect:
    post:
      tags:
        - "XML Tools"
      summary: "Inspect RSS 2.0 feeds."
      description: "Inspect RSS 2.0 feeds. Public-safe in Phase 1; future protected variants use PLATPHORM_API_KEY only."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XmlRequest"
      responses:
        200:
          description: "Operation result"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
  /api/v1/atom/inspect:
    post:
      tags:
        - "XML Tools"
      summary: "Inspect Atom feeds."
      description: "Inspect Atom feeds. Public-safe in Phase 1; future protected variants use PLATPHORM_API_KEY only."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XmlRequest"
      responses:
        200:
          description: "Operation result"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
  /api/v1/sitemap/inspect:
    post:
      tags:
        - "XML Tools"
      summary: "Inspect sitemap and sitemap index XML."
      description: "Inspect sitemap and sitemap index XML. Public-safe in Phase 1; future protected variants use PLATPHORM_API_KEY only."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XmlRequest"
      responses:
        200:
          description: "Operation result"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
  /api/v1/convert/json:
    post:
      tags:
        - "XML Tools"
      summary: "Convert XML to a structured JSON representation."
      description: "Convert XML to a structured JSON representation. Public-safe in Phase 1; future protected variants use PLATPHORM_API_KEY only."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XmlRequest"
      responses:
        200:
          description: "Operation result"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
  /api/v1/convert/yaml:
    post:
      tags:
        - "XML Tools"
      summary: "Convert XML to deterministic YAML."
      description: "Convert XML to deterministic YAML. Public-safe in Phase 1; future protected variants use PLATPHORM_API_KEY only."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/XmlRequest"
      responses:
        200:
          description: "Operation result"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RestEnvelope"
components:
  securitySchemes:
    PlatPhormApiKey:
      type: "apiKey"
      in: "header"
      name: "X-PlatPhorm-API-Key"
      description: "Future protected actions accept PLATPHORM_API_KEY. Public-safe Phase 1 XML tools do not require a key."
    PlatPhormBearer:
      type: "http"
      scheme: "bearer"
      description: "Future protected actions accept Authorization: Bearer $PLATPHORM_API_KEY."
  schemas:
    XmlRequest:
      type: "object"
      required:
        - "xml"
      properties:
        xml:
          type: "string"
          description: "XML content. DOCTYPE and external entities are blocked."
        indent:
          type: "integer"
          minimum: 1
          maximum: 8
          default: 2
    XPathRequest:
      type: "object"
      required:
        - "xml"
        - "xpath"
      properties:
        xml:
          type: "string"
        xpath:
          type: "string"
          examples:
            - "/rss/channel/item"
            - "//item/@id"
            - "//@href"
    XmlAndSchemaRequest:
      type: "object"
      required:
        - "xml"
        - "schema"
      properties:
        xml:
          type: "string"
        schema:
          type: "string"
          description: "XSD content for Phase 1 basic root-contract validation."
    RestEnvelope:
      oneOf:
        -
          type: "object"
          required:
            - "ok"
            - "data"
          properties:
            ok:
              const: true
            data:
              type: "object"
        -
          type: "object"
          required:
            - "ok"
            - "error"
          properties:
            ok:
              const: false
            error:
              type: "object"
