From d7a01145d4784c4e7394c39ad6056a0ce700dde9 Mon Sep 17 00:00:00 2001
From: Ramkumar Chinchani <rchincha@cisco.com>
Date: Wed, 17 Jan 2024 01:15:32 +0000
Subject: [PATCH] docs: initial commit for search extension

https://github.com/opencontainers/distribution-spec/issues/71

Signed-off-by: Ramkumar Chinchani <rchincha@cisco.com>
---
 extensions/_search.md | 121 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 121 insertions(+)
 create mode 100644 extensions/_search.md

diff --git a/extensions/_search.md b/extensions/_search.md
new file mode 100644
index 00000000..63ade899
--- /dev/null
+++ b/extensions/_search.md
@@ -0,0 +1,121 @@
+---
+tags: oci,distribution
+breaks: false
+---
+
+# Search Extensions API for Distribution 
+
+The distribution spec allows for OPTIONAL [extensions](./README.md) that registry operators
+may implement.
+
+```http
+GET /v2/_<extension>/<component>/<module>[?<key>=<value>&...]
+```
+
+One use case that is rising in prominence is standardized _search_ capability
+within registries. This capability can be organized under _oci as follows.
+
+```http
+GET `/v2/_oci/ext/search[?<key>=<value>&...]`
+```
+
+# Search vs List?
+
+In this document, if not explicitly called out, it is understood that Search is
+a truncated List based on certain criteria.
+
+# Search Use Cases
+
+Search for:
+
+* Repository name
+
+Return a list of repositories matching _name_. If _name_ is not specified, return all repositories (similar to /v2/_catalog query)
+
+```http
+GET `/v2/_oci/ext/search[?repository=<name>]`
+```
+
+** For all the following search queries, an additional _repository=<repository>_ query param can be added to further qualify the search.
+
+* Image name
+
+Return a list of images in a _repository_ matching _name_. If _name_ is not specified, return all images (similar to /v2/<>/tags/list query)
+
+```http
+GET `/v2/_oci/ext/search[?repository=<repository>&image=<name>]`
+```
+
+* MediaType
+
+Return a list of images matching _name_ media-type. If _name_ is not specified, return all images.
+
+```http
+GET `/v2/_oci/ext/search[?mediaType=<name>]`
+```
+
+* ArtifactType
+
+Return a list of images matching _name_ artifact-type. If _name_ is not specified, return all images.
+
+```http
+GET `/v2/_oci/ext/search[?artifactType=<name>]`
+```
+
+* Annotation
+
+Return a list of images matching _name_ annotation. If _name_ is not specified, return all images.
+
+```http
+GET `/v2/_oci/ext/search[?annotation=<name>]`
+```
+
+* Digest
+
+Return a list of images matching _hash_ digest. If _hash_ is not specified, return all images.
+
+```http
+GET `/v2/_oci/ext/search[?digest=<hash>]`
+```
+
+* Free-form global search
+
+Return a list of repositories and images matching _name_ name. If _name_ is not specified, return all repositories and images.
+
+```http
+GET `/v2/_oci/ext/search[?global=<key>]`
+```
+
+* Artifact content search
+
+Return a list of images containing a _key_ within artifact contents.
+
+```http
+GET `/v2/_oci/ext/search[?artifactType=<application/spdx>&key=<key>]`
+```
+
+# Prefix Match
+
+TBD
+
+# Regex
+
+TBD
+
+# Pagination
+
+Refer to [listing tags](https://github.com/opencontainers/distribution-spec/blob/main/spec.md#listing-tags) section.
+
+# Implementation Guidelines
+
+Not to prescribe an implementation but [GraphQL](https://en.wikipedia.org/wiki/GraphQL) could be a choice.
+TBD
+
+# Scalability
+
+When a registry has a very large number of repositories and images, then compiling and returning the results could be problematic.
+TBD
+
+# References
+
+[OCI Distribution Spec Extensions](./_oci.md)