From 654a2fd7c210979b6a2cbab99307ea840c949e43 Mon Sep 17 00:00:00 2001
From: Brandon Mitchell <git@bmitch.net>
Date: Sat, 30 Mar 2024 11:17:54 -0400
Subject: [PATCH] Converting the recommended limit to an implementers note

Signed-off-by: Brandon Mitchell <git@bmitch.net>
---
 spec.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/spec.md b/spec.md
index eacc730d..b4a32dc4 100644
--- a/spec.md
+++ b/spec.md
@@ -548,10 +548,13 @@ The tags MUST be in lexical order.
 
 When using the `last` query parameter, the `n` parameter is OPTIONAL.
 
-The registry SHOULD support at least `n=1000` tags in a single response.
-The client SHOULD avoid requesting more than `n=1000` tags in a single request.
 If the registry is unable to return all tags requested by the client, the registry MUST return a `413 Content Too Large` with `TAG_LIMIT_EXCEEDED` error <sup>[code-15](#error-codes)</sup> and include the header `OCI-Tag-Limit: <limit>`, where `<limit>` is the maximum tags per request supported by the registry.
 
+*Implementers note:*
+Most registries support at least 1000 tags per request, but limits have been seen as low as 50 tags per request.
+To maximize the tags per page, a request without setting `n` can be used, which should either return the full list of tags, or an error with the `OCI-Tag-Limit` header indicating the limit.
+When available, clients should prefer the `Link` header over using the `last` parameter for pagination.
+
 ##### Listing Referrers
 
 *Note: this feature was added in distibution-spec 1.1.