Updated Q&A template schema

[ahm8076]

Hi,

This is an update to issue #1003, which describes the proposed q&a template schema. This version reflects what was implemented, rather than what was proposed. This could definitely benefit from screenshots if it is going to be used on the contribute page.

Current Q&A schema

• key - A string representing the unique identifier for the field.

• label - A string which contains the title of the field.

• summary - A string shown in large font that contains the question the curator should answer. This question should be around 75 characters long.

• instructions - A string expounding on the title question that could contain additional questions for the curator to consider.

• howToFind - A string that guides the curator in the right direction to find the answer to the question.

• examples - A list of one-line strings that provide examples to the curator of what they could be looking for.

• defaultValue - The default value for the field. If set to an integer and type is set as repeater, this represents the number of starting fields the repeater will generate.

• type - A field which defines the type of the answer. Must be one of the types listed below under answer types.

• parentField - A string which specifies the parent field. Used for follow-up questions.

• acceptedValues - Used in child questions in tandem with comparisonType. A list of values which determines what will cause the field to be displayed.

• comparisonType - Used in child questions in tandem with acceptedValues. Can be "IN" or "NOT IN". If "IN", the field is not displayed until the parent field contains something listed in acceptedValues. If "NOT IN", the field is not displayed until the parent field contains nothing in the acceptedValues list.

  The content of acceptedValues and comparisonType currently follow two patterns. This should hopefully make it easier to understand what is happening when using them.

  • Pattern 1: acceptedValues = 1, comparisonType = "IN"
    This is used when checking a checkbox displays another field. If the checkbox value is equal to 1, which is set under the Value field (see below), and 1 is "IN" the acceptedValues list, the child field will be displayed (in this case, the checkbox is considered the parent field).

  • Pattern 2: acceptedValues = "", comparisonType = "NOT IN"
    This is used when typing any text in a field causes a new field to display. If "" is "NOT IN" the parent field (alternatively read as 'if something is in the parent field') the child field will be displayed.

• validationType - A string representing the type which the data the user entered will be validated against. Cannot be used with 'repeater' answer types, as they use a separate method for validation. Can be the following types:

  • input, textarea, string - Will check if the entered value is a string.
  • date - Will check if the entered value is in the ISO date format.
  • boolean - Will check if the entered value is a boolean.
  • number - Will check if the entered value is a number.
  • url - Will check if the entered value is a valid URL.
  • cve - Will check if the entered value is in the CVE format (CVE-YYYY-####(#)).
  • required - A boolean which determines if the answer is required to be filled.

answer types - The possible types of answers and what they expect the curator to provide:

• cve-selector - A dropdown box containing a list of every CVE number in the VHP database.

• cwe-selector - A dropdown box containing every CWE.

• textarea - A long line of text. There is no minimum or maximum length.

• input - A short line of text. There is no minimum or maximum length.

• date - A timestamp which must be in MM/DD/YYYY format to be considered valid.

• repeater - Will generate new fields which specify this field as their parent field every time the 'Add Entry' button is pressed, up to the number provided in entryLimit. If no limit is specified, it will generate infinitely.

  • entryLimit - The number of times the repeater will generate a new field.

• checkbox - Specifies that this field is a checkbox, which requires the Options field below.

  • Options - A list of checkboxes, each with its own starting value and optional note.

    • Value - Always set to 1. Signifies that this checkbox can be used with acceptedValues, if it also includes 1.

    • Label - Label for the checkbox, similar to the labels for the questions.

• content - Signifies that there is no user input needed for the parent question, only for the child questions.