Added generic descriptions for hyperion collections, nodes, links, an… (

#40) * Added generic descriptions for hyperion collections, nodes, links, and errors; Added redocly tag for API-specific links * Updated to reflect feedback.
Edgio · Apr 23, 2024 · 6ad0b9d · 6ad0b9d
1 parent f74ba28
commit 6ad0b9d
Show file tree

Hide file tree

Showing 6 changed files with 34 additions and 23 deletions.
diff --git a/schema/collection.json b/schema/collection.json
@@ -9,23 +9,27 @@
     "@id": {
       "type": "string",
       "format": "uri-reference",
-      "x-go-name": "HyperionId"
+      "x-go-name": "HyperionId",
+      "description": "The relative URI through which this response was generated."
     },
     "@type": {
       "type": "string",
       "enum": [
         "Collection"
       ],
       "pattern": "^[A-Z][a-zA-Z0-9]*$",
-      "x-go-name": "HyperionType"
+      "x-go-name": "HyperionType",
+      "description": "Returns `Collection`."
     },
     "@links": {
       "$ref": "./collection-links.json",
-      "x-go-name": "HyperionLinks"
+      "x-go-name": "HyperionLinks",
+      "description": "A collection of links related to this collection."
     },
     "total_items": {
       "type": "integer",
-      "readOnly": true
+      "readOnly": true,
+      "description": "The total number of items in this collection."
     }
   },
   "required": [

diff --git a/schema/error-detail.json b/schema/error-detail.json
@@ -14,7 +14,7 @@
   "properties": {
     "@type": {
       "type": "string",
-      "description": "Value is always \"ErrorDetail\"",
+      "description": "Returns `ErrorDetail`.",
       "enum": [
         "ErrorDetail"
       ],
@@ -28,13 +28,13 @@
     "source": {
       "type": "string",
       "minLength": 1,
-      "description": "Represents a JSON Pointer [RFC6901]",
+      "description": "Represents a JSON pointer.",
       "format": "json-pointer"
     },
     "description": {
       "type": "string",
       "minLength": 1,
-      "description": "Description about the error detail"
+      "description": "Detailed error description."
     }
   },
   "required": [

diff --git a/schema/error.json b/schema/error.json
@@ -6,7 +6,7 @@
       "@type": "Error",
       "code": "unauthorized",
       "status_code": 401,
-      "title": "You are not authorized to access this resource"
+      "title": "You are not authorized to access this resource."
     }
   },
   "x-tags": [
@@ -20,7 +20,7 @@
       "enum": [
         "Error"
       ],
-      "description": "The value of this is \"Error\"",
+      "description": "Returns `Error`.",
       "pattern": "^[A-Z][a-zA-Z0-9]*$",
       "x-go-name": "HyperionType"
     },
@@ -40,26 +40,26 @@
         "service_unavailable",
         "gateway_timeout"
       ],
-      "description": "A human readable error code as string following snake_case",
+      "description": "Error code.",
       "pattern": "^[a-z][a-z_]*[a-z]$"
     },
     "status_code": {
       "type": "integer",
       "minimum": 100,
       "maximum": 599,
-      "description": "Represents the HTTP status code associated with response as integer"
+      "description": "The response's HTTP status code."
     },
     "title": {
       "type": "string",
       "minLength": 1,
-      "description": "The main error heading as string"
+      "description": "Error heading"
     },
     "description": {
       "type": "string",
-      "description": "Detailed description about the error as string"
+      "description": "Detailed error description."
     },
     "details": {
-      "description": "Array of error detail",
+      "description": "Array of error detail.",
       "type": "array",
       "items": {
         "$ref": "./error-detail.json"

diff --git a/schema/node-link-value.json b/schema/node-link-value.json
@@ -4,18 +4,21 @@
     "hyperion"
   ],
   "type": "object",
-  "description": "A node-link-value is an object containing a valid URI. See https://edgecast.github.io/hyperion/versions/1.0/#document-components-link-value",
+  "description": "An object that contains a valid URI.",
   "properties": {
     "href": {
       "type": "string",
-      "format": "uri-reference"
+      "format": "uri-reference",
+      "description": "The relative URL path."
     },
     "description": {
-      "type": "string"
+      "type": "string",
+      "description": "Additional information about this link."
     },
     "base_path": {
       "type": "string",
-      "format": "uri"
+      "format": "uri",
+      "description": "The base URL path. Construct the URL by prepending this path to the `href` value."
     }
   },
   "required": [

diff --git a/schema/node-links.json b/schema/node-links.json
@@ -2,9 +2,10 @@
   "type": "object",
   "title": "links",
   "additionalProperties": {
+    "x-additionalPropertiesName": "hypermedia_link",
     "$ref": "./node-link-value.json"
   },
-  "description": "Links is an object used to represent a collection of link values related to the resource.",
+  "description": "Represents hypermedia link(s) related to the resource.",
   "x-tags": [
     "hyperion"
   ],

diff --git a/schema/node.json b/schema/node.json
@@ -4,21 +4,24 @@
   "x-tags": [
     "hyperion"
   ],
-  "description": "Represents a hyperion JSON object",
+  "description": "Represents a resource.",
   "properties": {
     "@id": {
       "type": "string",
       "format": "uri-reference",
-      "x-go-name": "HyperionId"
+      "x-go-name": "HyperionId",
+      "description": "The resource's URI."
     },
     "@type": {
       "type": "string",
       "pattern": "^[A-Z][a-zA-Z0-9]*$",
-      "x-go-name": "HyperionType"
+      "x-go-name": "HyperionType",
+      "description": "The resource's type."
     },
     "@links": {
       "$ref": "./node-links.json",
-      "x-go-name": "HyperionLinks"
+      "x-go-name": "HyperionLinks",
+      "description": "A collection of links related to the resource."
     }
   },
   "required": [