seed-xc-openapi.yaml

openapi: 3.1.0
info:
  title: SEED XC
  description: SEED XC is an API for compiling XSLT stylesheets and packages
  version: 1.0.0

tags:
  - name: transformer
    description: A Transformer API offers transformations user input
  - name: compiler
    description: A Compiler API offers operations for compiling user input

paths:
  /transformations:
    get:
      tags:
        - transformer
      operationId: transformationsGet
      summary: Get IDs of all transformations available on this service
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transformationIDs'
        "5XX":
          description: Unexpected error.

  /transformations/{transformation}/info:
    get:
      tags:
        - transformer
      operationId: transformationsTransformationInfoGet
      summary: Get info for transformation with the ID
      parameters:
        - name: transformation
          in: path
          description: The ID of the transformation
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/transformationInfo'
        "400":
          $ref: '#/components/responses/BadRequest'
        "404":
          $ref: '#/components/responses/NotFound'
        "500":
          $ref: '#/components/responses/InternalError'

  /transformations/{transformation}/parameters:
    get:
      tags:
        - transformer
      operationId: transformationsTransformationParametersGet
      summary: Get a compiler-generated description of the global parameters of this transformation.
      parameters:
        - name: transformation
          in: path
          description: The ID of the transformation
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/xsltParameterDetails'
        "400":
          $ref: '#/components/responses/BadRequest'
        "404":
          $ref: '#/components/responses/NotFound'
        "500":
          $ref: '#/components/responses/InternalError'

  /transform/{transformation}/{url}:
    post:
      tags:
        - transformer
      operationId: transformTransformationUrlPost
      summary: Transform the XML document from the specified URL. Runtime parameters are provided in the request body.
      parameters:
        - name: transformation
          in: path
          description: The ID of the transformation
          required: true
          schema:
            type: string
        - name: url
          in: path
          description: The URL of the source document to be transformed
          required: true
          schema:
            type: string
      requestBody:
        description: The input to the transformation
        required: false
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                runtimeParameters:
                  $ref: '#/components/schemas/runtimeParameters'
                config:
                  $ref: '#/components/schemas/config'
            encoding:
              runtimeParameters:
                contentType: application/json
              config:
                contentType: application/json
      responses:
        "200":
          $ref: '#/components/responses/TransformationOK'
        "400":
          $ref: '#/components/responses/BadRequest'
        "404":
          $ref: '#/components/responses/NotFound'
        "500":
          $ref: '#/components/responses/InternalError'
    get:
      tags:
        - transformer
      operationId: transformTransformationUrlGet
      summary: Transform the XML document from the specified URL. No runtime parameters can be provided.
      parameters:
        - name: transformation
          in: path
          description: The ID of the transformation
          required: true
          schema:
            type: string
        - name: url
          in: path
          description: The URL of the source document to be transformed
          required: true
          schema:
            type: string
      responses:
        "200":
          $ref: '#/components/responses/TransformationOK'
        "400":
          $ref: '#/components/responses/BadRequest'
        "404":
          $ref: '#/components/responses/NotFound'
        "500":
          $ref: '#/components/responses/InternalError'

  /transform/{transformation}:
    post:
      tags:
        - transformer
      operationId: transformTransformationPost
      summary: Transform the XML document posted in the request body. Its URL and the runtime parameters are also provided in the request body.
      parameters:
        - name: transformation
          in: path
          description: The ID of the transformation
          required: true
          schema:
            type: string
      requestBody:
        description: The input to the transformation
        required: false
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                source:
                  description: The source document
                  type: string
                  format: binary
                sourceUrl:
                  description: URL of the source document
                  type: string
                runtimeParameters:
                  $ref: '#/components/schemas/runtimeParameters'
                config:
                  $ref: '#/components/schemas/config'
              required:
                - source
            encoding:
              source:
                contentType: application/xml, text/xml, application/atom+xml, application/svg+xml, application/xhtml+xml
      responses:
        "200":
          $ref: '#/components/responses/TransformationOK'
        "400":
          $ref: '#/components/responses/BadRequest'
        "404":
          $ref: '#/components/responses/NotFound'
        "500":
          $ref: '#/components/responses/InternalError'


  /xslc/zip/{stylesheet}:
    post:
      tags:
        - compiler
      operationId: compileZip
      summary: Compiles the stylesheet contained in the posted zip and stores it under the given transformation ID.
      parameters:
        - name: stylesheet
          in: path
          description: The filename of the XSLT stylesheet or package to be compiled
          required: true
          schema:
            type: string
      requestBody:
        description: A zip file containing the XSLT stylesheets, packages, imports, and other static resources required for the compilation
        required: true
        content:
          application/zip:
            schema:
              type: string
              format: local-zip
      responses:
        "200":
          $ref: '#/components/responses/CompilationSuccessful'
        "400":
          $ref: '#/components/responses/StylesheetNotFound'
        "401":
          description: Unauthorized
        "5XX":
          $ref: '#/components/responses/CompilationError'

  /bind/{transformationResource}/{transformationId}:
    get:
      tags:
        - compiler
      operationId: bind
      summary: Binds the transformation resource to the transformation ID. A server without transformation capability SHOULD respond with 501.
      parameters:
        - name: transformationResource
          in: path
          description: The resource identifier (significant part of the transformation resource link)
          required: true
          schema:
            type: string
        - name: transformationId
          in: path
          description: The ID to which the transformation with the resource identifier is to be bound to
          required: true
          schema:
            type: string
      responses:
        "200":
          description: OK
        "400":
          description: Bad Request - Transformation ID syntax error
        "401":
          description: Unauthorized
        "404":
          description: Not Found - No such transformation resource
        "501":
          description: Not Implemented
        "5XX":
          description: Unexpected Error

components:
  responses:
    CompilationSuccessful:
      description: OK
      content:
        application/json:
          schema:
            type: object
      headers:
        transformation-resource-link:
          description: A link to the resource which runs the transformation.
          schema:
            type: string
            format: uri
        transformation-resource:
          description: The significant part of the transformation resource link that identifies the transformation
          schema:
            type: string
    StylesheetNotFound:
      description: Bad Request
      content:
        text/plain:
          schema:
            type: string
    CompilationError:
      description: Compilation Error
      content:
        text/plain:
          schema:
            type: string
    TransformationOK:
      description: OK
      content:
        "*/*":
          schema:
            type: string
            format: binary
    NotFound:
      description: The specified resource was not found
    BadRequest:
      description: Bad request.
      content:
        text/plain:
          schema:
            type: string
            format: binary
    InternalError:
      description: An error occurred while performing the transformation.
      content:
        text/plain:
          schema:
            type: string
            format: binary
  schemas:
    parser:
      description: How to parse the main input.
      type: object
      properties:
        class:
          description: Java name of the parser.
          type: string
        xinclude:
          description: Whether or to parse the source xinclude-aware.
          type: boolean
    serializer:
      description: How to serialize the output.
      type: object
      properties:
        class:
          description: Java name of the serializer.
          type: string
        method:
          description: Serialization method, e.g. `xml`, `text`, `json`.
          type: string
        indent:
          description: Whether or not the output is to be indented.
          type: boolean
    config:
      description: Configuration for the transformation request.
      type: object
      properties:
        parser:
          $ref: '#/components/schemas/parser'
        serializer:
          $ref: '#/components/schemas/serializer'
    runtimeParameters:
      description: How the transformation is to be called, with a set of global parameters and optionally the initial callable (template or function) and the parameters for it.
      type: object
      properties:
        globalParameters:
          description: Global parameters passed to the transformation (stylesheet parameters).
          type: object
          additionalProperties:
            $ref: '#/components/schemas/parameterValue'
        initialCall:
          description: The resource to call initially for the transformation.
          type: object
          additionalProperties:
            type: object
            properties:
              name:
                description: QName of the initial resource to call.
                type: string
              type:
                description: The type of the initially called resource, e.g. a template or a function.
                type: string
                enum:
                  - function
                  - template
              parameters:
                description: Parameters to be passed to the initially called resource.
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/parameterValue'
              tunnelParameters:
                description: QNames of the parameters that are tunnel parameters
                type: array
                items:
                  type: string
            required:
              - name
              - type
    source:
      description: URL of the XML source document to transform
      type: string
    transformationIDs:
      type: array
      items:
        type: string
    transformationId:
      description: ID of the transformation
      type: string
    parameterValue:
      description: A parameter value
      type: string
    typedParameter:
      description: A parameter value
      type: object
      required:
        - name
        - value
      properties:
        name:
          type: string
          description: The parameter name.
        value:
          type: string
          description: The parameter value.
        type:
          type: string
          description: The local name of the parameter type. Write 'integer' instead of 'xs:integer'!
    context:
      description: Options of the JSON-LD context
      type: object
      required:
        - location
      properties:
        location:
          type: string
          format: uri
          description: The URI of the initial active context
    transformationInfo:
      description: Information about the transformation resource and its runtime parameters
      type: object
      properties:
        ident:
          description: Identifier of the transformation.
          type: string
        class:
          description: The Java class of the transformation. This is evaluated by the service to create the transformation.
          type: string
        description:
          description: A human readable description of the transformation.
          type: string
        requiresSource:
          description: Whether or not the transformation requires a source document.
          type: boolean
        location:
          description: URL where the transformation resource is located.
          type: string
        mediaType:
          description: Mime-type of the transformed document.
          type: string
        compileTimeParameters:
          description: Static parameters passed at compile time.
          type: array
          items:
            $ref: '#/components/schemas/typedParameter'
        libraries:
          description: Library packages included by the transformation resource (by xsl:use-package). They must be provided in compilation order!
          type: array
          items:
            type: object
            properties:
              location:
                description: URL where the package is located.
                type: string
              asName:
                description: A package name used instead of the one in the source code.
                type: string
              asVersion:
                description: A package version used instead of the one in the source code.
                type: string
            required:
              - location
        parameterDescriptors:
          description: Descriptors of global parameters of the transformation.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/parameterDescriptor'
        initialCallables:
          description: Initial templates or functions with description
          type: object
          additionalProperties:
            type: object
            properties:
              type:
                description: The type of callable
                type: string
                enum:
                  - template
                  - function
              description:
                description: Human readable description of what the transformation does on starting when this is called.
                type: string
              parameters:
                description: Descriptors of parameters.
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/parameterDescriptor'
        parser:
            $ref: '#/components/schemas/parser'
        serializer:
            $ref: '#/components/schemas/serializer'
        context:
          $ref: '#/components/schemas/context'
      required:
        - class
        - description
        - location
        - requiresSource
    parameterDescriptor:
      description: A description of the transformation parameter.
      type: object
      properties:
        description:
          description: A human readable description of the parameter.
          type: string
        type:
          description: The data type of parameter values. Uses xs:*.
          type: string
        default:
          description: Default value of this parameter.
          type: string
        required:
          description: Whether or not the parameter is required.
          type: boolean
        static:
          description: Whether this is a static parameter, i.e. a compile time parameter.
          type: boolean
      required:
        - required
        - static
    transformationMap:
      description: A mapping of transformation IDs to transformation information. This is used to configure the service.
      type: object
      additionalProperties:
        $ref: '#/components/schemas/transformationInfo'
    xsltParameterDetails:
      description: "A description of parameters produced by the compiler. See [Saxon API](https://www.saxonica.com/documentation10/index.html#!javadoc/net.sf.saxon.s9api/XsltExecutable/ParameterDetails@getDeclaredItemType)"
      type: object
      additionalProperties:
        type: object
        properties:
          occurrenceIndicator:
            description: The declared cardinality of the parameter
            type: string
          itemType:
            description: The declared type of the parameter
            type: string
          underlyingDeclaredType:
            description: The underlying declared type
            type: string
          isRequired:
            description: Whether the parameter is required (mandatory) or optional
            type: boolean
    error:
      description: The error message.
      type: string
      format: binary