{
  "openapi": "3.1.2",
  "info": {
    "title": "Illustrative publishing service",
    "version": "1.0",
    "description": "An example API, not an implementation claim. Authenticated reads are limited to reviews offered to the acting account. The service binds every action-relevant publication term to revision and atomically enforces expected_revision, permission, recipient relationship, expiry and state on decision. A 409 or 410 commits no effect for that request. Accepted publication preserves its immutable content and destination snapshot. The read includes content_artifact.text: its exact UTF-8 bytes, including the final newline, are the publication artifact covered by the content digest. Clients verify those bytes and apply content policy or present them for review."
  },
  "servers": [
    {
      "url": "https://service.example"
    }
  ],
  "security": [
    {
      "accountToken": []
    }
  ],
  "paths": {
    "/reviews": {
      "get": {
        "operationId": "readReview",
        "parameters": [
          {
            "in": "query",
            "name": "reference",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uri"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The offered review for this authenticated account. Fields and example are generated from the canonical type and description.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "review_id",
                    "interaction",
                    "service",
                    "addressed_to",
                    "subject",
                    "contract",
                    "reference",
                    "revision",
                    "expires_at",
                    "allowed_actions",
                    "publication",
                    "state",
                    "content_artifact"
                  ],
                  "properties": {
                    "review_id": {
                      "type": "string",
                      "minLength": 1
                    },
                    "interaction": {
                      "type": "string",
                      "minLength": 1,
                      "format": "uri",
                      "maxLength": 2048
                    },
                    "service": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "id"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "minLength": 1,
                          "format": "uri",
                          "pattern": "^https://(?![0-9.]+(:[0-9]+)?$)[A-Za-z0-9-]+(\\.[A-Za-z0-9-]+)*(:[0-9]{1,5})?$",
                          "maxLength": 2048
                        },
                        "tenant": {
                          "type": "string",
                          "minLength": 1,
                          "format": "uri",
                          "maxLength": 2048
                        }
                      }
                    },
                    "addressed_to": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 320
                    },
                    "subject": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "id",
                        "title"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "minLength": 1,
                          "format": "uri",
                          "maxLength": 2048
                        },
                        "title": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 2048
                        }
                      }
                    },
                    "contract": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "id",
                        "version",
                        "contractDigest"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "minLength": 1,
                          "format": "uri",
                          "pattern": "^https://",
                          "maxLength": 2048
                        },
                        "version": {
                          "type": "string",
                          "minLength": 1,
                          "maxLength": 64
                        },
                        "contractDigest": {
                          "type": "string",
                          "minLength": 1,
                          "pattern": "^sha-256:[0-9a-f]{64}$"
                        }
                      }
                    },
                    "reference": {
                      "type": "string",
                      "format": "uri"
                    },
                    "revision": {
                      "type": "string",
                      "minLength": 1
                    },
                    "expires_at": {
                      "type": "string",
                      "minLength": 1,
                      "format": "date-time",
                      "pattern": "^\\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12]\\d|3[01])T([01]\\d|2[0-3]):[0-5]\\d:[0-5]\\dZ$"
                    },
                    "allowed_actions": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "uniqueItems": true
                    },
                    "publication": {
                      "type": "object"
                    },
                    "state": {
                      "const": "awaiting_review"
                    },
                    "content_artifact": {
                      "type": "object",
                      "additionalProperties": false,
                      "required": [
                        "media_type",
                        "text"
                      ],
                      "properties": {
                        "media_type": {
                          "const": "text/markdown"
                        },
                        "text": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "review_id": "p7",
                  "interaction": "urn:uuid:0199a6c2-4b1e-7c3a-9d2e-5f8a1b2c3d41",
                  "service": {
                    "id": "https://service.example",
                    "tenant": "urn:example:tenant:7"
                  },
                  "addressed_to": "owner@example.net",
                  "subject": {
                    "id": "urn:example:object:42",
                    "title": "Publish the getting started guide"
                  },
                  "contract": {
                    "id": "https://mailschema.org/types/publication-approval",
                    "version": "0.1",
                    "contractDigest": "sha-256:de91a49de4cba91209be253456e7c56709791fff877a060560d4eada0cc9468c"
                  },
                  "reference": "urn:example:proposal:p7",
                  "revision": "p7-r4",
                  "expires_at": "2026-10-03T08:00:00Z",
                  "allowed_actions": [
                    "approve",
                    "decline",
                    "request-changes"
                  ],
                  "publication": {
                    "summary": "Publish the approved getting started guide.",
                    "requester": "Documentation editor",
                    "content": {
                      "id": "urn:example:content:42",
                      "revision": "r4",
                      "title": "Getting started",
                      "digest": "sha-256:4ffdf504c44a73a059c09c9cb30362c04f593b3af405b83bc084bb045067f95c"
                    },
                    "destinations": [
                      {
                        "id": "https://docs.service.example/guide",
                        "account": "urn:example:account:7",
                        "visibility": "public"
                      }
                    ],
                    "schedule": {
                      "mode": "immediate"
                    }
                  },
                  "state": "awaiting_review",
                  "content_artifact": {
                    "media_type": "text/markdown",
                    "text": "# Getting started\n\nCreate a workspace, connect your inbox and invite your team.\n"
                  }
                }
              }
            }
          },
          "403": {
            "description": "The account cannot inspect this review."
          }
        }
      }
    },
    "/reviews/{id}/decision": {
      "parameters": [
        {
          "in": "path",
          "name": "id",
          "required": true,
          "schema": {
            "type": "string",
            "minLength": 1
          }
        }
      ],
      "post": {
        "operationId": "decideReview",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "decision",
                  "expected_revision"
                ],
                "properties": {
                  "decision": {
                    "enum": [
                      "approve",
                      "decline",
                      "request-changes"
                    ]
                  },
                  "expected_revision": {
                    "type": "string",
                    "minLength": 1
                  },
                  "comment": {
                    "type": "string",
                    "minLength": 1,
                    "maxLength": 4096
                  }
                },
                "allOf": [
                  {
                    "if": {
                      "properties": {
                        "decision": {
                          "const": "request-changes"
                        }
                      }
                    },
                    "then": {
                      "required": [
                        "comment"
                      ]
                    },
                    "else": {
                      "not": {
                        "required": [
                          "comment"
                        ]
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The decline or change request is recorded; publication is not authorized."
          },
          "202": {
            "description": "Publication was accepted and is queued; it has not necessarily completed.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "review_id",
                    "state"
                  ],
                  "properties": {
                    "review_id": {
                      "type": "string"
                    },
                    "state": {
                      "const": "queued"
                    }
                  }
                },
                "example": {
                  "review_id": "p7",
                  "state": "queued"
                }
              }
            }
          },
          "403": {
            "description": "Current permission is insufficient; no decision was recorded."
          },
          "409": {
            "description": "No decision recorded: stale_revision, already_decided or withdrawn.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "code"
                  ],
                  "properties": {
                    "code": {
                      "enum": [
                        "stale_revision",
                        "already_decided",
                        "withdrawn"
                      ]
                    }
                  }
                }
              }
            }
          },
          "410": {
            "description": "The review expired; no decision recorded."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "accountToken": {
        "type": "http",
        "scheme": "bearer"
      }
    }
  }
}