radiantearth · philvarner · Mar 17, 2022 · Mar 2, 2022 · Mar 2, 2022 · Mar 2, 2022
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -18,10 +18,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Query Extension is no longer deprecated.
 - Children conformance class now requires the /children endpoint includes all child catalogs or collections
   referenced via `child` link relations from the Landing Page
+- Clarified behavior of Transaction Extension endpoints:
+  - PUT and PATCH of a body that changes the `collection` or `id` is disallowed.
+  - POST, PUT, and PATCH do not need to include the `collection` attribute, as it should be derived from the URL.
+  - POST and PUT can be used with a body that is at least a GeoJSON Feature, but does not have to be an Item, but for which 
+    the server can derive a valid Item, e.g., by populating the id and collection fields or adding links
+  - Likewise, POST can be used with a body of a FeatureCollection that contains features that meet the same constraints.
 - Specifications now use the term "must" instead of "shall". The semantics of these words are identical.
 - Conformance class for Item Search Filter is now
   `https://api.stacspec.org/v1.0.0-beta.5/item-search#filter`, whereas before it was incorrectly stated as
   `https://api.stacspec.org/v1.0.0-beta.5/item-search#filter:item-search-filter`
+
 ### Deprecated
 
 ### Removed

diff --git a/ogcapi-features/extensions/transaction/README.md b/ogcapi-features/extensions/transaction/README.md
@@ -24,14 +24,63 @@ OGC API [Simple Transactions](http://docs.opengeospatial.org/DRAFTS/20-002.html)
 once it is released STAC will align to a released one, but we anticipate few changes as it is a very simple document.
 
 STAC Transactions additionally support optimistic locking through use of the ETag header, as specified in the
-OpenAPI document. This is not currently specified in OGC API - Features, but it is compatible and we will 
+OpenAPI document. This is not currently specified in *OGC API - Features*, but it is compatible and we will 
 work to get it incorporated.
 
 ## Methods
 
-| Path                                                   | Content-Type Header | Description                                                                                                                      |
-| ------------------------------------------------------ | ------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| `POST /collections/{collectionID}/items`               | `application/json`  | Adds a new item to a collection.                                                                                                 |
-| `PUT /collections/{collectionId}/items/{featureId}`    | `application/json`  | Updates an existing item by ID using a complete item description.                                                                |
-| `PATCH /collections/{collectionId}/items/{featureId}`  | `application/json`  | Updates an existing item by ID using a partial item description, compliant with [RFC 7386](https://tools.ietf.org/html/rfc7386). |
-| `DELETE /collections/{collectionID}/items/{featureId}` | n/a                 | Deletes an existing item by ID.                                                                                                  |
+| Path                                                   | Content-Type Header | Body                                   | Success Status | Description                                                       |
+| ------------------------------------------------------ | ------------------- | -------------------------------------- | -------------- | ----------------------------------------------------------------- |
+| `POST /collections/{collectionID}/items`               | `application/json`  | partial Item or partial ItemCollection | 201, 202       | Adds a new item to a collection.                                  |
+| `PUT /collections/{collectionId}/items/{featureId}`    | `application/json`  | partial Item                           | 200, 202, 204  | Updates an existing item by ID using a complete item description. |
+| `PATCH /collections/{collectionId}/items/{featureId}`  | `application/json`  | partial Item                           | 200, 202, 204  | Updates an existing item by ID using a partial item description.  |
+| `DELETE /collections/{collectionID}/items/{featureId}` | n/a                 | n/a                                    | 200, 202, 204  | Deletes an existing item by ID.                                   |
+
+### POST
+
+When the body is a partial Item:
+
+- Shall only create a new resource.
+- Shall return 409 if an Item exists for the same collection and id values.
+- Shall populate the `collection` field in the Item from the URI.
+- Shall return 201 and a Location header with the URI of the newly added resource for a successful operation.
+- May return the content of the newly added resource for a successful operation.
+
+When the body is a partial ItemCollection:
+
+- Shall only create a new resource.
+- Shall return 409 if an Item exists for any of the same collection and id values.
+- Shall populate the `collection` field in each Item from the URI.
+- Shall return 201 without a Location header.
+- May create only some of the Items in the ItemCollection.
+
+All cases:
+
+- Shall return 202 if the operation is queued for asynchronous execution.
+
+### PUT
+
+- Shall populate the `id` and `collection` fields in the Item from the URI.
+- Shall return 200 or 204 for a successful operation.
+- If 200 status code is returned, the server shall return the content of the updated resource for a successful operation.
+- Shall return 202 if the operation is queued for asynchronous execution.
+- Shall return 404 if no Item exists for this resource URI.
+- If the `id` or `collection` fields are different from those in the URI, status code 400 shall be returned.
+
+### PATCH
+
+- Shall populate the `id` and `collection` fields in the Item from the URI.
+- Shall return 200 or 204 for a successful operation.
+- If status code 200 is returned, the server shall return the content of the updated resource for a successful operation.
+- May return the content of the updated resource for a successful operation.
+- Shall return 202 if the operation is queued for asynchronous execution.
+- Shall return 404 if no Item exists for this resource URI.
+- If the `id` or `collection` fields are different from those in the URI, status code 400 shall be returned.
+
+PATCH is compliant with [RFC 7386](https://tools.ietf.org/html/rfc7386).
+
+### DELETE
+
+- Shall return 200 or 204 for a successful operation.
+- Shall return a 202 if the operation is queued for asynchronous execution.
+- May return a 404 if no Item existed prior to the delete operation. Returning a 200 or 204 is also valid in this situation.
diff --git a/ogcapi-features/extensions/transaction/openapi.yaml b/ogcapi-features/extensions/transaction/openapi.yaml
@@ -21,8 +21,8 @@ paths:
     parameters:
       - $ref: '../../openapi.yaml#/components/parameters/collectionId'
     post:
-      summary: add a new STAC Item to a collection
-      description: create a new STAC Item in a specific collection
+      summary: add a new STAC Item or Items in an ItemCollection to a collection
+      description: create a new STAC Item r Items in an ItemCollection in a specific collection
       operationId: postFeature
       tags:
         - Transaction
@@ -31,8 +31,8 @@ paths:
           application/json:
             schema:
               oneOf:
-                - $ref: '../../../core/commons.yaml#/components/schemas/item'
-                - $ref: '../../../fragments/itemcollection/openapi.yaml#/components/schemas/itemCollection'
+                - $ref: '#/components/schemas/postOrPutItemCollection'
+                - $ref: '#/components/schemas/postOrPutItem'
       responses:
         '201':
           description: Status of the create request.
@@ -50,6 +50,8 @@ paths:
             application/json:
               schema:
                 $ref: '../../../core/commons.yaml#/components/schemas/item'
+        '202':
+          description: The item was accepted for asynchronous action
         '400':
           $ref: '#/components/responses/BadRequest'
         '404':
@@ -96,8 +98,21 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '../../../core/commons.yaml#/components/schemas/item'
+              $ref: '#/components/schemas/postOrPutItem'
       responses:
+        '200':
+          description: The item was replaced
+          headers:
+            ETag:
+              schema:
+                type: string
+              description: An updated string to track changes
+          content:
+            application/json:
+              schema:
+                $ref: '../../../core/commons.yaml#/components/schemas/item'
+        '202':
+          description: The item was accepted for asynchronous action
         '204':
           description: The item was replaced
           headers:
@@ -133,8 +148,21 @@ paths:
         content:
           application/json:
             schema:
-              $ref: '#/components/schemas/partialItem'
+              $ref: '#/components/schemas/patchItem'
       responses:
+        '200':
+          description: The item was replaced
+          headers:
+            ETag:
+              schema:
+                type: string
+              description: An updated string to track changes
+          content:
+            application/json:
+              schema:
+                $ref: '../../../core/commons.yaml#/components/schemas/item'
+        '202':
+          description: The item was accepted for asynchronous action
         '204':
           description: Status of the update request.
           headers:
@@ -163,8 +191,12 @@ paths:
       parameters:
         - $ref: '#/components/parameters/IfMatch'
       responses:
-        '204':
+        '200':
           description: The resource was deleted.
+        '202':
+          description: The operation was accepted for asynchronous executiona.
+        '204':
+          description: The resource was deleted. 
         '400':
           $ref: '#/components/responses/BadRequest'
         '404':
@@ -196,7 +228,9 @@ components:
       schema:
         type: string
   schemas:
-    partialItem:
+    patchItem:
+      description: >-
+        An object that contains at least a subset of the fields for a STAC Item.
       type: object
       properties:
         stac_version:
@@ -212,25 +246,79 @@ components:
         type:
           $ref: '../../../core/commons.yaml#/components/schemas/itemType'
         properties:
-          $ref: '#/components/schemas/partialItemProperties'
+          $ref: '#/components/schemas/patchItemProperties'
         links:
           type: array
           items:
             $ref: '../../../core/commons.yaml#/components/schemas/link'
         assets:
           $ref: '../../../core/commons.yaml#/components/schemas/assets'
-      example:
-        assets:
-          analytic:
-            title: 1-Band Analytic
-            href: http://cool-sat.com/catalog/collections/cs/items/CS3-201605XX_132130_04/analytic-1.tif
-    partialItemProperties:
+    patchItemProperties:
+      description: >-
+        An object that contains at least a subset of a valid STAC Item Properties object.
       type: object
-      description: allows for partial collections of metadata fields
       additionalProperties: true
       properties:
         datetime:
           $ref: '../../../core/commons.yaml#/components/schemas/datetime'
+    postOrPutItemCollection:
+      description: >-
+        A GeoJSON FeatureCollection augmented with foreign members that contain values relevant to a STAC entity
+      type: object
+      required:
+        - features
+        - type
+      properties:
+        type:
+          type: string
+          enum:
+            - FeatureCollection
+        features:
+          type: array
+          items:
+            $ref: '#/components/schemas/postOrPutItem'
+        links:
+          description: >-
+            An array of links. Can be used for pagination, e.g. by providing a link
+            with the `next` relation type.
+          type: array
+          items:
+            $ref: '../../../core/commons.yaml#/components/schemas/link'
+          example:
+            - rel: next
+              href: >-
+                http://api.cool-sat.com/search?next=ANsXtp9mrqN0yrKWhf-y2PUpHRLQb1GT-mtxNcXou8TwkXhi1Jbk
+    postOrPutItem:
+      description: >-
+        An object that is a valid GeoJSON Feature, but not necessarily a valid STAC Item.
+      type: object
+      required:
+        - stac_version
+        - id
+        - type
+        - geometry
+        - properties
+      properties:
+        stac_version:
+          $ref: '../../../core/commons.yaml#/components/schemas/stac_version'
+        stac_extensions:
+          $ref: '../../../core/commons.yaml#/components/schemas/stac_extensions'
+        id:
+          $ref: '../../../core/commons.yaml#/components/schemas/itemId'
+        bbox:
+          $ref: '../../../core/commons.yaml#/components/schemas/bbox'
+        geometry:
+          $ref: '../../../core/commons.yaml#/components/schemas/geometryGeoJSON'
+        type:
+          $ref: '../../../core/commons.yaml#/components/schemas/itemType'
+        properties:
+          $ref: '../../../core/commons.yaml#/components/schemas/properties'
+        links:
+          type: array
+          items:
+            $ref: '../../../core/commons.yaml#/components/schemas/link'
+        assets:
+          $ref: '../../../core/commons.yaml#/components/schemas/assets'
   responses:
     BadRequest:
       description: The request was malformed or semantically invalid