Update spec to include tag history endpoint

Author: jcarter3

extensions/_oci.md

@@ -70,7 +70,7 @@ Content-Type: application/json
 
 This component is for endpoints relating to tag history operations on a repository.
 
-This endpoint returns the history of a tag, listing each manifest the tag has pointed to over time, in descending order by creation timestamp (newest first).
+This endpoint returns the history of a tag, listing each manifest the tag has pointed to over time and each time the tag was deleted, in descending order by history entry timestamp (newest first).
 
 Tag history MAY be retrieved with a standard `GET` as follows.
 
@@ -81,7 +81,12 @@ GET /v2/<name>/_oci/tag-history/<tag>
 `<name>` is the namespace of the repository, and `<tag>` is the name of the tag whose history is being queried.
 
 A successful request MUST return a `200 OK` response code.
-If the tag or repository does not exist, the registry MUST return a `404 Not Found` response code.
+If the repository does not exist, the registry MUST return a `404 Not Found` response code.
+If the tag has no history, the registry MUST return a `404 Not Found` response code.
+Tag history SHOULD remain queryable after the tag is deleted.
+Deleted manifests MUST NOT be removed from tag history.
+History entries for deleted manifests MUST continue to include the descriptor fields recorded when the tag was assigned to the manifest.
+Tag history MAY be deleted after the repository is deleted.
 
 Upon success, the response body MUST be a JSON array of descriptor objects in the following format:
 
@@ -99,6 +104,15 @@ Content-Type: application/json
             "org.opencontainers.tag.created": "2026-05-04T03:02:01Z"
         }
     },
+    {
+        "mediaType": "application/vnd.oci.empty.v1+json",
+        "digest": "sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a",
+        "size": 2,
+        "data": "e30=",
+        "annotations": {
+            "org.opencontainers.tag.deleted": "2026-05-03T03:02:01Z"
+        }
+    },
     {
         "mediaType": "application/vnd.oci.image.manifest.v1+json",
         "size": 1234,
@@ -110,9 +124,11 @@ Content-Type: application/json
 ]
 ```
 
-Results MUST be sorted in descending order by the `org.opencontainers.tag.created` annotation value (i.e. the most recently created entry appears first).
+Results MUST be sorted in descending order by the history entry timestamp, which is either the `org.opencontainers.tag.created` annotation value or the `org.opencontainers.tag.deleted` annotation value (i.e. the most recent entry appears first).
+
+Each descriptor object in the response MUST be either a manifest descriptor or a delete marker.
 
-Each descriptor object in the response MUST include the following properties:
+Manifest descriptors MUST include the following properties:
 
 - **`mediaType`** *string*, REQUIRED
 
@@ -134,6 +150,32 @@ Each descriptor object in the response MUST include the following properties:
 
     The RFC 3339 timestamp at which the tag was assigned to this manifest. Used as the sort key and as the cursor for time-based pagination.
 
+Delete markers MUST be represented by the OCI empty descriptor and MUST include the following properties:
+
+- **`mediaType`** *string*, REQUIRED
+
+  MUST be `application/vnd.oci.empty.v1+json`.
+
+- **`digest`** *string*, REQUIRED
+
+  MUST be `sha256:44136fa355b3678a1146ad16f7e8649e94fb4fc21fe77e8310c060f61caaff8a`.
+
+- **`size`** *integer*, REQUIRED
+
+  MUST be `2`.
+
+- **`data`** *string*, REQUIRED
+
+  MUST be `e30=`.
+
+- **`annotations`** *map of strings*, REQUIRED
+
+  Annotations associated with the historical tag entry. MUST include:
+
+  - **`org.opencontainers.tag.deleted`** *string*, REQUIRED
+
+    The RFC 3339 timestamp at which the tag was deleted. Used as the sort key and as the cursor for time-based pagination.
+
 ##### Query Parameters
 
 The following query parameters MAY be provided:
@@ -147,8 +189,8 @@ The following query parameters MAY be provided:
 
 - **`before`** *string (RFC 3339 timestamp)*, OPTIONAL
 
-  When provided, only entries whose `org.opencontainers.tag.created` value is strictly less than (i.e. older than) `before` will be returned.
-  This is used for time-based pagination: pass the `org.opencontainers.tag.created` value of the last entry returned in the previous response to retrieve the next page.
+  When provided, only entries whose history entry timestamp is strictly less than (i.e. older than) `before` will be returned.
+  This is used for time-based pagination: pass the `org.opencontainers.tag.created` or `org.opencontainers.tag.deleted` value of the last entry returned in the previous response to retrieve the next page.
 
 ##### Pagination Example
 
@@ -158,7 +200,7 @@ To fetch the first page of up to 10 results:
 GET /v2/<name>/_oci/tag-history/<tag>?n=10
 ```
 
-To fetch the next page, pass the `org.opencontainers.tag.created` value of the last result from the prior response as the `before` parameter:
+To fetch the next page, pass the history entry timestamp of the last result from the prior response as the `before` parameter:
 
 ```HTTP
 GET /v2/<name>/_oci/tag-history/<tag>?n=10&before=2026-04-03T02%3A01%3A00Z