docs: Data structures

docs/contributing.md

@@ -169,6 +169,10 @@ If you want to build something on top of the Apiary Reporter, note that it uses
 - [Apiary Tests API for anonymous test reports][]
 - [Apiary Tests API for authenticated test reports][]
 
+Following data are sent over the wire to Apiary:
+
+- [Apiary Reporter Test Data](data-structures.md#apiary-reporter-test-data)
+
 There is also one environment variable you could find useful:
 
 - `APIARY_API_URL='https://api.apiary.io'` - Allows to override host of the Apiary Tests API.

docs/data-structures.md

@@ -0,0 +1,204 @@
+# Data Structures
+
+Documentation of various data structures in both [Gavel.js][] and Dredd. [MSON notation](https://github.com/apiaryio/mson) is used to describe the data structures.
+
+<a name="transaction">
+## Transaction (object)
+
+Transaction object is passed as a first argument to [hook functions](hooks.md) and is one of the main public interfaces in Dredd.
+
+- name: `./api-description.apib > My API > Greetings > Hello, world! > Retrieve Message > Example 2` (string) - reference to the transaction definition in the original API description document (see also [Dredd Transactions' data structures][])
+- origin (object) - reference to the transaction definition in the original API description document (see also [Dredd Transactions' data structures][])
+  - filename: `./api-description.apib` (string)
+  - apiName: `My Api` (string)
+  - resourceGroupName: `Greetings` (string)
+  - resourceName: `Hello, world!` (string)
+  - actionName: `Retrieve Message` (string)
+  - exampleName: `Example 2` (string)
+- host: `localhost` (string) - server hostname without port number
+- port: `3000` (number) - server port number
+- protocol: `https:` (enum[string]) - server protocol
+  - `https:` (string)
+  - `http:` (string)
+- fullPath: `/message` (string) - expanded [URI Template][] with parameters (if any) used for the HTTP request Dredd performs to the tested server
+- request (object) - the HTTP request Dredd performs to the tested server, taken from the API description
+  - body: `Hello world!\n` (string)
+  - headers (object) - keys are HTTP header names, values are HTTP header contents
+  - uri: `/message` (string) - request URI as it was written in API description
+  - method: `POST` (string)
+- expected (object) - the HTTP response Dredd expects to get from the tested server
+  - statusCode: `200` (string)
+  - headers (object) - keys are HTTP header names, values are HTTP header contents
+  - body (string)
+  - schema (object) - JSON Schema of the response body
+- real (object) - the HTTP response Dredd gets from the tested server (present only in `after` hooks)
+  - statusCode: `200` (string)
+  - headers (object) - keys are HTTP header names, values are HTTP header contents
+  - body (string)
+- skip: `false` (boolean) - can be set to `true` and the transaction will be skipped
+- fail: `false` (enum) - can be set to `true` or string and the transaction will fail
+  - (string) - failure message with details why the transaction failed
+  - (boolean)
+- test ([Transaction Test][]) - test data passed to Dredd's reporters
+- results ([Transaction Results][]) - testing results
+
+<a name="transaction-test">
+## Transaction Test (object)
+
+- start (Date) - start of the test
+- end (Date) - end of the test
+- duration (number) - duration of the test in milliseconds
+- startedAt (number) - unix timestamp, [transaction][].startedAt
+- title (string) - [transaction][].id
+- request (object) - [transaction][].request
+- actual (object) - [transaction][].real
+- expected (object) - [transaction][].expected
+- status (enum) - whether the validation passed or not, defaults to empty string
+  - `pass` (string)
+  - `fail` (string)
+  - `skip` (string)
+- message (string) - concatenated all messages of all [Gavel Errors](#gavel-error) in `results` or Dredd's custom message (e.g. "failed in before hook")
+- results (Dredd's [transaction][].results)
+- valid (boolean)
+- origin (object) - [transaction][].origin
+
+<a name="transaction-results">
+## Transaction Results (object)
+
+This is a slightly retarded cousin of the [Gavel Validation Result](#gavel-validation-result). Why does this have `transaction.results.{something}.results` structure and not `transaction.results.{something}` as it's in the Gavel Validation Result? Answer: It's not intended, it's a mistake, but it's there now.
+
+- general (object) - contains Dredd's custom messages (e.g. "test was skipped"), formatted the same way like those from Gavel
+  - results (array[[Gavel Validator Output][]])
+- statusCode (object)
+  - results (array[[Gavel Validator Output][]])
+- headers (object)
+  - results (array[[Gavel Validator Output][]])
+- body (object)
+  - results (array[[Gavel Validator Output][]])
+- version (object, optional) - this is sometimes not present (correctly filtered out) and sometimes present
+  - results (array) - empty array
+
+<a name="gavel-validation-result">
+## Gavel Validation Result (object)
+
+Can be seen also [here](https://www.relishapp.com/apiary/gavel/docs/javascript/request-async-api#validate).
+
+- statusCode (array[[Gavel Validator Output][]])
+- headers (array[[Gavel Validator Output][]])
+- body (array[[Gavel Validator Output][]])
+- version (string) - version number of the Gavel Validation Result structure
+
+<a name="gavel-validator-output">
+## Gavel Validator Output (object)
+
+Can be seen also [here](https://www.relishapp.com/apiary/gavel/docs/data-validators-and-output-format#validators-output-format).
+
+- results (array[[Gavel Error][]])
+- realType (string) - media type
+- expectedType (string) - media type
+- validator (string) - validator class name
+- rawData (enum) - raw output of the validator, has different structure for every validator and is saved and used in Apiary to render graphical diff by [gavel2html](https://github.com/apiaryio/gavel2html/)
+  - ([JsonSchema Validation Result][])
+  - ([TextDiff Validation Result][])
+
+<a name="jsonschema-validation-result">
+## JsonSchema Validation Result (object)
+
+The validation error is based on format provided by [Amanda][] and is also "documented" [here](https://github.com/apiaryio/Amanda/blob/master/docs/json/objects/error.md). Although for validation of draft4 JSON Schema Gavel uses [tv4][] library, the output then gets reshaped into the structure of Amanda's errors.
+
+This validation result is returned not only when validating against [JSON Schema][], but also when validating against JSON example or when validating HTTP headers.
+
+- length: `0` (number, default) - number of error properties
+- errorMessages (object) - doesn't seem to ever contain anything or be used for anything
+- *0* (object) - validation error details, property is always a string containing a number (0, 1, 2, ...)
+  - property (array[string]) - path to the problematic property in format of [json-pointer's `parse()` output](https://github.com/manuelstofer/json-pointer#parsestr)
+  - propertyValue (mixed) - real value of the problematic property (can be also `undefined` etc.)
+  - attributeName: `enum`, `required` (string) - name of the relevant JSON Schema attribute, which triggered the error
+  - attributeValue (mixed) - value of the relevant JSON Schema attribute, which triggered the error
+  - message (string) - error message (in case of tv4 it contains [JSON Pointer][] to the problematic property and for both Amanda and tv4 it can directly mention property names and/or values)
+  - validator: `enum` (string) - the same as `attributeName`
+  - validatorName: `error`, `enum` (string) - the same as `attributeName`
+  - validatorValue (mixed) - the same as `attributeValue`
+
+<a name="textdiff-validation-result">
+## TextDiff Validation Result (string)
+
+Block of text which looks extremely similar to the standard GNU diff/patch format. Result of the [`patch_toText()` function of the `google-diff-match-patch` library](https://code.google.com/p/google-diff-match-patch/wiki/API).
+
+<a name="gavel-error">
+## Gavel Error (object)
+
+Can also be seen as part of Gavel Validator Output [here](https://www.relishapp.com/apiary/gavel/docs/data-validators-and-output-format#validators-output-format).
+
+- pointer (string) - [JSON Pointer][] path
+- severity (string) - severity of the error
+- message (string) - error message
+
+<a name="apiary-reporter-test-data">
+## Apiary Reporter Test Data (object)
+
+- testRunId (string) - ID of the [test run](#apiary-test-run), recieved from Apiary
+- origin (object) - [test][].origin
+- duration (number) - duration of the test in milliseconds
+- result (string) - [test][].status
+- startedAt (number) - [test][].startedAt
+- resultData (object)
+  - request (object) - [test][].request
+  - realResponse (object) - [test][].actual
+  - expectedResponse (object) - [test][].expected
+  - result ([Transaction Results][]) - [test][].results
+
+## Internal Apiary Data Structures
+
+These are private data structures used in Apiary internally and they are documented incompletely. They're present in this document just to provide better insight on what and how Apiary internally saves. It is closely related to what you can see in documentation for [Apiary Tests API for anonymous test reports][] and [Apiary Tests API for authenticated test reports][].
+
+<a name="apiary-test-run">
+### Apiary Test Run (object)
+
+Also known as `stats` in Dredd's code.
+
+- result
+  - tests: `0` (number, default) - total number of tests
+  - failures: `0` (number, default)
+  - errors: `0` (number, default)
+  - passes: `0` (number, default)
+  - skipped: `0` (number, default)
+  - start: `0` (number, default)
+  - end: `0` (number, default)
+  - duration: `0` (number, default)
+
+<a name="apiary-test-step">
+### Apiary Test Step (object)
+
+- resultData
+  - request (object) - [test][].request
+  - realResponse (object) - [test][].actual
+  - expectedResponse (object) - [test][].expected
+  - result ([Transaction Results][]) - [test][].results
+
+
+[Transaction]: #transaction
+[Transaction Test]: #transaction-test
+[Transaction Results]: #transaction-results
+[Gavel Validation Result]: #gavel-validation-result
+[Gavel Validator Output]: #gavel-validator-output
+[JsonSchema Validation Result]: #jsonschema-validation-result
+[TextDiff Validation Result]: #textdiff-validation-result
+[Gavel Error]: #gavel-error
+[Apiary Reporter Test Data]: #apiary-reporter-test-data
+[Apiary Test Run]: #apiary-test-run-result
+[Apiary Test Step]: #apiary-test-step-resultdata
+
+[transaction]: #transaction
+[test]: #transaction-test
+
+[Amanda]: https://github.com/apiaryio/Amanda
+[tv4]: https://github.com/geraintluff/tv4
+[Gavel.js]: https://github.com/apiaryio/gavel.js
+[URI Template]: https://tools.ietf.org/html/rfc6570
+[JSON Pointer]: https://tools.ietf.org/html/rfc6901
+[JSON Schema]: http://json-schema.org/
+
+[Apiary Tests API for anonymous test reports]: https://github.com/apiaryio/dredd/blob/master/ApiaryReportingApiAnonymous.apib
+[Apiary Tests API for authenticated test reports]: https://github.com/apiaryio/dredd/blob/master/ApiaryReportingApi.apib
+[Dredd Transaction's data structures]: https://github.com/apiaryio/dredd-transactions#data-structures

docs/hooks-go.md

@@ -63,14 +63,14 @@ func main() {
 The `Runner` type has the following callback methods.
 
 1. `BeforeEach`, `BeforeEachValidation`, `AfterEach`
-  - accepts a function as a first argument passing a [Transaction object](hooks.md#transaction-object-structure) as a first argument
+  - accepts a function as a first argument passing a [Transaction object](data-structures.md#transaction) as a first argument
 
 2. `Before`, `BeforeValidation`, `After`
   - accepts [transaction name](hooks.md#getting-transaction-names) as a first argument
-  - accepts a function as a second argument passing a [Transaction object](hooks.md#transaction-object-structure) as a first argument of it
+  - accepts a function as a second argument passing a [Transaction object](data-structures.md#transaction) as a first argument of it
 
 3. `BeforeAll`, `AfterAll`
-  - accepts a function as a first argument passing a Slice of [Transaction objects](hooks.md#transaction-object-structure) as a first argument
+  - accepts a function as a first argument passing a Slice of [Transaction objects](data-structures.md#transaction) as a first argument
 
 Refer to [Dredd execution lifecycle](how-it-works.md#execution-life-cycle) to find when each hook callback is executed.
 

docs/hooks-js-sandbox.md

@@ -50,7 +50,7 @@ In each hook file you can use following functions:
 
 `log(string)`
 
-- A [Transaction Object](hooks.md#transaction-object-structure) is passed as a first argument to the hook function for `before`, `after`, `beforeEach`, `afterEach`, `beforeValidation` and `beforeEachValidation`.
+- A [Transaction Object](data-structures.md#transaction) is passed as a first argument to the hook function for `before`, `after`, `beforeEach`, `afterEach`, `beforeValidation` and `beforeEachValidation`.
 - An array of Transaction Objects is passed to `beforeAll` and `afterAll`.
 - Sandboxed hooks don't have an asynchronous API. Loading and running of each hook happens in it's own isolated, sandboxed context.
 - Hook maximum execution time is 500ms.

docs/hooks-new-language.md

@@ -6,7 +6,7 @@ Dredd comes with concept of hooks language abstraction bridge via simple TCP soc
 
 When you run Dredd with `--language` argument, it runs the command in argument and tries to connect to `http://localhost:61321`. If connection to the hook handling server wasn't successful, it exits with exit code `3`.
 
-Dredd internally registers a function for each [type of hooks](hooks.md#types-of-hooks) and when this function is executed it assigns execution `uuid` to that event, serializes received function parameters (a [Transaction object](hooks.md#transaction-object-structure) or an Array of it), sends it to the TCP socket to be handled (executed) in other language and waits until message with same `uuid` is received. After data reception it assigns received `data` back to the transaction, so other language can interact with transactions same way like [native Node.js hooks](hooks-nodejs.md).
+Dredd internally registers a function for each [type of hooks](hooks.md#types-of-hooks) and when this function is executed it assigns execution `uuid` to that event, serializes received function parameters (a [Transaction object](data-structures.md#transaction) or an Array of it), sends it to the TCP socket to be handled (executed) in other language and waits until message with same `uuid` is received. After data reception it assigns received `data` back to the transaction, so other language can interact with transactions same way like [native Node.js hooks](hooks-nodejs.md).
 
 ## Language agnostic test suite
 

docs/hooks-perl.md

@@ -23,14 +23,14 @@ $ dredd apiary.apib http://localhost:3000 --language dredd-hooks-perl --hookfile
 Module `Dredd::Hooks::Methods` imports following decorators:
 
 1. `beforeEach`, `beforeEachValidation`, `afterEach`
-  - wraps a function and passes [Transaction object](hooks.md#transaction-object-structure) as a first argument to it
+  - wraps a function and passes [Transaction object](data-structures.md#transaction) as a first argument to it
 
 2. `before`, `beforeValidation`, `after`
   - accepts [transaction name](hooks.md#getting-transaction-names) as a first argument
-  - wraps a function and sends a [Transaction object](hooks.md#transaction-object-structure) as a first argument to it
+  - wraps a function and sends a [Transaction object](data-structures.md#transaction) as a first argument to it
 
 3. `beforeAll`, `afterAll`
-  - wraps a function and passes an Array of [Transaction objects](hooks.md#transaction-object-structure) as a first argument to it
+  - wraps a function and passes an Array of [Transaction objects](data-structures.md#transaction) as a first argument to it
 
 Refer to [Dredd execution life-cycle](how-it-works.md#execution-life-cycle) to find when is each hook function executed.
 

docs/hooks-php.md

@@ -28,14 +28,14 @@ $ dredd apiary.apib http://localhost:3000 --language vendor/bin/dredd-hooks-php
 The `Dredd\Hooks` class provides the static methods listed below to create hooks
 
 1. `beforeEach`, `beforeEachValidation`, `afterEach`
-  - accepts a closure as a first argument passing a [Transaction object](hooks.md#transaction-object-structure) as a first argument
+  - accepts a closure as a first argument passing a [Transaction object](data-structures.md#transaction) as a first argument
 
 2. `before`, `beforeValidation`, `after`
   - accepts [transaction name](hooks.md#getting-transaction-names) as a first argument
-  - accepts a block as a second argument passing a [Transaction object](hooks.md#transaction-object-structure) as a first argument of it
+  - accepts a block as a second argument passing a [Transaction object](data-structures.md#transaction) as a first argument of it
 
 3. `beforeAll`, `afterAll`
-  - accepts a block as a first argument passing an Array of [Transaction objects](hooks.md#transaction-object-structure) as a first argument
+  - accepts a block as a first argument passing an Array of [Transaction objects](data-structures.md#transaction) as a first argument
 
 
 Refer to [Dredd execution lifecycle](how-it-works.md#execution-life-cycle) to find when is each hook function executed.

docs/hooks-python.md

@@ -24,14 +24,14 @@ $ dredd apiary.apib http://localhost:3000 --language python --hookfiles=./hooks*
 Module `dredd_hooks` imports following decorators:
 
 1. `before_each`, `before_each_validation`, `after_each`
-  - wraps a function and passes [Transaction object](hooks.md#transaction-object-structure) as a first argument to it
+  - wraps a function and passes [Transaction object](data-structures.md#transaction) as a first argument to it
 
 2. `before`, `before_validation`, `after`
   - accepts [transaction name](hooks.md#getting-transaction-names) as a first argument
-  - wraps a function and sends a [Transaction object](hooks.md#transaction-object-structure) as a first argument to it
+  - wraps a function and sends a [Transaction object](data-structures.md#transaction) as a first argument to it
 
 3. `before_all`, `after_all`
-  - wraps a function and passes an Array of [Transaction objects](hooks.md#transaction-object-structure) as a first argument to it
+  - wraps a function and passes an Array of [Transaction objects](data-structures.md#transaction) as a first argument to it
 
 
 Refer to [Dredd execution life-cycle](how-it-works.md#execution-life-cycle) to find when is each hook function executed.

docs/hooks-ruby.md

@@ -23,14 +23,14 @@ $ dredd apiary.apib http://localhost:3000 --language ruby --hookfiles=./hooks*.r
 Including module `Dredd::Hooks:Methods` expands current scope with methods
 
 1. `@before_each`, `before_each_validation`, `after_each`
-  - accepts a block as a first argument passing a [Transaction object](hooks.md#transaction-object-structure) as a first argument
+  - accepts a block as a first argument passing a [Transaction object](data-structures.md#transaction) as a first argument
 
 2. `before`, `before_validation`, `after`
   - accepts [transaction name](hooks.md#getting-transaction-names) as a first argument
-  - accepts a block as a second argument passing a [Transaction object](hooks.md#transaction-object-structure) as a first argument of it
+  - accepts a block as a second argument passing a [Transaction object](data-structures.md#transaction) as a first argument of it
 
 3. `before_all`, `after_all`
-  - accepts a block as a first argument passing an Array of [Transaction objects](hooks.md#transaction-object-structure) as a first argument
+  - accepts a block as a first argument passing an Array of [Transaction objects](data-structures.md#transaction) as a first argument
 
 
 Refer to [Dredd execution lifecycle](how-it-works.md#execution-life-cycle) to find when is each hook function executed.