adapt-authoring-jsonschema 0.0.1 → 1.0.0

package/docs/plugins/schemas-reference.js

@@ -1,74 +1,74 @@
-export default class SchemasReference {
-  constructor(app, config, dir, utils) {
-    this.app = app;
-    this.utils = utils;
-  }
-  async run() {
-    this.schemas = await this.loadSchemas();
-    this.manualFile = 'schemas-reference.md';
-    this.contents = Object.keys(this.schemas);
-    this.replace = { 'LIST': this.generateList() };
-  }
-  async loadSchemas() {
-    const schema = await this.app.waitForModule('jsonschema');
-    return Object.keys(schema.schemas)
-      .sort((a, b) => a.localeCompare(b))
-      .reduce((schemas, s) => Object.assign(schemas, { [s]: schema.schemas[s].raw }), {});
-  }
-  generateList() {
-    return Object.entries(this.schemas).reduce((output, [dep, schema]) => {
-      return `${output}<h3 id="${dep.toLowerCase()}" class="dep">${dep}</h3>
-      
-      ${this.schemaToMd(schema)}
-      
-      `;
-    }, '');
-  }
-  schemaToMd(schema) {
-    let output = '';
-    if(schema.description) {
-      output += `<div class="desc">${schema.description}</div>\n\n`;
-    }
-    let s;
-    if(schema.properties) {
-      s = schema;
-    } else if(schema.$patch) {
-      s = schema.$patch.with;
-      const ref = schema.$patch.source.$ref;
-      output += `<div class="extension">Patches <a href="#/schemas-reference?id=${ref}">${ref}</a></div>`;
-    } else if(schema.$merge) {
-      s = schema.$merge.with;
-      const ref = schema.$merge?.source?.$ref;
-      output += `<div class="extension">${ref ? `Merges with <a href="#/schemas-reference?id=${ref}">${ref}</a>` : 'This is a merge schema'}</div>\n\n`;
-    }
-    const { properties, required } = s;
-
-    if(!properties) {
-      return;
-    }
-    if(required) {
-      output += `<div class="required">Fields in bold are required.</div>\n\n`;
-    }
-    const table = `<tr><th>Attribute</th><th>Type</th><th>Default</th><th>Description</th></tr>${this.tableRowsFromProps(properties, required)}`;
-    return `${output}<table class="schema">${table}</table>`;
-  }
-  tableRowsFromProps(properties, required = [], parent) {
-    return Object.entries(properties).reduce((output, [attr, config]) => {
-      const attrKey = (parent ? parent + '.' : '') + attr;
-      output +=  `<tr class="${config.default === undefined && required && required.includes(attr) ? 'required' : ''}">\n`;
-      output += `<td>${attrKey}</td>\n`;
-      output += `<td>${config.type}</td>\n`;
-      output += `<td>${config.default !== undefined ? this.defaultToMd(config.default) : ''}</td>\n`;
-      output += `<td>${config.description || ' '}</td>\n`;
-      output +=  `</tr>\n`;
-      if(config.properties) output += this.tableRowsFromProps(config.properties, config.required, attrKey);
-      return output;
-    }, '');
-  }
-  /**
-   * Returns a string formatted nicely for markdown
-   */
-  defaultToMd(val) {
-    return `<pre>${JSON.stringify(val)}</pre>`;
-  }
-}
+export default class SchemasReference {
+  constructor(app, config, dir, utils) {
+    this.app = app;
+    this.utils = utils;
+  }
+  async run() {
+    this.schemas = await this.loadSchemas();
+    this.manualFile = 'schemas-reference.md';
+    this.contents = Object.keys(this.schemas);
+    this.replace = { 'LIST': this.generateList() };
+  }
+  async loadSchemas() {
+    const schema = await this.app.waitForModule('jsonschema');
+    return Object.keys(schema.schemas)
+      .sort((a, b) => a.localeCompare(b))
+      .reduce((schemas, s) => Object.assign(schemas, { [s]: schema.schemas[s].raw }), {});
+  }
+  generateList() {
+    return Object.entries(this.schemas).reduce((output, [dep, schema]) => {
+      return `${output}<h3 id="${dep.toLowerCase()}" class="dep">${dep}</h3>
+      
+      ${this.schemaToMd(schema)}
+      
+      `;
+    }, '');
+  }
+  schemaToMd(schema) {
+    let output = '';
+    if(schema.description) {
+      output += `<div class="desc">${schema.description}</div>\n\n`;
+    }
+    let s;
+    if(schema.properties) {
+      s = schema;
+    } else if(schema.$patch) {
+      s = schema.$patch.with;
+      const ref = schema.$patch.source.$ref;
+      output += `<div class="extension">Patches <a href="#/schemas-reference?id=${ref}">${ref}</a></div>`;
+    } else if(schema.$merge) {
+      s = schema.$merge.with;
+      const ref = schema.$merge?.source?.$ref;
+      output += `<div class="extension">${ref ? `Merges with <a href="#/schemas-reference?id=${ref}">${ref}</a>` : 'This is a merge schema'}</div>\n\n`;
+    }
+    const { properties, required } = s;
+
+    if(!properties) {
+      return;
+    }
+    if(required) {
+      output += `<div class="required">Fields in bold are required.</div>\n\n`;
+    }
+    const table = `<tr><th>Attribute</th><th>Type</th><th>Default</th><th>Description</th></tr>${this.tableRowsFromProps(properties, required)}`;
+    return `${output}<table class="schema">${table}</table>`;
+  }
+  tableRowsFromProps(properties, required = [], parent) {
+    return Object.entries(properties).reduce((output, [attr, config]) => {
+      const attrKey = (parent ? parent + '.' : '') + attr;
+      output +=  `<tr class="${config.default === undefined && required && required.includes(attr) ? 'required' : ''}">\n`;
+      output += `<td>${attrKey}</td>\n`;
+      output += `<td>${config.type}</td>\n`;
+      output += `<td>${config.default !== undefined ? this.defaultToMd(config.default) : ''}</td>\n`;
+      output += `<td>${config.description || ' '}</td>\n`;
+      output +=  `</tr>\n`;
+      if(config.properties) output += this.tableRowsFromProps(config.properties, config.required, attrKey);
+      return output;
+    }, '');
+  }
+  /**
+   * Returns a string formatted nicely for markdown
+   */
+  defaultToMd(val) {
+    return `<pre>${JSON.stringify(val)}</pre>`;
+  }
+}

package/docs/plugins/schemas-reference.md

@@ -1,7 +1,7 @@
-# Schemas reference
-
-This page documents all schemas defined in the authoring tool core bundle. Where relevant, any schema inheritance is noted, along with which fields are required.
-
-{{{TABLE_OF_CONTENTS}}}
-
+# Schemas reference
+
+This page documents all schemas defined in the authoring tool core bundle. Where relevant, any schema inheritance is noted, along with which fields are required.
+
+{{{TABLE_OF_CONTENTS}}}
+
 {{{LIST}}}

package/docs/schema-examples.md

@@ -1,144 +1,144 @@
-# Schema examples
-
-This page presents some example schema definitions (along with their UI representation) which may be useful in defining your own schemas.
-
-## Quick navigation
-- [String](#string)
-- [String with text area](#string-with-text-area)
-- [Number](#number)
-- [Boolean with checkbox](#boolean-with-checkbox)
-- [Image](#image)
-- [Select](#select)
-- [Object](#object)
-- [Array](#array)
-
-## String 
-
-> Simple string values do not need custom `_backboneForms` configuration.
-
-```
-"title": {
-  "type": "string",
-  "title": "Title",
-  "default": "Default title",
-  "_adapt": {
-    "translatable": true
-  }
-}
-```
-
-<img width="815" alt="Screenshot 2023-01-16 at 17 06 30" src="https://user-images.githubusercontent.com/11569678/212891159-e73fbe91-0169-429e-86c7-3f8231617b3b.png">
-
-## String with text area
-
-```
-"body": {
-  "type": "string",
-  "title": "Body",
-  "default": "",
-  "_adapt": {
-    "translatable": true
-  },
-  "_backboneForms": "TextArea"
-}
-```
-
-<img width="820" alt="Screenshot 2023-01-16 at 17 07 11" src="https://user-images.githubusercontent.com/11569678/212891179-f7477a54-3be5-4c39-aa60-7df67d86b7d2.png">
-
-## Number
-
-> Number values do not need custom `_backboneForms` configuration.
-
-```
-"_left": {
-  "type": "number",
-  "title": "Pin horizontal position (%)",
-  "description": "",
-  "default": 0
-}
-```
-
-<img width="484" alt="Screenshot 2023-01-16 at 17 10 50" src="https://user-images.githubusercontent.com/11569678/212891200-f9968fe2-8882-4248-8bb2-d6b2f8151e56.png">
-
-## Boolean with checkbox
-
-> Boolean values do not need custom `_backboneForms` configuration.
-
-```
-"_isMobileTextBelowImage": {
-  "type": "boolean",
-  "title": "Move text area below image on mobile",
-  "description": "If enabled, on mobile, the text area drops below the image instead of being behind the strapline button",
-  "default": false
-}
-```
-
-<img width="336" alt="Screenshot 2023-01-16 at 17 29 09" src="https://user-images.githubusercontent.com/11569678/212891377-4c3e130d-5f2a-4de5-b1e2-b1747ed2da0e.png">
-
-## Image
-
-In addition to the `type`, an asset sub-schema can define the type of the asset using the `media` property (see [this page](/schemas-introduction#custom-backbone-forms-properties) for more information).
-
-```
-"src": {
-  "type": "string",
-  "isObjectId": true,
-  "title": "Source",
-  "description": "This is the image that appears behind the pins",
-  "_backboneForms": {
-    "type": "Asset",
-    "media": "image"
-  }
-}
-```
-
-<img width="331" alt="Screenshot 2023-01-16 at 17 29 41" src="https://user-images.githubusercontent.com/11569678/212891422-c240c248-1bfd-4c2d-af63-a01aa281ba45.png">
-
-## Select
-
-```
-"_setCompletionOn": {
-  "type": "string",
-  "title": "Completion criteria",
-  "description": "Whether completion is based on the learner having viewed all the narrative items - or just having viewed the component",
-  "default": "allItems",
-  "enum": [
-    "inview",
-    "allItems"
-  ],
-  "_backboneForms": "Select"
-}
-```
-
-<img width="178" alt="Screenshot 2023-01-16 at 17 31 00" src="https://user-images.githubusercontent.com/11569678/212891453-5c482ea5-ef4f-425f-9756-cdb5b71d7e69.png">
-
-## Object
-
-```
-"_graphic": {
-  "type": "object",
-  "title": "Graphic",
-  "default": {},
-  "properties": {
-    ...omitted for brevity
-  }
-}
-```
-
-<img width="485" alt="Screenshot 2023-01-16 at 17 33 08" src="https://user-images.githubusercontent.com/11569678/212891476-fab8198d-2dca-4ce5-af0b-4f07729780f4.png">
-
-## Array
-
-The items value is its own schema, and can take any of the standard types.
-
-```
-"_items": {
-  "type": "array",
-  "title": "Items",
-  "items": {
-    ...
-  }
-}
-```
-
+# Schema examples
+
+This page presents some example schema definitions (along with their UI representation) which may be useful in defining your own schemas.
+
+## Quick navigation
+- [String](#string)
+- [String with text area](#string-with-text-area)
+- [Number](#number)
+- [Boolean with checkbox](#boolean-with-checkbox)
+- [Image](#image)
+- [Select](#select)
+- [Object](#object)
+- [Array](#array)
+
+## String 
+
+> Simple string values do not need custom `_backboneForms` configuration.
+
+```
+"title": {
+  "type": "string",
+  "title": "Title",
+  "default": "Default title",
+  "_adapt": {
+    "translatable": true
+  }
+}
+```
+
+<img width="815" alt="Screenshot 2023-01-16 at 17 06 30" src="https://user-images.githubusercontent.com/11569678/212891159-e73fbe91-0169-429e-86c7-3f8231617b3b.png">
+
+## String with text area
+
+```
+"body": {
+  "type": "string",
+  "title": "Body",
+  "default": "",
+  "_adapt": {
+    "translatable": true
+  },
+  "_backboneForms": "TextArea"
+}
+```
+
+<img width="820" alt="Screenshot 2023-01-16 at 17 07 11" src="https://user-images.githubusercontent.com/11569678/212891179-f7477a54-3be5-4c39-aa60-7df67d86b7d2.png">
+
+## Number
+
+> Number values do not need custom `_backboneForms` configuration.
+
+```
+"_left": {
+  "type": "number",
+  "title": "Pin horizontal position (%)",
+  "description": "",
+  "default": 0
+}
+```
+
+<img width="484" alt="Screenshot 2023-01-16 at 17 10 50" src="https://user-images.githubusercontent.com/11569678/212891200-f9968fe2-8882-4248-8bb2-d6b2f8151e56.png">
+
+## Boolean with checkbox
+
+> Boolean values do not need custom `_backboneForms` configuration.
+
+```
+"_isMobileTextBelowImage": {
+  "type": "boolean",
+  "title": "Move text area below image on mobile",
+  "description": "If enabled, on mobile, the text area drops below the image instead of being behind the strapline button",
+  "default": false
+}
+```
+
+<img width="336" alt="Screenshot 2023-01-16 at 17 29 09" src="https://user-images.githubusercontent.com/11569678/212891377-4c3e130d-5f2a-4de5-b1e2-b1747ed2da0e.png">
+
+## Image
+
+In addition to the `type`, an asset sub-schema can define the type of the asset using the `media` property (see [this page](/schemas-introduction#custom-backbone-forms-properties) for more information).
+
+```
+"src": {
+  "type": "string",
+  "isObjectId": true,
+  "title": "Source",
+  "description": "This is the image that appears behind the pins",
+  "_backboneForms": {
+    "type": "Asset",
+    "media": "image"
+  }
+}
+```
+
+<img width="331" alt="Screenshot 2023-01-16 at 17 29 41" src="https://user-images.githubusercontent.com/11569678/212891422-c240c248-1bfd-4c2d-af63-a01aa281ba45.png">
+
+## Select
+
+```
+"_setCompletionOn": {
+  "type": "string",
+  "title": "Completion criteria",
+  "description": "Whether completion is based on the learner having viewed all the narrative items - or just having viewed the component",
+  "default": "allItems",
+  "enum": [
+    "inview",
+    "allItems"
+  ],
+  "_backboneForms": "Select"
+}
+```
+
+<img width="178" alt="Screenshot 2023-01-16 at 17 31 00" src="https://user-images.githubusercontent.com/11569678/212891453-5c482ea5-ef4f-425f-9756-cdb5b71d7e69.png">
+
+## Object
+
+```
+"_graphic": {
+  "type": "object",
+  "title": "Graphic",
+  "default": {},
+  "properties": {
+    ...omitted for brevity
+  }
+}
+```
+
+<img width="485" alt="Screenshot 2023-01-16 at 17 33 08" src="https://user-images.githubusercontent.com/11569678/212891476-fab8198d-2dca-4ce5-af0b-4f07729780f4.png">
+
+## Array
+
+The items value is its own schema, and can take any of the standard types.
+
+```
+"_items": {
+  "type": "array",
+  "title": "Items",
+  "items": {
+    ...
+  }
+}
+```
+
 <img width="79" alt="Screenshot 2023-01-16 at 17 33 43" src="https://user-images.githubusercontent.com/11569678/212891491-b6102f17-7631-4ef3-b3cc-1c0dadfd3522.png">

package/docs/schemas-introduction.md

@@ -1,78 +1,78 @@
-# Introduction to schemas
-
-The Adapt authoring tool uses the JSON Schema specification (draft 2020-12) to define its data schemas. This page will give you a brief explanation of why we use JSON schema.
-
-## What is a schema?
-
-At its most basic level, a schema is a 'blueprint' which is applied to information coming into the application.
-
-As with architectural blueprints, a database schema defines how data should be structured and named, as well as other expectations such as the specific 'type' of the data (e.g. strings, numbers) as well as other restrictions (e.g. a fixed length for strings).
- 
-## Why use a schema?
-
-Schemas are **MASSIVELY** useful because they set the expectations for data moving into and out of an application. This benefits third-parties because it makes it easier to design interactions with the application, and it benefits the application itself because it can assume that data entering from external sources is in an expected and valid format.
-
-> **Note**: schemas only become useful when a 'validation' process is used, which compares data to the schema which defines that data. Without validation, we have no idea whether the data is safe to use or not.
-
-## Why JSON Schemas?
-_**TLDR;** JSON just 'works' with Javascript._
-
-The JSON Schema specification is a schema spec based on Javascript Object Notation (JSON) and was designed specifically for annotating and validating JSON documents, which are the standard for data representation in Javascript code (and therefore Node.js). We also currently use MongoDB as our database which uses JSON-like documents.
-
-Additionally, the JSON Schema specification has matured to a point where it is incredibly well supported by a host of third-party libraries from data validators to UI form renderers.
-
-## Defining a schema
-
-When defining a schema, you need to think about the kind of data you need, and how that data is best structured to make it easy to work with.
-
-### Data types
-
-JSON uses the following types:
-- **object**: `{ "a": 1, "b": 2 }`
-- **array**: `[1,2,3]`
-- **number**: `369`
-- **string**: `"Hello world"`
-- **boolean**: `true`/`false`
-- **null**: `null`
-
-Combined, these types allow a huge amount of flexibility in the way that you want to define your data.
-
-e.g.
-```
-{
-  "$anchor": "example-schema",
-  "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "type": "object",
-  "required": ["myRequiredAttribute"],
-  "properties": {
-    "myRequiredAttribute": {
-      "type": "string",
-    },
-    "aStringAttribute": {
-      "type": "number",
-      "default": 12345
-    },
-    "aStringAttributeWithRestrictedValues": {
-      "type": "string",
-      "default": "false",
-      "enum": ["false", "soft", "hard"],
-    },
-    "nestedObjectAttribute": {
-      "type": "object",
-      "default": {},
-      "properties": {
-        "nestedProperty": {
-          "type": "boolean",
-          "default": true
-        }
-      }
-    }
-  }
-}
-```
-
-> For more in-depth information on JSON schemas, the [Understanding JSON Schema](https://json-schema.org/understanding-json-schema/) ebook is a great place to start.
-
-## Next steps
-
+# Introduction to schemas
+
+The Adapt authoring tool uses the JSON Schema specification (draft 2020-12) to define its data schemas. This page will give you a brief explanation of why we use JSON schema.
+
+## What is a schema?
+
+At its most basic level, a schema is a 'blueprint' which is applied to information coming into the application.
+
+As with architectural blueprints, a database schema defines how data should be structured and named, as well as other expectations such as the specific 'type' of the data (e.g. strings, numbers) as well as other restrictions (e.g. a fixed length for strings).
+ 
+## Why use a schema?
+
+Schemas are **MASSIVELY** useful because they set the expectations for data moving into and out of an application. This benefits third-parties because it makes it easier to design interactions with the application, and it benefits the application itself because it can assume that data entering from external sources is in an expected and valid format.
+
+> **Note**: schemas only become useful when a 'validation' process is used, which compares data to the schema which defines that data. Without validation, we have no idea whether the data is safe to use or not.
+
+## Why JSON Schemas?
+_**TLDR;** JSON just 'works' with Javascript._
+
+The JSON Schema specification is a schema spec based on Javascript Object Notation (JSON) and was designed specifically for annotating and validating JSON documents, which are the standard for data representation in Javascript code (and therefore Node.js). We also currently use MongoDB as our database which uses JSON-like documents.
+
+Additionally, the JSON Schema specification has matured to a point where it is incredibly well supported by a host of third-party libraries from data validators to UI form renderers.
+
+## Defining a schema
+
+When defining a schema, you need to think about the kind of data you need, and how that data is best structured to make it easy to work with.
+
+### Data types
+
+JSON uses the following types:
+- **object**: `{ "a": 1, "b": 2 }`
+- **array**: `[1,2,3]`
+- **number**: `369`
+- **string**: `"Hello world"`
+- **boolean**: `true`/`false`
+- **null**: `null`
+
+Combined, these types allow a huge amount of flexibility in the way that you want to define your data.
+
+e.g.
+```
+{
+  "$anchor": "example-schema",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "required": ["myRequiredAttribute"],
+  "properties": {
+    "myRequiredAttribute": {
+      "type": "string",
+    },
+    "aStringAttribute": {
+      "type": "number",
+      "default": 12345
+    },
+    "aStringAttributeWithRestrictedValues": {
+      "type": "string",
+      "default": "false",
+      "enum": ["false", "soft", "hard"],
+    },
+    "nestedObjectAttribute": {
+      "type": "object",
+      "default": {},
+      "properties": {
+        "nestedProperty": {
+          "type": "boolean",
+          "default": true
+        }
+      }
+    }
+  }
+}
+```
+
+> For more in-depth information on JSON schemas, the [Understanding JSON Schema](https://json-schema.org/understanding-json-schema/) ebook is a great place to start.
+
+## Next steps
+
 When you're ready to start writing your own schemas, check out [this page](/writing-a-schema).