# Sections
- [Sections](#sections)
- [About YAML Format](#about-yaml-format)
- [File extension](#file-extension)
- [Validation Rules](#validation-rules)
- [Exporting](#exporting)
- [Importing, Parsing](#importing-parsing)
- [Examples](#examples)
- [Good Examples](#good-examples)
- [Example 1](#example-1)
- [Bad Examples](#bad-examples)
- [Example 1](#example-1-1)
- [Example 2](#example-2)
- [Example 3](#example-3)
- [Example 4](#example-4)
- [Example 5](#example-5)
- [Example 6](#example-6)
- [Example 7](#example-7)
# About YAML Format
YAML (YAML Ain't Markup Language) is a human friendly data format and serialization standard. Read more about YAML format [here](https://yaml.org/).
# File extension
The conventional file extension for convo files is `*.convo.yml`.
# Validation Rules
You can expect an error to be thrown when trying to export or import `*.convo.yml` files if the following validation rules have not been satisfied. You will receive verbose error information on failure, but for comprehension, the rules are listed below in full.
## Exporting
* The `Tree` must have a root key set
* The `Tree#nodes` must contain at least 1 node.
* **Future ([#10](https://github.com/simbleau/convo/issues/10))** : Links must all reference existing nodes.
* **Future ([#3](https://github.com/simbleau/convo/issues/3))** : All nodes must be reachable; Nodes must be the root element or linked to by a parent.
## Importing, Parsing
* YAML must contain a top-level element called `root` which is a *string*, which specifies the entry point node key.
* YAML must contain a top-level element called `nodes` which is a *hash*, which specifies the map of nodes.
* `nodes` must contain at least 1 node.
* `nodes` is a *hash*.
* Node keys are *strings*.
* Node values are *hashes*.
* Node must contain a `dialogue` key and/or a `links` key.
* If node data contains a `dialogue` :
* node dialogue value is a *string* value.
* If node data contains a `links` :
* node link values are *array elements*.
* node link keys are *strings*.
* node link values are *strings*.
* **Future ([#10](https://github.com/simbleau/convo/issues/10))** : Link keys must all reference existing nodes.
* **Future ([#3](https://github.com/simbleau/convo/issues/3))** : All nodes must be reachable; Nodes must be the root element or linked to by a parent.
# Examples
You can find valid examples in the [dialogue_files](../dialogue_files/) folder.
## Good Examples
### Example 1
```yaml
---
root: start
nodes:
start:
dialogue: "Hello, how are you?"
links:
- end: "I'm rudely in a hurry."
end:
dialogue: "Ok, let's talk some other time."
```
Why is this a **good** example?
The example adheres to [YAML format](#about-yaml-format) and follows [validation rules](#validation-rules).
Namely,
* YAML contains a top-level element called `root` which specifies the entry point called `start`.
* YAML contain a top-level element called `nodes`.
* `nodes` contains at least 1 node (It contains 2).
* All nodes contain a `dialogue` key.
* Orphan nodes do not exist (all links can be visited).
## Bad Examples
### Example 1
```yaml
---
nodes:
root:
dialogue: "It's a bad day."
```
Why is this a **bad** example?
* YAML does not contain a top-level element called `root`.
### Example 2
```yaml
---
root: root
nodes:
start:
dialogue: "It's a bad day."
```
Why is this a **bad** example?
* YAML contains a top-level element called `root` which specifies the entry point to be a node called `root`. This will not work because there is only one node called `start`.
### Example 3
```yaml
---
root: start
nodes:
```
Why is this a **bad** example?
* `nodes` does not contains at least 1 node.
* `start` does not exist.
### Example 4
```yaml
---
root: start
nodes:
start:
links:
- end: "I'm rudely in a hurry."
end:
dialogue: "Ok, let's talk some other time."
```
Why is this a **bad** example?
* `start` does not contain dialogue.
### Example 5
```yaml
---
root: start
nodes:
start:
dialogue: "Hello, how are you?"
end:
dialogue: "Ok, let's talk some other time."
```
Why is this a **bad** example?
* `end` is an orphan node. It is not linked to and therefore not part of the hierarchy.
### Example 6
```yaml
---
root: start
nodes:
fork:
dialogue: "I link to all nodes!"
links:
- start: "I link to start"
- end: "I link to end"
- fork: "I even link to myself!"
start:
dialogue: "Hello, how are you?"
end:
dialogue: "Ok, let's talk some other time."
```
Why is this a **bad** example?
* `end` and `fork` are unreachable nodes because the root node is `start`.
### Example 7
```yaml
---
root: start
nodes:
start:
dialogue: "I am the start node"
links:
- start: "I am valid and link to myself"
- not_a_real_key: "I do not link to a valid key"
```
Why is this a **bad** example?
* `not_a_real_key` is not a node that exists, e.g. invalid reference key.