secureCodeBox · J12934 · Jul 30, 2021 · Jul 14, 2021 · Jul 14, 2021 · Jul 14, 2021
diff --git a/docs/api/finding.md b/docs/api/finding.md
@@ -6,24 +6,93 @@
 title: "Finding"
 ---
 
-All scanners integrated in the secureCodeBox create findings objects.
-These findings all contain the same set of fields listed in the example below.
+All scanners integrated in the secureCodeBox create a JSON-Array of Findings objects.
+The 'findings.json' file that contains these Findings complies with the following JSON Schema (Draft-04).
+
+```yaml
+{
+  "$schema": "http://json-schema.org/draft-04/schema",
+  "type": "array",
+  "description": "Array of Findings.",
+  "items": {
+    "$ref": "#/$defs/finding"
+  },
+  "$defs": {
+    "finding": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "id": {
+          "description": "The unique identifier for a Finding according to RFC4122.",
+          "type": "string",
+          "format": "uuid"
+        },
+        "identified_at": {
+          "description": "Date-Time when the Finding was exactly identified according to ISO8601. This information will often not be present.",
+          "type": "string",
+          "format": "date-time"
+        },
+        "parsed_at": {
+          "description": "Date-Time when the Finding was parsed according to ISO8601. This information will always be present.",
+          "type": "string",
+          "format": "date-time"
+        },
+        "name": {
+          "description": "Contains a short description of the Finding.",
+          "type": "string"
+        },
+        "description": {
+          "description": "In depth description, can span multiple paragraphs.",
+          "type": "string",
+          "nullable": true
+        },
+        "category": {
+          "description": "Is often used to group finding based on their types.",
+          "type": "string"
+        },
+        "severity": {
+          "description": "Indicates the severity of the finding.",
+          "type": "string",
+          "enum": [
+            "INFORMATIONAL",
+            "LOW",
+            "MEDIUM",
+            "HIGH"
+          ]
+        },
+        "attributes": {
+          "description": "Attributes are not standardized. They differ from Scanner to Scanner.",
+          "type": "object"
+        },
+        "location": {
+          "description": "Full URL with protocol, port, and path if existing.",
+          "type": "string",
+          "nullable": true
+        }
+      },
+      "required": [
+        "id",
+        "parsed_at",
+        "severity",
+        "category",
+        "name"
+      ]
+    }
+  }
+}
+```
+
+An example findings object is shown below:
 
 ```yaml
 {
-  # Unique uuid4 for the finding
   "id": "e18cdc5e-6b49-4346-b623-28a4e878e154",
-  # name contains a short description of the finding
   "name": "Open mysql Port",
-  # In depth description, can span multiple paragraphs
   "description": "Port 3306 is open using tcp protocol.",
-  # The category is often used to group finding based on their types
   "category": "Open Port",
-  # OSI network layer the finding fits into
-  "osi_layer": "NETWORK",
-  # One of "INFORMATIONAL", "LOW", "MEDIUM", "HIGH"
+  "parsed_at": "2021-06-22T12:27:28.153Z",
+  "identified_at": "2021-06-22T12:26:54.378Z",
   "severity": "INFORMATIONAL",
-  # Attributes are not standardized. They differ from scanner to scanner
   "attributes": {
     "port": 3306,
     "state": "open",
@@ -38,7 +107,6 @@ These findings all contain the same set of fields listed in the example below.
     "serviceVersion": null,
     "scripts": null
   },
-  # Full url with protocol, port, and path if existing
   "location": "tcp://127.0.0.1:3306"
 }
 ```
diff --git a/docs/contributing/integrating-a-scanner/parser-dir.md b/docs/contributing/integrating-a-scanner/parser-dir.md
@@ -5,7 +5,7 @@
 
 title: parser (Directory)
 ---
- 
+
 This directory contains the parser for your scanner to transform the results of your scanner to *Findings* (see: [Finding | secureCodeBox](/docs/api/finding)).
 
 ## Dockerfile
@@ -63,14 +63,25 @@ Create a `parser.js` file and update the parser function of the Parser SDK. A st
 
 ```javascript
 async function parse(fileContent) {
-    return [];
+  return [];
 }
 
 module.exports.parse = parse;
 ```
-After your scanner has finished, the Parser SDK will retrieve the output results and call your custom parse function `parse`. The SDK expects a finding object as specified in [Finding | secureCodeBox](/docs/api/finding). The `id` field can be omitted, as it will be added by the Parser SDK.
+
+After your scanner has finished, the Parser SDK will retrieve the output results and call your custom parse function `parse`. The SDK expects a finding object as specified in [Finding | secureCodeBox](/docs/api/finding). The `id`, `parsed_at` and `identified_at` fields can be omitted, as they will be added by the Parser SDK.
 
 ### Write Tests for Your Parser
 
-Please provide some tests for your parser in the `parser.test.js` file.
+Please provide some tests for your parser in the `parser.test.js` file. To make sure that the output complies with the format specified in [Finding | secureCodeBox](/docs/api/finding) you should call the method `validateParser(parseResult)` from the ParserSDK and assert that it must resolve (not throw errors). You can do so e.g. by calling the following code. See the already existing parsers for reference.
+
+```javascript
+const {
+  validateParser,
+} = require("@securecodebox/parser-sdk-nodejs/parser-utils");
+
+const findings = await parse(fileContent);
+await expect(validateParser(findings)).resolves.toBeUndefined();
+```
+
 If you need additional files for your test please save these in the `__testFiles__` directory. Please take a look at [Integration Tests | secureCodeBox](/docs/contributing/integrating-a-scanner/integration-tests) for more information.