Yandex Cloud
Documentation
PresentationContact UsTry it for free
© 2026 Direct Cursus Technology L.L.C.
Yandex API Gateway
  • Getting started
    • Resource relationships
    • Networking
      • Overview
      • Greedy parameters
      • Generic HTTP method
      • Authorization using a Cloud Functions function
      • Authorization using a JWT
      • WebSocket protocol support
      • Data validation
      • CORS
      • Specification parameterization
      • Canary release
      • Request rate limit
      • Response code replacement
      • Transformation of response and request bodies
    • Quotas and limits
  • Access management
  • Tools
  • Pricing policy
  • Terraform reference
  • Monitoring metrics
  • Audit Trails events
  • Public materials
  • Release notes
  • FAQ

In this article:

  • Supported parameters
  • Extension specification
  • Use cases
  1. Concepts
  2. Specification extensions
  3. Transformation of response and request bodies

x-yc-schema-mapping extension

Written by
Yandex Cloud
Updated at September 21, 2026
View in Markdown
  • Supported parameters
  • Extension specification
  • Use cases

The x-yc-schema-mapping extension allows you to transform the JSON body of a request to an integration or response from it.

The extension is intended for the Schema object of the OpenAPI specification.

Supported parametersSupported parameters

The table below lists the parameters specific to API Gateway API gateways. You can find the description of other parameters in the OpenAPI 3.0 specification.

Parameter

Type

Description

type

string

Transformation type. The possible value is static, i.e., the body is described by a static resource.

template

map[string]TemplateObject

Full body description as a dictionary in <field_name>: "<field_value>" format.

string

String containing a valid jq template for extracting the required data from the body, e.g., "${.numbers.firstNumber}".

Extension specificationExtension specification

Extension specification depends on the template value type.

Specification example:

Object (dictionary)
jq_template
x-yc-schema-mapping:
  type:static
  template:
    property1: "value1"
    property2: "${.baseProperty1.baseProperty2}"

Example of response body transformation where a user gets a two-field response if the Cloud Functions function returns code 200 and the Content-Type: application/json header:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Petstore API

paths:
  /pets:
    get:
      responses:
        '200':
          description: Pet
          content:
            application/json:
              schema:
                type: object
                x-yc-schema-mapping:
                  type: static
                  template:
                    Name: "Dog"
                    Breed: "${.nestedProperty1.nestedProperty2}"
      x-yc-apigateway-integration:
        type: cloud_functions
        function_id: b095c95icn**********
x-yc-schema-mapping:
  type: static
  template: "${.numbers.firstNumber}"

Example of response body transformation where a user gets a key value from the incoming JSON object (12), obtained after applying the jq template set under template:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Test API

paths:
  /test:
    get:
      summary: Number
      operationId: Number
      responses:
        200:
          description: Another example
          content:
            application/json:
              schema:
                type: object
                x-yc-schema-mapping:
                  type: static
                  template: "${.numbers.firstNumber}"
          x-yc-status-mapping: 201
        x-yc-mapping-index:
          200: application/json
      x-yc-apigateway-integration:
        http_code: 200
        http_headers:
          Content-Type: application/json
          Content-Length: '10'
        type: dummy
        content:
          application/json: '{"numbers":{"firstNumber": 12, "secondNumber": 32}}'

Use casesUse cases

  • Using Yandex API Gateway to set up speech synthesis in Yandex SpeechKit

Was the article helpful?

Previous
Response code replacement
Next
Overview
© 2026 Direct Cursus Technology L.L.C.