openapi: 3.1.0
info:
  title: "JSON Tree + PlatPhorm Schema Registry API"
  description: "Public-safe JSON parse, format, minify, validation, schema registry, JSON-LD, v0 registry, and MCP discovery API for json.platphormnews.com."
  version: 1.0.0
  contact:
    name: PlatPhormNews
    url: https://platphormnews.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
servers:
  - url: https://json.platphormnews.com
    description: Production
  - url: http://localhost:3000
    description: "Local development"
tags:
  - name: "JSON Tools"
    description: "Public-safe JSON utility operations."
  - name: "Schema Registry"
    description: "Public PlatPhorm schema pack and schema validation."
  - name: Discovery
    description: "Health, OpenAPI, llms, RSS, sitemap, trust, and well-known files."
  - name: MCP
    description: "JSON-RPC 2.0 MCP endpoint and metadata."
  - name: "V0 Registry"
    description: "Public universe, realm, and item views backed by schema registry state."
paths:
  /api/health:
    get:
      tags:
        - Discovery
      summary: "Health summary"
      responses:
        200:
          description: "Health response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - data
                  - meta
                properties:
                  ok:
                    const: true
                  data:
                    type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
  /api/v1/health:
    get:
      tags:
        - Discovery
      summary: "Health summary"
      responses:
        200:
          description: "Health response"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - data
                  - meta
                properties:
                  ok:
                    const: true
                  data:
                    type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
  /api/docs:
    get:
      tags:
        - Discovery
      summary: "OpenAPI JSON"
      responses:
        200:
          description: "OpenAPI 3.1 JSON document"
  /openapi.json:
    get:
      tags:
        - Discovery
      summary: "OpenAPI JSON"
      responses:
        200:
          description: "OpenAPI 3.1 JSON document"
  /openapi.yaml:
    get:
      tags:
        - Discovery
      summary: "OpenAPI YAML"
      responses:
        200:
          description: "OpenAPI 3.1 YAML document"
  /api/v1/parse:
    post:
      tags:
        - "JSON Tools"
      summary: "Parse JSON into tree nodes and stats."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - json
              properties:
                json:
                  type: string
                indent:
                  type: integer
                  minimum: 0
                  maximum: 8
      responses:
        200:
          description: "JSON tool result"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - data
                  - meta
                properties:
                  ok:
                    const: true
                  data:
                    type: object
                    properties:
                      valid:
                        type: boolean
                      tree:
                        type: object
                      stats:
                        $ref: "#/components/schemas/JsonStats"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - error
                  - meta
                properties:
                  ok:
                    const: false
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        429:
          description: "Rate limited"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - error
                  - meta
                properties:
                  ok:
                    const: false
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
  /api/v1/format:
    post:
      tags:
        - "JSON Tools"
      summary: "Format valid JSON."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - json
              properties:
                json:
                  type: string
                indent:
                  type: integer
                  minimum: 0
                  maximum: 8
      responses:
        200:
          description: "JSON tool result"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - data
                  - meta
                properties:
                  ok:
                    const: true
                  data:
                    type: object
                    properties:
                      formatted:
                        type: string
                      length:
                        type: integer
                      originalLength:
                        type: integer
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - error
                  - meta
                properties:
                  ok:
                    const: false
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        429:
          description: "Rate limited"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - error
                  - meta
                properties:
                  ok:
                    const: false
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
  /api/v1/minify:
    post:
      tags:
        - "JSON Tools"
      summary: "Minify valid JSON."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - json
              properties:
                json:
                  type: string
                indent:
                  type: integer
                  minimum: 0
                  maximum: 8
      responses:
        200:
          description: "JSON tool result"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - data
                  - meta
                properties:
                  ok:
                    const: true
                  data:
                    type: object
                    properties:
                      minified:
                        type: string
                      length:
                        type: integer
                      originalLength:
                        type: integer
                      saved:
                        type: integer
                      savedPercent:
                        type: integer
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - error
                  - meta
                properties:
                  ok:
                    const: false
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        429:
          description: "Rate limited"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - error
                  - meta
                properties:
                  ok:
                    const: false
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
  /api/v1/validate:
    post:
      tags:
        - "JSON Tools"
      summary: "Validate JSON syntax and return stats when valid."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - json
              properties:
                json:
                  type: string
                indent:
                  type: integer
                  minimum: 0
                  maximum: 8
      responses:
        200:
          description: "JSON tool result"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - data
                  - meta
                properties:
                  ok:
                    const: true
                  data:
                    type: object
                    properties:
                      valid:
                        type: boolean
                      stats:
                        $ref: "#/components/schemas/JsonStats"
                      error:
                        type: string
                      line:
                        type: integer
                      column:
                        type: integer
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - error
                  - meta
                properties:
                  ok:
                    const: false
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        429:
          description: "Rate limited"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - error
                  - meta
                properties:
                  ok:
                    const: false
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
  /api/v1/stats:
    post:
      tags:
        - "JSON Tools"
      summary: "Calculate JSON statistics."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - json
              properties:
                json:
                  type: string
                indent:
                  type: integer
                  minimum: 0
                  maximum: 8
      responses:
        200:
          description: "JSON tool result"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - data
                  - meta
                properties:
                  ok:
                    const: true
                  data:
                    $ref: "#/components/schemas/JsonStats"
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - error
                  - meta
                properties:
                  ok:
                    const: false
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        429:
          description: "Rate limited"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - error
                  - meta
                properties:
                  ok:
                    const: false
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
  /api/v1/schema/validate:
    post:
      tags:
        - "Schema Registry"
      summary: "Validate JSON against a public schema"
      description: "Public-safe schema validation against bundled public schema registry files."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - json
                - schemaSlug
              properties:
                json:
                  type: string
                schemaSlug:
                  type: string
                  enum:
                    - platphorm-universal-schema-pack
                    - core
                    - realm
                    - item
                    - observability
                    - agent
      responses:
        200:
          description: "Validation result"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - data
                  - meta
                properties:
                  ok:
                    const: true
                  data:
                    type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - error
                  - meta
                properties:
                  ok:
                    const: false
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
  /api/v1/schemas:
    get:
      tags:
        - "Schema Registry"
      summary: "List public schemas"
      responses:
        200:
          description: "Schema records"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - data
                  - meta
                properties:
                  ok:
                    const: true
                  data:
                    type: array
                    items:
                      type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
  /api/v1/schemas/{slug}:
    get:
      tags:
        - "Schema Registry"
      summary: "Get public schema"
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Schema record"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - data
                  - meta
                properties:
                  ok:
                    const: true
                  data:
                    type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        404:
          description: "Schema not found"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - error
                  - meta
                properties:
                  ok:
                    const: false
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
  /api/v1/schema-pack:
    get:
      tags:
        - "Schema Registry"
      summary: "Get public schema pack metadata"
      responses:
        200:
          description: "Schema pack"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - data
                  - meta
                properties:
                  ok:
                    const: true
                  data:
                    type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
  /api/v1/jsonld:
    get:
      tags:
        - "Schema Registry"
      summary: "Get JSON-LD artifacts"
      responses:
        200:
          description: "JSON-LD artifacts"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - data
                  - meta
                properties:
                  ok:
                    const: true
                  data:
                    type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
  /api/v1/jsonld/validate:
    post:
      tags:
        - "JSON Tools"
      summary: "Validate JSON-LD structure locally."
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - json
              properties:
                json:
                  type: string
                indent:
                  type: integer
                  minimum: 0
                  maximum: 8
      responses:
        200:
          description: "JSON tool result"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - data
                  - meta
                properties:
                  ok:
                    const: true
                  data:
                    type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        400:
          description: "Invalid request"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - error
                  - meta
                properties:
                  ok:
                    const: false
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
        429:
          description: "Rate limited"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - error
                  - meta
                properties:
                  ok:
                    const: false
                  error:
                    type: object
                    required:
                      - code
                      - message
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      details:
                        type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
  /api/mcp:
    get:
      tags:
        - MCP
      summary: "Read MCP metadata"
      responses:
        200:
          description: "MCP metadata"
    post:
      tags:
        - MCP
      summary: "Execute JSON-RPC 2.0 MCP request"
      description: "Public-safe read-only introspection and JSON/schema utility tools. Future protected tool calls use PLATPHORM_API_KEY when enforcement is enabled."
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                jsonrpc:
                  const: 2.0
                id:
{}
                method:
                  type: string
                params:
                  type: object
      responses:
        200:
          description: "JSON-RPC 2.0 response"
  /v0/universes:
    get:
      tags:
        - "V0 Registry"
      summary: "List public schema registry universes."
      responses:
        200:
          description: "V0 registry result"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - data
                  - meta
                properties:
                  ok:
                    const: true
                  data:
                    type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
  /v0/realms:
    get:
      tags:
        - "V0 Registry"
      summary: "List public schema registry realms."
      responses:
        200:
          description: "V0 registry result"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - data
                  - meta
                properties:
                  ok:
                    const: true
                  data:
                    type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
  /v0/realm/{id}/items:
    get:
      tags:
        - "V0 Registry"
      summary: "List realm items"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        200:
          description: "Realm schema items"
          content:
            application/json:
              schema:
                type: object
                required:
                  - ok
                  - data
                  - meta
                properties:
                  ok:
                    const: true
                  data:
                    type: object
                  meta:
                    $ref: "#/components/schemas/ResponseMeta"
components:
  securitySchemes:
    PlatPhormApiKey:
      type: apiKey
      in: header
      name: X-PlatPhorm-API-Key
      description: "Future protected-action auth. Public-safe Phase 1 flows do not require this key by default."
    PlatPhormBearer:
      type: http
      scheme: bearer
      description: "Future protected-action auth using Authorization: Bearer $PLATPHORM_API_KEY."
  schemas:
    ResponseMeta:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
        requestId:
          type: string
        version:
          type: string
        traceId:
          type: string
        spanId:
          type: string
        traceUrl:
          type: string
          format: uri
    JsonStats:
      type: object
      properties:
        totalNodes:
          type: integer
        maxDepth:
          type: integer
        types:
          type: object
          additionalProperties:
            type: integer
x-platphorm:
  service: json
  product: "JSON Tree + PlatPhorm Schema Registry"
  authPolicy: "Public-safe by default. Future protected actions use PLATPHORM_API_KEY only."
  routeCount: 15
