Skip to main content
Validate a definition against the schema and manifest. For a listener definition it validates the stored listener body instead.

POST /revisions/:id/data/query (Command: check_definition)

Request Body

Response

A failed validation is still HTTP 200. The verdict is carried in the response body’s status field, not in the HTTP status code. Clients must read status — treating 200 as “the definition is valid” accepts every invalid definition. An HTTP error here means the request failed (malformed body, inaccessible definition), not that validation found problems. status is failure only when an event has type error. Warnings and informational events leave the status at success, so a definition can validate successfully and still return events worth showing to an author. events is never empty. When validation finds nothing to report, the platform appends a single info event confirming the flow is ready, so a client can render the result uniformly without special-casing an empty array. Each event has this shape:

Example

A structurally complete workflow:
A workflow with no starting point — note the 200:
A listener definition is checked against its body rules and the limits, not the workflow manifest. A valid body answers success with one info event, “Verification completed. The listener is ready to act”. An invalid body answers failure with one error event whose message is the refusal’s error code and message, such as invalid_listener: batch.max_events: must be an integer of at least 1.

Notes

  • Validation is not enforced on write. Upload Definition performs no structural validation of workflow documents, so an invalid definition stores successfully. This command is where structural problems surface, which is why it must be called explicitly before relying on a definition being executable.
  • A listener body is checked, but the check does not resolve its workflow reference; Upload Definition does.
  • An unknown or inaccessible definition_id returns 403 forbidden, not 404 — an id that does not exist and one belonging to another revision are deliberately indistinguishable. An empty definition_id returns 400 invalid_request_body.