# Essay (H5P.Essay)

The learner writes a text, scored by the keywords it contains, with feedback per keyword and a sample answer to compare.

- Each item of `keywords` is a word or phrase to look for, with its `alternatives`, and `options` for its points and feedback. `*` matches any characters; `/…/` is a regular expression.
- A sample solution: `solution.sample`, shown after the learner submits.
- `behaviour.minimumLength` and `behaviour.maximumLength` bound the answer in characters.
- Keyword scoring cannot judge an argument: say so to the user, and keep the essay's weight low where it counts.

## Example

```json
{
  "type": "H5P.Essay",
  "params": {
    "taskDescription": "In two or three sentences, explain how a river reaches the sea.",
    "keywords": [
      { "keyword": "downhill", "alternatives": ["down hill", "gravity"], "options": { "points": 1, "feedbackMissed": "Say what makes the water move." } },
      { "keyword": "sea", "options": { "points": 1, "feedbackMissed": "Say where the river ends." } }
    ],
    "solution": { "sample": "Water flows downhill under gravity, gathering into streams and then a river, which ends in the sea." }
  }
}
```

<!-- Generated by `h5p-author schema --markdown` from the pinned pack. Do not edit by hand. -->

## Fields of H5P.Essay 1.5

The example is `type` and `params` alone, and `params` holds the fields below. A source also names its own `title`, `language`, `license` and `authors`, all four required: the build refuses a source that leaves out any of them. The author's name and the licence are the user's: ask for what they have not given. For a name they skip, write the one you know them by, or "Unknown"; for a licence they skip, `U`.

- `media` group — Media
  - `type` sub-content: H5P.Image | H5P.Video | H5P.Audio — Type: Optional media to display above the question.
  - `disableImageZooming` boolean = false; only when type is "H5P.Image 1.1" — Disable image zooming
- `taskDescription` html: strong em u a ul ol h2 h3 hr pre code, required — Task description: Describe your task here. The task description will appear above text input area.
- `placeholderText` text — Help text: This text should help the user to get started.
- `solution` group — Sample solution
  - `introduction` html: strong em u a ul ol hr code — Introduction: You can optionally leave the students some explanations about your example. The explanation will only show up if you add an example, too.
  - `sample` html: strong a — Sample solution text: The student will see a "Show solution" button after submitting if you provide some text here.
- `keywords` list 1+ of, required — Keywords
  - `keyword` text, required — Keyword: Keyword or phrase to look for. Use an asterisk '*' as a wildcard for one or more characters. Use a slash '/' at the beginning and the end to use a regular expression.
  - `alternatives` list of text — Variations: Add optional variations for this keyword. Example: For a 'city' add alternatives 'town', 'municipality' etc. Points will be awarded if the user includes any of the specified alternatives.
  - `options` group — Points, Options and Feedback
    - `points` whole number 0– = 1 — Points: Points that the user will get if he/she includes this keyword or its alternatives in the answer.
    - `occurrences` whole number 1– = 1 — Occurrences: Define how many occurrences of the keyword or its variations should be awarded with points.
    - `caseSensitive` boolean = true — Case sensitive
    - `forgiveMistakes` boolean — Forgive minor mistakes
    - `feedbackIncluded` text — Feedback if keyword included: This feedback will be displayed if the user includes this keyword or its alternatives in the answer.
    - `feedbackMissed` text — Feedback if keyword missing: This feedback will be displayed if the user doesn’t include this keyword or its alternatives in the answer.
    - `feedbackIncludedWord` one of "keyword" | "alternative" | "answer" | "none" = "keyword" — Feedback word shown if keyword included: This option allows you to specify which word should be shown in front of your feedback if a keyword was found in the text.
    - `feedbackMissedWord` one of "keyword" | "none" = "none" — Feedback word shown if keyword missing: This option allows you to specify which word should be shown in front of your feedback if a keyword was not found in the text.
- `overallFeedback` list 1+ of — Overall Feedback: Click the "Add range" button to add as many ranges as you need. Example: 0-20% Bad score, 21-91% Average Score, 91-100% Great Score!
  - `from` whole number 0–100 = 0 — Score Range
  - `to` whole number 0–100 = 100
  - `feedback` text — Feedback for defined score range
- `behaviour` group — Behavioural settings
  - `minimumLength` whole number 0– — Minimum number of characters: Specify the minimum number of characters that the user must enter.
  - `maximumLength` whole number 0– — Maximum number of characters: Specify the maximum number of characters that the user can enter.
  - `inputFieldSize` one of "1" | "3" | "10" = "10" — Input field size: The size of the input field in amount of lines it will cover
  - `enableRetry` boolean = true — Enable "Retry"
  - `ignoreScoring` boolean = false — Ignore scoring
  - `pointsHost` number 0– = 1; only when ignoreScoring is true — Points in host environment: Used to award points in host environment merely for answering (not shown to learner).
  - `percentagePassing` number 0–100; only when ignoreScoring is false — Passing percentage: Percentage that's necessary for passing
  - `percentageMastering` number 0–100; only when ignoreScoring is false — Mastering percentage: Percentage that's necessary for mastering. Setting the mastering percentage below 100 % will lower the maximum possible score accordingly. It's intended to give some leeway to…
  - `overrideCaseSensitive` one of "on" | "off" — Override case sensitive: This option determines if the "Case sensitive" option will be activated for all keywords.
  - `overrideForgiveMistakes` one of "on" | "off" — Override forgive mistakes: This option determines if the "Forgive mistakes" option will be activated for all keywords.
  - `linebreakReplacement` one of " " | "\n" = " " — Replacement for line breaks: By default, line breaks will be replaced with a space character. If you want to check for line breaks, e.g. in regular expressions, you can set a different replacement …

14 interface texts are left out: they come from the libraries' translations. `h5p-author schema H5P.Essay --all` lists them, for a source to set one.

<!-- End of the generated section. -->