The Powerduck Blog
Product updates, engineering notes, and guides for designing, debugging, testing, mocking, and serving MCP tools from one OpenAPI spec.
Browse the guidesA JSON object is sometimes a fixed record, sometimes a Map<string, T> of arbitrary keys, and sometimes genuinely free-form. Use additionalProperties for dictionaries, properties plus additionalProperties:false for strict records, and an empty object for anything-goes payloads. Get it wrong and...
Read articleCategories contain children, comments have replies, and org charts nest forever. Model these with a self-referencing $ref and generated clients produce recursive types that compile; inline the shape and codegen either loops or flattens it. Here is how to model trees, nullable children, oneOf...
Read articleAn enum is a promise the server only accepts those values; a const is one fixed value; an open string accepts anything. Teams blur the three and ship a breaking change every time they add an option. Here is the decision table, extensible enums, and what codegen and AI callers do with each shape.
Read articleOptional, nullable, and omitted are three different facts most specs collapse into one. A field can be required yet nullable, optional but never null, or an array empty rather than absent. Here is the 3.1 decision table, and why one non-null sample never proves non-nullability.
Read articlePATCH is not PUT with fewer fields; the media type defines its semantics. JSON Merge Patch treats null as delete and replaces arrays; JSON Patch sends atomic operations and pairs with optimistic concurrency. Here is when to use each and the OpenAPI for all three.
Read articleA webhook is an inbound URL you register once; an OpenAPI callback is an outbound call whose URL arrives inside the request. Same shape, opposite direction. Here are the callbacks syntax, runtime expressions, a worked 202 example, and how to mock the round trip.
Read articleWhich JSON Schema keywords become types, which are enforced at runtime, and which are only annotations? Here is how format, pattern, ranges, required, and nullability flow into codegen, validators, mocks, and AI-generated test data.
Read articleA payment can be a card, a bank transfer, or a wallet. Model that as a loose anyOf and generated clients fall back to any; model it as oneOf with a discriminator and you get a tagged union a compiler can narrow. Here is when each keyword applies and how to keep codegen, mocks, and AI callers honest.
Read articleA 429 with no Retry-After just makes clients guess, hammer harder, or give up. A usable rate-limit contract states the quota window, the remaining count, and exactly when to retry. Here is how to model 429, Retry-After, and the RateLimit headers in OpenAPI and verify the backoff with a mock.
Read articleTwo clients PUT the same resource and the last write silently wins. The HTTP fix is conditional requests with ETag, If-Match, and a 412 that tells the client to re-fetch and retry. Here is the exact state table and the OpenAPI that makes codegen and AI agents handle conflicts correctly.
Read articleMost OpenAPI upload specs are subtly wrong: the file is typed as a string, the multipart boundary is undocumented, or an array of files generates the wrong client. Here is how to model each of the three real upload shapes so codegen, mocks, and scanners all agree.
Read articleThe same example payload is usually hand-copied into docs, a mock server, a Postman collection, and test fixtures, and then they drift. OpenAPI examples can drive all four from one document, but only if they are realistic, schema-valid, and cover success, empty, and error states.
Read article