Request a waiver for one finding, with a reason of at least 20 characters (REQ-072).
const url = 'https://example.com/api/v1/docs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/waivers';const options = { method: 'POST', headers: {'Content-Type': 'application/json'}, body: '{"finding_id":"2489E9AD-2EE2-8E00-8EC9-32D5F69181C0","reason":"example","trace":{"status":"out_of_scope","target":"example"},"standalone":true,"upstream_change":true,"send_back":true,"not_needed":true}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://example.com/api/v1/docs/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/waivers \ --header 'Content-Type: application/json' \ --data '{ "finding_id": "2489E9AD-2EE2-8E00-8EC9-32D5F69181C0", "reason": "example", "trace": { "status": "out_of_scope", "target": "example" }, "standalone": true, "upstream_change": true, "send_back": true, "not_needed": true }'Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters”The ID of one spec doc.
Request Bodyrequired
Section titled “Request Bodyrequired”object
The answer to a coverage gap that says the ID is intentionally absent from this doc. It is an Acknowledgement, and it follows the profile’s waiver policy.
object
For covered_by, the slug of the doc that covers the ID.
Mark the doc standalone: the answer to a links.has-upstream finding. It is an Acknowledgement, and its approval writes standalone to the doc’s sidecar.
Answer a coherence.contradiction finding with “The linked doc must change”: an upstream request. Its approval writes the request to the doc’s sidecar under upstream_changes. The conflict then waits on the linked doc, and the review of the linked doc reports it as coherence.downstream-request.
Answer a coherence.downstream-request finding with “The downstream doc must change”: a send-back. Its approval ends the upstream request in the sidecar of the downstream doc, and the conflict blocks there again with this reason.
Answer a finding with “Not needed”: the author says the fork does not matter, with a reason. It needs no approval. Speccy writes it to the sidecar at once, bound to the one fork of the finding, and it ends when the section changes.
Responses
Section titled “ Responses ”The waiver.
object
Withdrawn is an approved Acknowledgement that a person took out of the sidecar.
The waiver policy (§9.1).
The approvals the policy needs.
Whether the caller can approve or reject it now.
Why the waiver is rejected. Only a rejected waiver has one.
The byte range of the waiver’s section in the current main doc. Absent when the section is gone.
object
An Acknowledgement of one upstream trace ID. On approval it goes in the sidecar under trace.
object
One conflict between a doc and a linked doc, as a coherence.contradiction finding names it. A waiver of that check binds to it, and excuses no other conflict in the section. On a coherence.downstream-request finding, it is the conflict as the downstream doc names it.
object
The slug of the linked doc.
The text of this doc that conflicts.
The text of the linked doc that it conflicts with.
What a verification waiver excuses. It never goes in the sidecar.
object
The code repo, or the folder, as the verification run names it.
The verification run the request came from. Empty for a request that named no run.
True for a standalone Acknowledgement. On approval it goes in the sidecar under standalone.
True for an upstream request, the answer “The linked doc must change”. On approval it goes in the sidecar under upstream_changes.
True for a send-back, the answer “The downstream doc must change” to a coherence.downstream-request finding.
True for the answer “Not needed” to one finding. The author gives it, and it needs no approval.
For a send-back, or a waiver of a coherence.downstream-request finding: the downstream doc. The approval writes to its sidecar, because Speccy writes nothing into the linked doc’s sidecar.
object
The bundle that holds the spec doc.
Who withdrew the Acknowledgement. Only a withdrawn one has it.
Why an ended waiver ended: an edit changed its section, a full review passed its whole-doc check, or the profile changed what the check asks. An upstream request ends when the linked doc sends it back, or when an edit removes a quote of its conflict.
True for a waiver of a whole-doc check. An edit does not end it. It ends when a full review passes the check, or when the profile changes what the check asks.
Example
{ "status": "requested", "trace": { "status": "out_of_scope" }, "ended_because": "section_changed"}default
Section titled “default”An error.
RFC 9457 problem details with a stable code.
object
A stable machine-readable error code.
Examplegenerated
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "code": "example"}