From 3e335f5d26b1cb4ca1421f97c6a16c800b025a65 Mon Sep 17 00:00:00 2001
From: Alex Stephen <astephen2@gmail.com>
Date: Fri, 14 Nov 2025 12:59:32 -0800
Subject: [PATCH 1/3] AEP 216 OAS guidance

---
 aep/general/0216/aep.md.j2 | 45 +++++++++++++++++++++++++++++++++++---
 1 file changed, 42 insertions(+), 3 deletions(-)

diff --git a/aep/general/0216/aep.md.j2 b/aep/general/0216/aep.md.j2
index 64323a43..50418205 100644
--- a/aep/general/0216/aep.md.j2
+++ b/aep/general/0216/aep.md.j2
@@ -116,9 +116,48 @@ message PublishBookRequest {
 }
 ```
 
-{% tab oas %}
-
-**Note:** OAS content not yet written.
+{% tab oas %} State transition methods in OpenAPI follow these requirements:
+
+- The HTTP method **must** be `POST`.
+- The path **must** use the `:` separator followed by the action verb (e.g.,
+  `:publish`).
+- The request body **should** be an object containing any additional parameters
+  beyond the resource path.
+  - If no additional parameters are needed, an empty object `{}` **should** be
+    sent.
+- The response **should** be the resource itself (e.g., the `Book` object).
+  - If the operation is long-running, the response **should** be an `Operation`
+    object which resolves to the resource.
+- The resource path parameters (e.g., `publisher_id`, `book_id`) **should** be
+  the only path variables in the URI. All other parameters **should** be in the
+  request body.
+- If the state transition is not allowed, the API **must** return
+  `400 Bad Request`.
+
+Example OpenAPI specification:
+
+```yaml
+components:
+  schemas:
+    Book:
+      type: object
+      properties:
+        name:
+          type: string
+          description: |
+            The resource name of the book.
+            Format: publishers/{publisher_id}/books/{book_id}
+        state:
+          type: string
+          readOnly: true
+          enum:
+            - STATE_UNSPECIFIED
+            - DRAFT
+            - PUBLISHED
+          description: |
+            Output only. The current state of the book. This field cannot be
+            directly updated through create or update methods.
+```
 
 {% endtabs %}
 

From a050ca933f198ed261b1d7ef2cbf6c10a8db4032 Mon Sep 17 00:00:00 2001
From: Alex Stephen <astephen2@gmail.com>
Date: Mon, 17 Nov 2025 11:08:12 -0800
Subject: [PATCH 2/3] PR comment

---
 aep/general/0216/aep.md.j2 | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/aep/general/0216/aep.md.j2 b/aep/general/0216/aep.md.j2
index 50418205..35967a5d 100644
--- a/aep/general/0216/aep.md.j2
+++ b/aep/general/0216/aep.md.j2
@@ -116,7 +116,9 @@ message PublishBookRequest {
 }
 ```
 
-{% tab oas %} State transition methods in OpenAPI follow these requirements:
+{% tab oas %} 
+
+State transition methods in OpenAPI follow these requirements:
 
 - The HTTP method **must** be `POST`.
 - The path **must** use the `:` separator followed by the action verb (e.g.,
@@ -151,7 +153,6 @@ components:
           type: string
           readOnly: true
           enum:
-            - STATE_UNSPECIFIED
             - DRAFT
             - PUBLISHED
           description: |

From 0243d25ba4b0521b2bde0e3301525ed9c83d51a9 Mon Sep 17 00:00:00 2001
From: Alex Stephen <astephen2@gmail.com>
Date: Mon, 17 Nov 2025 20:04:01 -0800
Subject: [PATCH 3/3] lint

---
 aep/general/0216/aep.md.j2 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/aep/general/0216/aep.md.j2 b/aep/general/0216/aep.md.j2
index 35967a5d..5891b0bc 100644
--- a/aep/general/0216/aep.md.j2
+++ b/aep/general/0216/aep.md.j2
@@ -116,7 +116,7 @@ message PublishBookRequest {
 }
 ```
 
-{% tab oas %} 
+{% tab oas %}
 
 State transition methods in OpenAPI follow these requirements: