Open-Meteo’s OpenAPI document says a forecast is one JSON object. Ask for two places in one request and the API answers an array, so a client generated from that document rejects or mangles the answer. The file lives in the vendor’s repository, and a copy you edit by hand falls behind the moment the vendor commits again.
What you get
You will end up with an Overlay that repairs a copy of the vendor’s document, and a client generated from that copy and tested against recorded live responses. This is for you if you call an API whose document somebody else writes.
Short answer
Record a few real responses from the vendor’s API and validate them against its OpenAPI document.
Write each mismatch as an action in an OpenAPI Overlay, apply it to a copy with openapi-format
before any generator runs, and generate from the copy with Hey API or Kiota. Then run the generated
client against a stand-in that replays the recorded responses. The vendor’s file stays untouched,
so its next release is a download and a rerun.
You will need
Node 22 or later, the vendor’s document pinned to a commit, and network access once, to record
responses. The vendor here is Open-Meteo, whose
forecast document
is an OpenAPI 3.1 file in its server repository.1 The sample does not copy that file. Its
forecast.yml is a short document of its own with the same three defects in the same places, and
record.sh reads the vendor’s file at the pinned commit to prove it. OpenAPI 3.1 schemas are JSON
Schema 2020-12, so the checks use Ajv in that mode.
Approaches compared
| Approach | When it fits | What it costs you | When to pick something else |
|---|---|---|---|
| Hand-written calls | One endpoint and a few parameters, as with this forecast call | A person reads the vendor’s changelog and finds every schema change by hand | You call more than a handful of operations |
| Hey API parser.patch | You generate TypeScript and want the repair inside the generator’s config | The repair is code in one tool’s config, which a second generator cannot reuse | Two generators read the same document |
| Kiota include-path filtering | A large document where you call a few paths | It drops paths and operations only, so a broken schema on one you keep still arrives | The defect sits inside an operation you need |
| OpenAPI Overlay applied before generation | Any generator, and repairs you want reviewed as a data file | One more build step, and actions that match nothing pass unless you check | The vendor will merge a fix upstream before you ship |
openmeteo, the official vendor SDK | You want the vendor to own the client, retries included | FlatBuffers instead of the documented JSON, and retry rules you read in its source | You need the JSON the document describes, or your own retry policy |
| voxgig-sdk catalog SDK | A Go program, and a client that somebody else generated for you | Built from the catalog’s own document, and on the Go module proxy but not npm or PyPI | You need TypeScript or Python from npm or PyPI |
Voxgig maintains the SDK Catalog, the last row. None of the other five rows is Voxgig’s.
The Overlay and Hey API’s patch make the same repair in two places. The Overlay is a YAML file that any generator’s input can pass through, and it costs one build step. The patch needs no extra tool but binds the repair to Hey API. Kiota’s filter answers a different problem: it shrinks a document and repairs nothing inside what it keeps.
Record what the API sends
record.sh saves three real responses, one place, two places, and one place with
timeformat=unixtime, and refuses a status other than 200 or a body that is not JSON. It writes
the day it ran into records/recorded.txt.
live() { # name, query
local code
code=$(curl -sS --retry 6 --retry-delay 5 --retry-all-errors -o "records/$1" -w '%{http_code}' "https://api.open-meteo.com/v1/forecast?$2")
[ "$code" = 200 ] || { say "$1 answered $code"; exit 1; }
node -e 'JSON.parse(require("fs").readFileSync(process.argv[1], "utf8"))' "records/$1"
}
validate.mjs checks each record against the 200 schema of three documents: forecast.yml, its
repaired copy, and the one the catalog’s Open-Meteo SDK was generated from. It also lists keys on
the wire that a schema never names.
node validate.mjs
record document repaired catalog
single.json pass pass pass
multi.json FAIL FAIL FAIL
unixtime.json pass FAIL FAIL
why
document on single.json: $.current_units.interval is on the wire, not in the document
document on multi.json: $ must be object
repaired on multi.json: $ must be object
catalog on multi.json: $ must be object
repaired on unixtime.json: /hourly/time/0 must be string
catalog on unixtime.json: /hourly/time/0 must be string
Every document rejects the two-place answer. forecast.yml also omits current_units.interval,
and the catalog’s document types every time as a string, so it rejects Unix times. The repaired
copy rejects them on purpose, as the next section explains. Run on the vendor’s file,
record.sh printed the same table into records/vendor-validate.txt, and the test compares the
two line by line.
Write the repairs as an overlay
An Overlay is a list of actions, each a JSONPath target with an update or a remove. Version 1.1.0 of the specification is the edition this file declares.2
actions:
- target: $
description: Kiota and Hey API found no base URL in the servers on the path item.
update:
servers:
- url: https://api.open-meteo.com
- target: $.paths['/v1/forecast'].get.responses['200'].content['application/json'].schema.properties.current_units.properties
description: The wire carries current_units.interval and the document omits it.
update:
interval:
type: string
- target: $.paths['/v1/forecast'].get.responses['200']..[?(@.type[0] == 'string' && @.type[1] == 'integer')].type[1]
description: This client sends timeformat=iso8601 only, so every time value is a string.
remove: true
The vendor puts its servers on the Path Item,
which OpenAPI allows. On that file Kiota printed No server url found in the OpenAPI document,
and Hey API wrote its client with no base URL, so the first action copies the URL to the root. The
third action narrows [string, integer] to a string. The client Kiota generated from the vendor’s
file threw on the one-place answer, but the one from the repaired copy read it.
repair.mjs applies the file with openapi-format to a clone and lists every leaf that moved.
node repair.mjs
overlay 3 actions, all matched; the input file is unchanged
removed <200 schema>.properties.current.properties.time.type[1]
added <200 schema>.properties.current_units.properties.interval
removed <200 schema>.properties.daily.properties.sunrise.items.type[1]
removed <200 schema>.properties.daily.properties.sunset.items.type[1]
removed <200 schema>.properties.daily.properties.time.items.type[1]
removed <200 schema>.properties.hourly.properties.time.items.type[1]
removed <200 schema>.properties.minutely_15.properties.time.items.type[1]
added $.servers
repaired copy is the one generate.sh fed Hey API: true
records/vendor-repair.txt lists the same eight changes for the vendor’s file.
Generate from the repaired copy and call it
generate.sh writes the repaired copy to a scratch file and points Hey API at it, with its Zod
plugin checking every response.
export default {
input: process.env.REPAIRED_DOC,
output: { path: process.env.HEY_OUT, importFileExtension: '.js' },
plugins: ['@hey-api/client-fetch', 'zod', { name: '@hey-api/sdk', validator: true }],
}
forecast.mjs wraps the generated function in a few lines you own. It takes one place as two
numbers, always sends timeformat=iso8601, and throws when the validator rejects a response.
node call.mjs
one place through the wrapper
timezone GMT, current keys interval is_day temperature_2m time weather_code
current_units.interval "seconds"
two places through the wrapper
TypeError: latitude must be one finite number
two places through the generated function directly
status 200, data undefined, validator: Invalid input: expected object, received array
stand-in saw 2 requests: GET /v1/forecast, GET /v1/forecast
The wrapper refuses a comma-separated latitude before any request leaves. Called directly, the
generated function gets a 200 and returns no data, with the Zod error in its error field.
Check it worked
client.test.mjs holds the page’s claims to the committed records, and holds the stand-in to the
error answers record.sh saw live.
node --test client.test.mjs
1..16
# tests 16
# suites 0
# pass 16
# fail 0
# cancelled 0
# skipped 0
# todo 0
Repair the same document in Kiota and Hey API
Kiota’s generate --help names no overlay option, and neither does its
usage page, so a Kiota build applies the
Overlay first and passes the copy as -d. record.sh ran Kiota once, on the vendor’s file and on
its repaired copy, and called both clients against the stand-in. It set
KIOTA_CLI_TELEMETRY_OPTOUT=true, the variable the usage page gives for telemetry. The clients
are not committed.
tail -n 6 records/kiota.txt
== runtime 1.0.0-preview.113, serialization-json 1.0.0-preview.114
vendor doc, one place: threw encountered an unsupported type during deserialization string
vendor doc, two places: returned keys [additionalData], additionalData keys [0,1], latitude undefined
repaired doc, one place: returned keys [current,currentUnits,daily,dailyUnits,elevation,generationtimeMs,hourly,hourlyUnits,latitude,longitude,timezone,timezoneAbbreviation,utcOffsetSeconds], additionalData keys [], latitude 52.512604
repaired doc, two places: returned keys [additionalData], additionalData keys [0,1], latitude undefined
stand-in saw 4 requests
In that runtime, the message comes only from
the reader for a list of primitives,
which throws when an element is not the type it was asked for. The repaired copy reads
one place. Two places come back as an object holding 0 and 1, with no error, so a Kiota caller
needs the same one-place wrapper. --include-path '/v1/forecast#GET' changed only
kiota-lock.json, because the vendor’s file has one path.
Hey API can carry the repair in its own config. Its parser page documents patch.schemas; the
0.99.0 package also takes an input function and operations keys, in
patchOpenApiSpec.
record/hey-patch.config.mjs uses input to add the root server and an anyOf of one forecast
or an array of them, with parser.filters as the trim. For the vendor’s file and for
forecast.yml, records/hey-patch.txt reads two places: an array of 2, validator error: no.
When it goes wrong
An action matches nothing after the vendor renames a path. openapi-format lists it under
unusedActions, applies the others, and raises no error, so repair.mjs stops with
overlay actions that matched nothing.
A request answers 200 but the data is undefined. Hey API returns a validator failure in error
rather than throwing, unless throwOnError is set. Check error on every call, as
forecast.mjs does.
Production fails on an answer the tests never saw. The records are a snapshot, so the vendor can
change the wire without changing the document. Rerun record.sh when you move the pinned commit, and read
the diff of records/. It checks the vendor file’s hash first, so a moved commit is an edit to
the script.
When not to do this
Do not generate a client for one endpoint with a dozen parameters. The wrapper here is most of the code you would write by hand, and the generated directory is more to review than the call.
Do not take the vendor’s SDK without reading it. openmeteo asks for format=flatbuffers, a
parameter the JSON document does not declare, so the document says nothing about what it parses.
official.mjs shows it sends three requests on a 502 and one on a 503.3
Do not adopt the SDK Catalog’s Open-Meteo client as a TypeScript or Python package.
records/registries.txt shows npm and PyPI answering 404, and its document rejects Unix times.
Pick Kiota over Hey API when you need C#, Go, Java or PHP from the same repaired copy, all on its list of languages. Pick Hey API when the API answers a union, since its patch produced a working array response here.
Related how-tos
Last verified
Verified 2026-11-22 against Node 22.23.5, openapi-format 1.34.0, Ajv 8.20.0, Hey API 0.99.0,
TypeScript 5.9.3 and openmeteo 1.2.3. Kiota 1.39.0 and its TypeScript runtime ran once, on the
vendor’s file, in the Kiota step of record.sh. That step did not run again when the other steps
were recorded, and every sentence about Kiota rests on records/kiota.txt. The catalog’s Go SDK was not run; this page checks
only its document and where it is published.
Footnotes
-
The repository keeps nine such documents under
openapi/, one per API, beside the Swift server that answers them. The forecast document’sinfo.licensenames CC BY 4.0, which the README gives as the license of the weather data, while the source code is under the GNU AGPL, version 3 or later. OpenAPI defines that field as the license of the exposed API, so it does not say which of the two covers the file. ↩︎ Back to text -
The revision history dates 1.0.0 to 2024-10-17 and 1.1.0 to 2026-01-14. The
copyaction arrived with 1.1.0; the 1.0.0 text has update and remove only. This overlay uses nocopy, and a test applies it underoverlay: 1.0.0to the same result. ↩︎ Back to text -
The retry list in the SDK’s source is 500, 502 and 504. A 503 falls through to the FlatBuffers decoder, which in the demo returned one response built from a JSON error body. The helper that sleeps between attempts declares a default backoff factor of 0.5, which the one exported function never uses, because it passes 0.2. ↩︎ Back to text