@tryghost/admin-api-schema 2.17.0 → 3.0.0

package/README.md

@@ -34,7 +34,7 @@ jsonSchema.get('tags-edit');
 /*
 > {
   '$schema': 'http://json-schema.org/draft-07/schema#',
-  '$id': 'tags.edit.canary',
+  '$id': 'tags.edit',
   title: 'tags.edit',
   description: 'Schema for tags.edit',
   type: 'object',
@@ -65,8 +65,7 @@ When used from Ghost core in validation layer:
 const jsonSchema = require('@tryghost/admin-api-schema');
 const validate = async (apiConfig, frame) => await jsonSchema.validate({
     data: frame.data,
-    schema: `${apiConfig.docName}-${apiConfig.method}`,
-    version: 'canary'
+    schema: `${apiConfig.docName}-${apiConfig.method}`
 });
 ```
 

package/lib/admin-api-schema.js

@@ -3,13 +3,12 @@ const jsonSchema = require('./utils/json-schema');
 
 /**
  *
- * @param {'v2'|'v3'|'canary'} version - API's JSON schema version to check against
- * @param {string} name -JSON schema to retreive from "version" folder
+ * @param {string} name -JSON schema to retreive from "schemas" folder
  *
  * @returns {Object} - JSON schema file content
  */
-const getJSONDefinition = (version, name) => {
-    const definitionPath = `./${version}/${name}`;
+const getJSONDefinition = (name) => {
+    const definitionPath = `./schemas/${name}`;
 
     try {
         return require(definitionPath);
@@ -21,37 +20,12 @@ const getJSONDefinition = (version, name) => {
 };
 
 /**
- * Resolves with a schema definition content. At the moment it contains unresolved `$ref` statements.
- * This method needs some additional work to be useful for outside consumer - contain resolved '$ref'.
- *
- * @param {Object} options
- * @param {'v2'|'v3'|'canary'} - API's JSON schema version to check against
- * @param {string} options.schema - name of JSON schema definition, comes from available optios returned by list()
- */
-const get = ({version, schema}) => {
-    if (!list({version}).includes(schema)) {
-        return null;
-    }
-
-    return getJSONDefinition(version, schema);
-};
-
-/**
- * Lists available JSON schema definitions for provided version
- *
- * @param {Object} options
- * @param {'v2'|'v3'|'v4'|'canary'} - API's JSON schema version to check against
+ * Lists available JSON schema definitions
  *
  * @returns {string[]} - list of available JSON schema definitions
  */
-const list = ({version}) => {
-    if (version === 'v2') {
-        return require('./v2');
-    } else if (version === 'v3') {
-        return require('./v3');
-    } else if (version === 'v4' || version === 'canary') {
-        return require('./canary');
-    }
+const list = () => {
+    return require('./schemas');
 };
 
 /**
@@ -59,7 +33,6 @@ const list = ({version}) => {
  *
  * @typedef {Object} ValidateOptions
  * @property {Object} options.data - data to validate
- * @property {'v2'|'v3'|'canary'} options.version - API version to data belongs to, e.g.: 'v2', 'canary'
  * @property {string} [options.schema] - name of the schema to validate against. Available schema names are returned by list() function
  * @property {string} [options.definition] - name of the definition where schema belongs
  */
@@ -71,8 +44,8 @@ const list = ({version}) => {
  *
  * @returns {Promise} - resolves a promise if validation is successful and rejects with error details otherwise
  */
-const validate = ({data, version, schema = '', definition = schema.split('-')[0]}) => {
-    const schemaJSON = get({schema, version});
+const validate = ({data, schema, definition = schema?.split('-')[0]}) => {
+    const schemaJSON = getJSONDefinition(schema);
 
     if (!schemaJSON) {
         throw new errors.IncorrectUsageError({
@@ -81,66 +54,13 @@ const validate = ({data, version, schema = '', definition = schema.split('-')[0]
         });
     }
 
-    const definitionJSON = getJSONDefinition(version, definition);
+    const definitionJSON = getJSONDefinition(definition);
 
     return jsonSchema.validate(schemaJSON, definitionJSON, data);
 };
 
-/**
- * Resolves version into "internal" one.
- * 'canary' is used to identify latest available version. Currently it's 'v3' and once there's
- * next version introduced - 'v4' should be resolved to 'canary', and 'v3' should be returned as is.
- *
- * @param {'v2'|'v3'|'v4'|'canary'} - version to resolve into internaly available version
- *
- * @returns {'v2'|'v3'|'canary'} - resolved version
- */
-const resolveVersion = (version) => {
-    switch (version) {
-    case 'canary':
-    case 'v4':
-        return 'canary';
-    case 'v3':
-        return 'v3';
-    case 'v2':
-        return 'v2';
-    default:
-        throw new errors.IncorrectUsageError({
-            message: `Unrecognised version ${version}.`
-        });
-    }
-};
-
-/**
- * Versioned version of 'get' method, which returns a JSON schema definition if found
- *
- * @param {string} schema - name of JSON schema definitions
- * @param {string} version - API's JSON schema version to check against
- *
- * @returns {Object|null} JSON schema definition or null if it's not found
- */
-const versionedGet = (schema, version = 'v4') => get({schema, version: resolveVersion(version)});
-
-/**
- * Versioned version of 'list' method, which lisists available JSON schema definitions for provided version
- *
- * @param {string} version - API's JSON schema version to check against
- *
- * @returns {string[]} - list of available JSON schema definitions
- */
-const versionedList = (version = 'v4') => list({version: resolveVersion(version)});
-
-/**
- * Versioned version of 'validate' method, which validates objects against predefined JSON Schema
- *
- * @param {ValidateOptions} options
- *
- * @returns {Promise} - resolves a promise if validation is successful and rejects with error details otherwise
- */
-const versionedValidate = options => validate(Object.assign(options, {version: resolveVersion(options.version || 'v4')}));
-
 module.exports = {
-    get: versionedGet,
-    list: versionedList,
-    validate: versionedValidate
+    get: getJSONDefinition,
+    list: list,
+    validate: validate
 };

package/lib/{canary → schemas}/README.md

@@ -2,7 +2,7 @@
 
 When adding a new schema or definition following naming convention should be followed:
 1. Name the file containing JSON definitions in the same way as resource is named in the API (aka "docName" in controller config). For example, for [tags](https://github.com/TryGhost/Ghost/blob/2a921b86598184fcd5a2d95fefae4283bba1042a/core/server/api/canary/tags.js#L9) the definitions file would be `tags.json`
-2. Name the file containing JSON schema (which usually references "definitions") using following convention `{resourceName}-{methodName}.json`. For example, for [tags.edit](https://github.com/TryGhost/Ghost/blob/master/core/server/api/canary/tags.js#L89) method file would be named `tags-edit.json`
+2. Name the file containing JSON schema (which usually references "definitions") using following convention `{resourceName}-{methodName}.json`. For example, for [tags.edit](https://github.com/TryGhost/Ghost/blob/7252f03824fff38564e4fa759a181b6228e094b2/core/server/api/canary/tags.js#L89) method file would be named `tags-edit.json`
 3. Update `index.js` list with a new definition name
 
 The need to have separate "definitions" and "schema" files comes from [schema reusability pattern](https://cswr.github.io/JsonSchema/spec/definitions_references/) that JSON schema allows for through $ref keyword. In some cases, the pattern doesn't quite work out because of limitations of the syntax (cannot override parts of referenced definition). Generally try to reuse as much schema as possible to avoid duplication unless it becomes painful to do so.

package/lib/{v3 → schemas}/images-upload.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "images.upload.v3",
+  "$id": "images.upload",
   "title": "images.upload",
   "description": "Schema for images.upload",
-  "$ref": "images.v3#/definitions/image"
+  "$ref": "images#/definitions/image"
 }

package/lib/{v2 → schemas}/images.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "images.v2",
+  "$id": "images",
   "title": "images",
   "description": "Base images definitions",
   "definitions": {

package/lib/{v3 → schemas}/labels-add.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "labels.add.v3",
+  "$id": "labels.add",
   "title": "labels.add",
   "description": "Schema for labels.add",
   "type": "object",
@@ -13,7 +13,7 @@
       "additionalProperties": false,
       "items": {
         "type": "object",
-        "allOf": [{ "$ref": "labels.v3#/definitions/label" }],
+        "allOf": [{ "$ref": "labels#/definitions/label" }],
         "required": ["name"]
       }
     }

package/lib/{v3 → schemas}/labels-edit.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "labels.edit.v3",
+  "$id": "labels.edit",
   "title": "labels.edit",
   "description": "Schema for labels.edit",
   "type": "object",
@@ -10,7 +10,7 @@
       "type": "array",
       "minItems": 1,
       "maxItems": 1,
-      "items": { "$ref": "labels.v3#/definitions/label" }
+      "items": { "$ref": "labels#/definitions/label" }
     }
   },
   "required": ["labels"]

package/lib/{v3 → schemas}/labels.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "labels.v3",
+  "$id": "labels",
   "title": "labels",
   "description": "Base labels definitions",
   "definitions": {

package/lib/{canary → schemas}/media-upload.json

@@ -1,7 +1,7 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "media.upload.canary",
+  "$id": "media.upload",
   "title": "media.upload",
   "description": "Schema for media.upload",
-  "$ref": "media.canary#/definitions/media"
+  "$ref": "media#/definitions/media"
 }

package/lib/{canary → schemas}/media.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "media.canary",
+  "$id": "media",
   "title": "media",
   "description": "Base media definitions",
   "definitions": {

package/lib/{v3 → schemas}/members-add.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "members.add.v3",
+  "$id": "members.add",
   "title": "members.add",
   "description": "Schema for members.add",
   "type": "object",
@@ -12,7 +12,7 @@
       "maxItems": 1,
       "items": {
         "type": "object",
-        "allOf": [{ "$ref": "members.v3#/definitions/member" }],
+        "allOf": [{ "$ref": "members#/definitions/member" }],
         "required": ["email"]
       }
     }

package/lib/{canary → schemas}/members-edit.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "members.edit.canary",
+  "$id": "members.edit",
   "title": "members.edit",
   "description": "Schema for members.edit",
   "type": "object",
@@ -46,16 +46,16 @@
             "strip": true
           },
           "products": {
-            "$ref": "members.canary#/definitions/member-products"
+            "$ref": "members#/definitions/member-products"
           },
           "tiers": {
-            "$ref": "members.canary#/definitions/member-products"
+            "$ref": "members#/definitions/member-products"
           },
           "newsletters": {
-            "$ref": "members.canary#/definitions/member-newsletters"
+            "$ref": "members#/definitions/member-newsletters"
           },
           "labels": {
-            "$ref": "members.canary#/definitions/member-labels"
+            "$ref": "members#/definitions/member-labels"
           },
           "email_count": {
             "strip": true

package/lib/{canary → schemas}/members-upload.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "members.upload.canary",
+  "$id": "members.upload",
   "title": "members.upload",
   "description": "Schema for members.upload",
   "type": "array",

package/lib/{canary → schemas}/members.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "members.canary",
+  "$id": "members",
   "title": "members",
   "description": "Base members definitions",
   "definitions": {

package/lib/{v3 → schemas}/pages-add.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "pages.add.v3",
+  "$id": "pages.add",
   "title": "pages.add",
   "description": "Schema for pages.add",
   "type": "object",
@@ -12,7 +12,7 @@
       "maxItems": 1,
       "items": {
         "type": "object",
-        "allOf": [{ "$ref": "pages.v3#/definitions/page" }],
+        "allOf": [{ "$ref": "pages#/definitions/page" }],
         "required": ["title"]
       }
     }

package/lib/{v3 → schemas}/pages-edit.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "pages.edit.v3",
+  "$id": "pages.edit",
   "title": "pages.edit",
   "description": "Schema for pages.edit",
   "type": "object",
@@ -12,7 +12,7 @@
       "maxItems": 1,
       "items": {
         "type": "object",
-        "allOf": [{ "$ref": "pages.v3#/definitions/page" }],
+        "allOf": [{ "$ref": "pages#/definitions/page" }],
         "required": ["updated_at"]
       }
     }

package/lib/{canary → schemas}/pages.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "pages.canary",
+  "$id": "pages",
   "title": "pages",
   "description": "Base pages definitions",
   "definitions": {

package/lib/{v3 → schemas}/posts-add.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "posts.add.v3",
+  "$id": "posts.add",
   "title": "posts.add",
   "description": "Schema for posts.add",
   "type": "object",
@@ -12,7 +12,7 @@
       "maxItems": 1,
       "items": {
         "type": "object",
-        "allOf": [{ "$ref": "posts.v3#/definitions/post" }],
+        "allOf": [{ "$ref": "posts#/definitions/post" }],
         "required": ["title"]
       }
     }

package/lib/{v3 → schemas}/posts-edit.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "posts.edit.v3",
+  "$id": "posts.edit",
   "title": "posts.edit",
   "description": "Schema for posts.edit",
   "type": "object",
@@ -12,7 +12,7 @@
       "maxItems": 1,
       "items": {
         "type": "object",
-        "allOf": [{ "$ref": "posts.v3#/definitions/post" }],
+        "allOf": [{ "$ref": "posts#/definitions/post" }],
         "required": ["updated_at"]
       }
     }

package/lib/{canary → schemas}/posts.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "posts.canary",
+  "$id": "posts",
   "title": "posts",
   "description": "Base posts definitions",
   "definitions": {

package/lib/{canary → schemas}/products-add.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "products.add.canary",
+  "$id": "products.add",
   "title": "products.add",
   "description": "Schema for products.add",
   "type": "object",
@@ -11,7 +11,7 @@
       "minItems": 1,
       "maxItems": 1,
       "items": {
-        "type": "products.canary#/definitions/product"
+        "type": "products#/definitions/product"
       }
     }
   },

package/lib/{canary → schemas}/products-edit.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "products.edit.canary",
+  "$id": "products.edit",
   "title": "products.edit",
   "description": "Schema for products.edit",
   "type": "object",
@@ -11,7 +11,7 @@
       "minItems": 1,
       "maxItems": 1,
       "items": {
-        "type": "products.canary#/definitions/product"
+        "type": "products#/definitions/product"
       }
     }
   },

package/lib/{canary → schemas}/products.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "products.canary",
+  "$id": "products",
   "title": "products",
   "description": "Base products definitions",
   "definitions": {
@@ -33,13 +33,13 @@
         "stripe_prices": {
           "type": ["array", "null"],
           "items": {
-            "type": "producs.canary#/definitions/stripe_price"
+            "type": "producs#/definitions/stripe_price"
           }
         },
         "benefits": {
           "type": ["array", "null"],
           "items": {
-            "type": "producs.canary#/definitions/product-benefit"
+            "type": "producs#/definitions/product-benefit"
           }
         }
       }

package/lib/{v3 → schemas}/snippets-add.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "snippets.add.v3",
+  "$id": "snippets.add",
   "title": "snippets.add",
   "description": "Schema for snippets.add",
   "type": "object",
@@ -13,7 +13,7 @@
       "additionalProperties": false,
       "items": {
         "type": "object",
-        "allOf": [{ "$ref": "snippets.v3#/definitions/snippet" }],
+        "allOf": [{ "$ref": "snippets#/definitions/snippet" }],
         "required": ["name", "mobiledoc"]
       }
     }

package/lib/{v3 → schemas}/snippets-edit.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "snippets.edit.v3",
+  "$id": "snippets.edit",
   "title": "snippets.edit",
   "description": "Schema for snippets.edit",
   "type": "object",
@@ -13,7 +13,7 @@
       "additionalProperties": false,
       "items": {
         "type": "object",
-        "allOf": [{ "$ref": "snippets.v3#/definitions/snippet" }],
+        "allOf": [{ "$ref": "snippets#/definitions/snippet" }],
         "required": ["name", "mobiledoc"]
       }
     }

package/lib/{v3 → schemas}/snippets.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "snippets.v3",
+  "$id": "snippets",
   "title": "snippets",
   "description": "Base snippets definitions",
   "definitions": {

package/lib/{v3 → schemas}/tags-add.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "tags.add.v3",
+  "$id": "tags.add",
   "title": "tags.add",
   "description": "Schema for tags.add",
   "type": "object",
@@ -13,7 +13,7 @@
       "additionalProperties": false,
       "items": {
         "type": "object",
-        "allOf": [{ "$ref": "tags.v3#/definitions/tag" }],
+        "allOf": [{ "$ref": "tags#/definitions/tag" }],
         "required": ["name"]
       }
     }

package/lib/{v2 → schemas}/tags-edit.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "tags.edit.v2",
+  "$id": "tags.edit",
   "title": "tags.edit",
   "description": "Schema for tags.edit",
   "type": "object",
@@ -10,7 +10,7 @@
       "type": "array",
       "minItems": 1,
       "maxItems": 1,
-      "items": { "$ref": "tags.v2#/definitions/tag" }
+      "items": { "$ref": "tags#/definitions/tag" }
     }
   },
   "required": ["tags"]

package/lib/{v3 → schemas}/tags.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "tags.v3",
+  "$id": "tags",
   "title": "tags",
   "description": "Base tags definitions",
   "definitions": {

package/lib/{canary → schemas}/tiers-add.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "tiers.add.canary",
+  "$id": "tiers.add",
   "title": "tiers.add",
   "description": "Schema for tiers.add",
   "type": "object",
@@ -12,7 +12,7 @@
       "maxItems": 1,
       "items": {
         "type": "object",
-        "allOf": [{ "$ref": "tiers.canary#/definitions/tier" }]
+        "allOf": [{ "$ref": "tiers#/definitions/tier" }]
       }
     }
   },

package/lib/{canary → schemas}/tiers-edit.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "tiers.edit.canary",
+  "$id": "tiers.edit",
   "title": "tiers.edit",
   "description": "Schema for tiers.edit",
   "type": "object",
@@ -12,7 +12,7 @@
       "maxItems": 1,
       "items": {
         "type": "object",
-        "allOf": [{ "$ref": "tiers.canary#/definitions/tier" }]
+        "allOf": [{ "$ref": "tiers#/definitions/tier" }]
       }
     }
   },

package/lib/{canary → schemas}/tiers.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "tiers.canary",
+  "$id": "tiers",
   "title": "tiers",
   "description": "Base Tier definitions",
   "definitions": {

package/lib/{v3 → schemas}/webhooks-add.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "webhooks.add.v3",
+  "$id": "webhooks.add",
   "title": "webhooks.add",
   "description": "Schema for webhooks.add",
   "type": "object",
@@ -12,7 +12,7 @@
       "maxItems": 1,
       "items": {
         "type": "object",
-        "allOf": [{ "$ref": "webhooks.v3#/definitions/webhook" }],
+        "allOf": [{ "$ref": "webhooks#/definitions/webhook" }],
         "required": ["event", "target_url"]
       }
     }

package/lib/{v3 → schemas}/webhooks-edit.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "webhooks.edit.v3",
+  "$id": "webhooks.edit",
   "title": "webhooks.edit",
   "description": "Schema for webhooks.edit",
   "type": "object",

package/lib/{v3 → schemas}/webhooks.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "webhooks.v3",
+  "$id": "webhooks",
   "title": "webhooks",
   "description": "Base webhooks definitions",
   "definitions": {