openapi: 3.1.0
info:
  title: makeBIMI SVG Tiny P/S Validation API
  version: 1.0.0
  description: |
    A free public REST API that validates a publicly reachable SVG file against the
    SVG Tiny Portable/Secure profile used for BIMI logo files. It evaluates XML and
    SVG structure, required Tiny P/S attributes, forbidden content, and recommended
    file-size limits. No authentication is required.
  contact:
    name: makeBIMI
    url: https://makebimi.com
  license:
    name: API terms
    url: https://makebimi.com/api-docs
externalDocs:
  description: SVG Tiny P/S validation guide
  url: https://makebimi.com/api-docs
servers:
  - url: https://makebimi.com
    description: Production
paths:
  /api/validate:
    get:
      operationId: validateSvgTinyPs
      summary: Validate a public SVG URL for BIMI readiness
      description: |
        Fetches a publicly reachable SVG over HTTPS and returns a detailed validation
        report. A syntactically reachable but non-compliant SVG returns HTTP 200 with
        `valid: false`; request-shape errors return HTTP 400.
      parameters:
        - name: url
          in: query
          required: true
          description: Absolute HTTPS URL of the public SVG file to validate.
          schema:
            type: string
            format: uri
            pattern: '^https://'
          example: https://yourdomain.com/.well-known/bimi/logo.svg
      responses:
        '200':
          description: Validation report returned, including reports for files that are not compliant.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationReport'
              examples:
                nonCompliantSvg:
                  summary: Reachable SVG that is not Tiny P/S compliant
                  value:
                    valid: false
                    url: https://yourdomain.com/logo.svg
                    file_size_bytes: 8432
                    file_size_kb: '8.2'
                    errors:
                      - Missing version="1.2" on root <svg> element
                      - Missing baseProfile="tiny-ps" on root <svg> element
                    warnings: []
                    checks:
                      fetchable: true
                      is_xml: true
                      svg_root: true
                      namespace_correct: true
                      version_1_2: false
                      base_profile_tiny_ps: false
                      has_viewbox: true
                      viewbox_square: true
                      has_title: true
                      no_scripts: true
                      no_external_refs: true
                      no_image_elements: true
                      no_embedded_bitmaps: true
                      no_animations: true
                      no_foreign_object: true
                      file_size_ok: true
                    meta:
                      viewbox: 0 0 100 100
                      dimensions: 100x100
                    spec: https://bimigroup.org/resources/RFC_SVG_PS.txt
                    tool: makeBIMI.com — Free BIMI SVG Tiny P/S Validator
        '400':
          description: The required `url` parameter is missing or cannot be parsed as a supported URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestError'
              examples:
                missingUrl:
                  value:
                    error: 'Missing required parameter: url'
                    example: 'GET /api/validate?url=https://yourdomain.com/bimi-logo.svg'
                    spec: https://bimigroup.org/resources/RFC_SVG_PS.txt
                    tool: makeBIMI.com
components:
  schemas:
    ValidationReport:
      type: object
      required:
        - valid
        - url
        - checks
        - errors
        - warnings
        - meta
        - spec
        - tool
      properties:
        valid:
          type: boolean
          description: True only when all required validation checks pass.
        url:
          type: string
          format: uri
          description: The SVG URL supplied to the validator.
        file_size_bytes:
          type: integer
          minimum: 0
          description: Size of the fetched SVG in bytes when the file was retrieved.
        file_size_kb:
          type: string
          description: Human-readable file size in kilobytes when the file was retrieved.
        errors:
          type: array
          items:
            type: string
          description: Blocking validation failures.
        warnings:
          type: array
          items:
            type: string
          description: Non-blocking validation warnings.
        checks:
          $ref: '#/components/schemas/ValidationChecks'
        meta:
          type: object
          additionalProperties: true
          description: Extracted SVG metadata, such as viewBox and dimensions, when available.
        spec:
          type: string
          format: uri
          description: Reference SVG Tiny P/S specification.
        tool:
          type: string
          description: Tool attribution string.
    ValidationChecks:
      type: object
      required:
        - fetchable
        - is_xml
        - svg_root
        - namespace_correct
        - version_1_2
        - base_profile_tiny_ps
        - has_viewbox
        - viewbox_square
        - has_title
        - no_scripts
        - no_external_refs
        - no_image_elements
        - no_embedded_bitmaps
        - no_animations
        - no_foreign_object
        - file_size_ok
      properties:
        fetchable:
          type: boolean
          description: The supplied URL is publicly reachable.
        is_xml:
          type: boolean
          description: The response parses as XML.
        svg_root:
          type: boolean
          description: The root element is svg.
        namespace_correct:
          type: boolean
          description: The SVG namespace is http://www.w3.org/2000/svg.
        version_1_2:
          type: boolean
          description: The root SVG element declares version 1.2.
        base_profile_tiny_ps:
          type: boolean
          description: The root SVG element declares baseProfile tiny-ps.
        has_viewbox:
          type: boolean
          description: A viewBox is present.
        viewbox_square:
          type: boolean
          description: The viewBox has a 1:1 aspect ratio.
        has_title:
          type: boolean
          description: A title element is present.
        no_scripts:
          type: boolean
          description: No script elements are present.
        no_external_refs:
          type: boolean
          description: No external href or xlink:href references are present.
        no_image_elements:
          type: boolean
          description: No image elements are present.
        no_embedded_bitmaps:
          type: boolean
          description: No data-image bitmap content is present.
        no_animations:
          type: boolean
          description: No SVG animation elements are present.
        no_foreign_object:
          type: boolean
          description: No foreignObject elements are present.
        file_size_ok:
          type: boolean
          description: The SVG is no larger than the validator’s recommended 32 KB maximum.
    RequestError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
        example:
          type: string
        spec:
          type: string
          format: uri
        tool:
          type: string