Situation

An operation of the OpenAPI server (OpenApiServer configuration) can declare a JSON schema for its request body. The schema appears in the exported OpenAPI specification, but the server does not check the body against it when a request is processed: unknown properties, missing required properties and wrongly typed values all reach the implementation unchanged.

So every implementation has to repeat the schema as hand-written checks if it wants to answer an invalid request with 400 Bad Request instead of failing later or silently ignoring the input. In the TopLogic release notes application (TopLogic/tl-releasenotes, CMS and release API), this was the reason to implement the operations in Java instead of TL-Script.

Proposal

Validate the request body against its declared schema before calling the implementation:

• required properties
• types and formats
• enums
• additionalProperties: false

An invalid body is answered with 400 and a message naming the offending property; the implementation is not called.

Lösung

• Jeder Request-Parameter einer OpenAPI-Server-Operation, der ein JSON-Schema deklariert (Request-Body, Query-, Header-, Cookie- und Pfad-Parameter sowie Teile eines Multipart-Bodys im Format OBJECT), wird vor dem Aufruf der Implementierung gegen dieses Schema geprüft. Die Prüfung ist nicht abschaltbar; eine Operation, deren Eingabe nicht geprüft werden soll, deklariert kein Schema (ein leeres Schema schema="" gilt als kein Schema).
• Geprüft wird mit der vollen Semantik eines OpenAPI-3.0-Schemas (u.a. type, format, required, enum, nullable, additionalProperties, items, allOf/`oneOf`/`anyOf`, $ref auf die globalen Schemas des Servers unter #/components/schemas/<Name>, auch zwischen globalen Schemas).
• Ein ungültiger Wert wird mit 400 Bad Request beantwortet; die Meldung nennt den Parameter und jede Verletzung mit ihrer Stelle im Wert und dem Grund, z.B. Value of parameter 'body' does not match its schema: $.release: required property 'name' not found (höchstens 10 Verletzungen). Die Implementierung wird nicht aufgerufen; ein gültiger Wert erreicht sie unverändert.
• Ein als Body gesendetes JSON-null wird gegen das Schema geprüft (gültig nur mit nullable: true). Ein mehrfach angegebener Parameter (multiple) wird Wert für Wert geprüft. Ein fehlender bzw. leerer Wert wird nicht geprüft, für ihn gilt weiterhin nur required.
• Das Schema wird einmal beim Start des Servers übersetzt und pro Request nur angewendet. Ein Schema, das sich nicht übersetzen lässt (ungültiges JSON, kein JSON-Objekt, unbekannte Referenz, ungültiges globales Schema), verhindert den Start des Servers mit einer Fehlermeldung, die Pfad, Methode und Parameter nennt.
• Die Demo-Anwendung (tl-demo) enthält die Operation POST /api/echo mit dem globalen Schema Release als Beispiel.
• Technisch: Validierung mit der Bibliothek com.networknt:json-schema-validator (OpenAPI-3.0-Dialekt), die damit Laufzeitabhängigkeit von tl-service-openapi-server wird (zieht Jackson 3 tools.jackson und com.ethlo.time:itu nach). Externe `$ref`s (URLs) werden nicht geladen.

Migration

Operationen des OpenAPI-Servers, deren deklariertes Schema nicht zu den tatsächlich gesendeten Werten passt (z.B. unvollständige properties zusammen mit additionalProperties: false, fehlerhafte required-Listen oder falsche Typen), beantworten solche Requests jetzt mit 400. Ein Schema, das sich nicht übersetzen lässt, verhindert jetzt den Start des OpenAPI-Servers. Das Schema in der Service-Konfiguration des OpenAPI-Servers an die tatsächlichen Werte anpassen bzw. korrigieren, oder – wenn keine Prüfung gewünscht ist – das Schema am Parameter entfernen.