fix: disambiguating *.meta fields

ipfs-pinning-service.yaml

@@ -82,7 +82,7 @@ A pin object can be removed via `DELETE /pins/{cid-of-pin-object}`.
 Pinning of new data can be accelerated by providing a list of known data
 sources in `Pin.providers`, and connecting at least one of them to pinning
 service nodes at `PinStatus.providers`.
-
+:
 
 The most common scenario is a client putting its own IPFS node's multiaddrs in
 `Pin.providers`,  and then directly connecting to every multiaddr returned by
@@ -96,15 +96,41 @@ issues in restrictive network topologies such as NATs.
 
 ## Custom metadata
 
-Pinning services are encouraged to add support for additional features by leveraging the following optional `meta` attributes. Note that it is OK to omit or ignore `meta` attributes; doing so should not impact the basic pinning functionality.
+Pinning services are encouraged to add support for additional features by leveraging optional `Pin.meta` and `PinStatus.info` fields.
+While these attributes can be application or vendor-specific, we encourage the community at large to leverage these attributes as a sandbox to come up with conventions that could become part of future revisions of this API.
+
+### Pin metadata
+
+String keys and values passed in `Pin.meta` are persisted with the pin object.
+
 
+Potential uses:
 
 - `Pin.meta[app_id]`: Attaching a unique identifier to pins created by an app enables filtering pins per app via `?meta={\"app_id\":<UUID>}`
 
-- `PinStatus.meta[status_details]`: Service-specific details. For example, when `PinStatus.status=failed`, it could provide a reason why a pin operation failed (e.g. lack of funds, DAG too big, etc.)
+- `Pin.meta[vendor_policy]`: Vendor-specific policy (which region use, how many copies keep)
+
+
+Note that it is OK for a client to omit or ignore these optional attributes; doing so should not impact the basic pinning functionality.
+
 
+### Pin status info
 
-While these attributes can be vendor-specific, we encourage the community at large to leverage these `meta` attributes as a sandbox to come up with conventions that could become part of future revisions of this API.
+Additional `PinStatus.info` can be returned by pinning service.
+
+
+Potential uses:
+
+- `PinStatus.info[status_details]`: more info about current status (queue
+  position, % of transferred data, summary of where data is stored etc); when
+  `PinStatus.status=failed`, it could provide a reason why a pin operation
+  failed (e.g. lack of funds, DAG too big, etc.)
+
+- `PinStatus.info[dag_size]`: the size of pinned data along with DAG overhead
+
+- `PinStatus.info[raw_size]`: the size of data without DAG overhead (eg. unixfs)
+
+- `PinStatus.info[pinned_until]`: if vendor supports time-bound pins, this could indicate when pin will expire
 
 
 # Pagination and filtering
@@ -280,6 +306,7 @@ components:
           type: integer
           format: int32
           minimum: 0
+          example: 1
         results:
           description: An array of PinStatus results
           type: array
@@ -314,8 +341,8 @@ components:
           $ref: '#/components/schemas/Pin'
         providers:
           $ref: '#/components/schemas/ServiceProviders'
-        meta:
-          $ref: '#/components/schemas/StatusMeta'
+        info:
+          $ref: '#/components/schemas/StatusInfo'
 
     Pin:
       description: Pin object
@@ -336,10 +363,10 @@ components:
       description: Status a pin object can have at a pinning service
       type: string
       enum:
-        - queued     # pinning operation is waiting in the queue; additional info can be returned in meta[status_details]      
-        - pinning    # pinning in progress; additional info can be returned in meta[status_details]
+        - queued     # pinning operation is waiting in the queue; additional info can be returned in info[status_details]      
+        - pinning    # pinning in progress; additional info can be returned in info[status_details]
         - pinned     # pinned successfully
-        - failed     # pinning service was unable to finish pinning operation; additional info can be found in meta[status_details]
+        - failed     # pinning service was unable to finish pinning operation; additional info can be found in info[status_details]
 
     ServiceProviders:
       description: List of multiaddrs designated by pinning service for transferring any new data from external peers
@@ -367,19 +394,19 @@ components:
       additionalProperties:
         type: string
         minProperties: 0
-        maxProperties: 1000        
+        maxProperties: 1000
       example:
         app_id: "99986338-1113-4706-8302-4420da6158aa" # Pin.meta[app_id], useful for filtering pins per app
 
-    StatusMeta:
-      description: Optional metadata for PinStatus response
+    StatusInfo:
+      description: Optional info for PinStatus response
       type: object
       additionalProperties:
         type: string
         minProperties: 0
-        maxProperties: 1000        
+        maxProperties: 1000
       example:
-        status_details: "Fetching new data: 50% complete" # PinStatus.meta[status_details], when status=pinning
+        status_details: "Queue position: 7 of 9" # PinStatus.info[status_details], when status=queued
 
     Error:
       description: Base error object