From e8a253701c78e5090a853d9c95709485d125a8dc Mon Sep 17 00:00:00 2001
From: Giuseppe Lo Presti <giuseppe.lopresti@cern.ch>
Date: Thu, 5 Mar 2026 12:29:22 +0100
Subject: [PATCH] Revised OpenAPI endpoints

Updated OpenAPI spec with new endpoint variables and descriptions to address https://github.com/cs3org/OCM-API/pull/317#issuecomment-3932426085
---
 spec.yaml | 22 +++++++++++++++-------
 1 file changed, 15 insertions(+), 7 deletions(-)

diff --git a/spec.yaml b/spec.yaml
index f8744de..d1753ad 100644
--- a/spec.yaml
+++ b/spec.yaml
@@ -4,24 +4,29 @@ info:
   description: >
     Open Cloud Mesh OpenAPI Specification.
     The semantic of the Protocol Specification is detailed in the
-    [IETF-RFC.md](https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md) document.
+    [IETF-RFC.md](https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md)
+    document, published at the [IETF Datatracker](https://datatracker.ietf.org/doc/draft-ietf-ocm-open-cloud-mesh).
   version: 1.3.0
   x-logo:
     url: logo.png
 servers:
-  - url: https://{discovery_fqdn}
+  - url: https://{ocm_endpoint}
+    description: >
+      The root of the Open Cloud Mesh API, dynamically resolved by taking the `endpoint`
+      value returned by the Discovery endpoint. 
     variables:
-      discovery_fqdn:
-        default: cloud.example.org
+      ocm_endpoint:
+        default: cloud.example.org/ocm
 paths:
   /.well-known/ocm:
+    servers:
+      - url: https://cloud.example.org
+        description: The OCM Server's top-level FQDN.
     get:
       summary: Discovery endpoint
       description: >
         Following [RFC8615], this endpoint returns the properties and
-        capabilities offered by an OCM Server. This endpoint MUST be
-        served at the OCM Server's root FQDN, e.g. as in
-        `https://cloud.example.org/.well-known/ocm`. See [OCM API Discovery](https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md#ocm-api-discovery)
+        capabilities offered by an OCM Server. See [OCM API Discovery](https://github.com/cs3org/OCM-API/blob/develop/IETF-RFC.md#ocm-api-discovery)
         for more details.
       responses:
         "200":
@@ -32,6 +37,9 @@ paths:
               schema:
                 $ref: "#/components/schemas/Discovery"
   /ocm-provider:
+    servers:
+      - url: https://cloud.example.org
+        description: The OCM Server's root FQDN.
     get:
       summary: Legacy discovery endpoint
       description: >