adapt-authoring-jsonschema 0.0.1

package/.eslintignore

@@ -0,0 +1 @@
+node_modules

package/.eslintrc

@@ -0,0 +1,14 @@
+{
+  "env": {
+      "browser": false,
+      "node": true,
+      "commonjs": false,
+      "es2020": true
+  },
+  "extends": [
+      "standard"
+  ],
+  "parserOptions": {
+      "ecmaVersion": 2020
+  }
+}

package/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,55 @@
+name: Bug Report
+description: File a bug report
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out this bug report!
+  - type: textarea
+    id: description
+    attributes:
+      label: What happened?
+      description: Please describe the issue
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected behaviour
+      description: Tell us what should have happened
+  - type: textarea
+    id: repro-steps
+    attributes:
+      label: Steps to reproduce
+      description: Tell us how to reproduce the issue
+    validations:
+      required: true
+  - type: input
+    id: aat-version
+    attributes:
+      label: Authoring tool version
+      description: What version of the Adapt authoring tool are you running?
+    validations:
+      required: true
+  - type: input
+    id: fw-version
+    attributes:
+      label: Framework version
+      description: What version of the Adapt framework are you running?
+  - type: dropdown
+    id: browsers
+    attributes:
+      label: What browsers are you seeing the problem on?
+      multiple: true
+      options:
+        - Firefox
+        - Chrome
+        - Safari
+        - Microsoft Edge
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
+      render: sh

package/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1 @@
+blank_issues_enabled: false

package/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,22 @@
+name: Feature request
+description: Request a new feature
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to request a new feature in the Adapt authoring tool! The Adapt team will consider all new feature requests, but unfortunately cannot commit to every one.
+  - type: textarea
+    id: description
+    attributes:
+      label: Feature description
+      description: Please describe your feature request
+    validations:
+      required: true
+  - type: checkboxes
+    id: contribute
+    attributes:
+      label: Can you work on this feature?
+      description: If you are able to commit your own time to work on this feature, it will greatly increase the liklihood of it being implemented by the core dev team. Otherwise, it will be triaged and prioritised alongside the core team's current priorities.
+      options:
+        - label: I can contribute

package/.github/dependabot.yml

@@ -0,0 +1,11 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
+
+version: 2
+updates:
+  - package-ecosystem: "npm" # See documentation for possible values
+    directory: "/" # Location of package manifests
+    schedule:
+      interval: "weekly"

package/.github/pull_request_template.md

@@ -0,0 +1,25 @@
+[//]: # (Please title your PR according to eslint commit conventions)
+[//]: # (See https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint#eslint-convention for details)
+
+[//]: # (Add a link to the original issue)
+
+[//]: # (Delete as appropriate)
+### Fix
+* A sentence describing each fix
+
+### Update
+* A sentence describing each udpate
+
+### New
+* A sentence describing each new feature
+
+### Breaking
+* A sentence describing each breaking change
+
+[//]: # (List appropriate steps for testing if needed)
+### Testing
+1. Steps for testing
+
+[//]: # (Mention any other dependencies)
+
+

package/.github/workflows/labelled_prs.yml

@@ -0,0 +1,16 @@
+name: Add labelled PRs to project
+
+on:
+  pull_request:
+    types: [ labeled ]
+
+jobs:
+  add-to-project:
+    if: ${{ github.event.label.name == 'dependencies' }}
+    name: Add to main project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/add-to-project@v0.1.0
+        with:
+          project-url: https://github.com/orgs/adapt-security/projects/5
+          github-token: ${{ secrets.PROJECTS_SECRET }}

package/.github/workflows/new.yml

@@ -0,0 +1,19 @@
+name: Add to main project
+
+on:
+  issues:
+    types:
+      - opened
+  pull_request:
+    types:
+      - opened
+
+jobs:
+  add-to-project:
+    name: Add to main project
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/add-to-project@v0.1.0
+        with:
+          project-url: https://github.com/orgs/adapt-security/projects/5
+          github-token: ${{ secrets.PROJECTS_SECRET }}

package/adapt-authoring.json

@@ -0,0 +1,13 @@
+{
+  "essentialType": "schema",
+  "documentation": {
+    "enable": true,
+    "manualPlugins": ["docs/plugins/schemas-reference.js"],
+    "manualPages": {
+      "schema-examples.md": "reference",
+      "schemas-introduction.md": "basics",
+      "schemas-reference.md": "reference",
+      "writing-a-schema.md": "basics"
+    }
+  }
+}

package/bin/check.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * Checks for duplicate schema properties
+*/
+import { App } from 'adapt-authoring-core'
+
+process.env.NODE_ENV = 'production'
+process.env.ADAPT_AUTHORING_LOGGER__mute = 'true'
+
+let app
+
+async function check () {
+  console.log('Checking for duplicate schema definitions.\n')
+  app = await App.instance.onReady()
+  const schema = await app.waitForModule('jsonschema')
+
+  await Promise.allSettled(Object.keys(schema.schemaPaths).map(async s => {
+    const usedKeys = {}
+    const hierarchy = await schema.loadSchemaHierarchy(s)
+    await Promise.all(hierarchy.map(s => checkSchema(s, usedKeys)))
+    const duplicates = Object.entries(usedKeys).filter(([key, uses]) => uses.length > 1)
+
+    if (duplicates.length) {
+      console.log(`Schema '${s}' contains duplicate definitions for the following properties:`)
+      duplicates.forEach(([prop, schemas]) => console.log(` - ${prop}: ${schemas}`))
+      console.log('')
+      process.exitCode = 1
+    }
+  }))
+  if (process.exitCode !== 1) console.log('No duplicates found.')
+  process.exit()
+}
+
+async function checkSchema (schema, usedKeys) {
+  const props = schema.properties ?? schema?.$patch?.with?.properties ?? schema?.$merge?.with?.properties
+  Object.keys(props).forEach(p => {
+    if (p === '_globals') return
+    if (!usedKeys[p]) usedKeys[p] = []
+    usedKeys[p].push(schema.$anchor)
+  })
+}
+
+check()

package/conf/config.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "properties": {
+    "enableCache": {
+      "description": "Whether schema data should be cached",
+      "type": "boolean",
+      "default": true
+    },
+    "formatOverrides": {
+      "description": "Custom RegExp overrides for Ajv string formats",
+      "type": "object",
+      "default": {}
+    },
+    "xssWhitelist": {
+      "description": "Attributes which should be whitelisted when run through the XSS sanitiser.",
+      "type": "object",
+      "default": {}
+    },
+    "xssWhitelistOverride": {
+      "description": "If set to false, the xssWhitelist value will EXTEND the default XSS whitelist. If set to true, it will REPLACE it.",
+      "type": "boolean",
+      "default": false
+    }
+  }
+}

package/docs/plugins/schemas-reference.js

@@ -0,0 +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>`;
+  }
+}

package/docs/plugins/schemas-reference.md

@@ -0,0 +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}}}
+
+{{{LIST}}}

package/docs/schema-examples.md

@@ -0,0 +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": {
+    ...
+  }
+}
+```
+
+<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

@@ -0,0 +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
+
+When you're ready to start writing your own schemas, check out [this page](/writing-a-schema).