feat(model): Cleanup and introduce telemetry

[csit.git] / docs / model / current / top.rst

diff --git a/docs/model/current/top.rst b/docs/model/current/top.rst
index 640abe2..e824225 100644 (file)
--- a/docs/model/current/top.rst
+++ b/docs/model/current/top.rst
@@ -1,5 +1,5 @@
 ..
 ..

-   Copyright (c) 2021 Cisco and/or its affiliates.
+   Copyright (c) 2022 Cisco and/or its affiliates.

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at:
    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at:


@@ -22,7 +22,7 @@ especially the export side (UTI), not import side (PAL).
 Version
 ~~~~~~~
 
 Version
 ~~~~~~~
 

-This document is valid for CSIT model version 0.1.0.
+This document is valid for CSIT model version 1.1.0.

 
 It is recommended to use semantic versioning: https://semver.org/
 That means, if the new model misses a field present in the old model,
 
 It is recommended to use semantic versioning: https://semver.org/
 That means, if the new model misses a field present in the old model,


@@ -42,7 +42,34 @@ UTI stands for Unified Test Interface.
 It mainly focuses on exporting information gathered during test run
 into JSON output files.
 
 It mainly focuses on exporting information gathered during test run
 into JSON output files.
 

-Files
------
+Output Structure
+-----------------

 
 

-No files are exported yet in this version.
+UTI outputs come in filesystem tree structure (single tree), where directories
+correspond to suite levels and files correspond to suite setup, suite teardown
+or any test case at this level of suite.
+The directory name comes from SUITE_NAME Robot variable (the last part
+as the previous parts are higher level suites), converted to lowercase.
+If the suite name contains spaces (Robot converts underscores to spaces),
+they are replaced with underscores.
+
+The filesystem tree is rooted under tests/ (as suites in git are there),
+and for each component (test case, suite setup, suite teardown).
+
+Although we expect only ASCII text in the exported files,
+we manipulate files using UTF-8 encoding,
+so if Robot Framework uses a non-ascii character, it will be handled.
+
+JSON schemas
+------------
+
+CSIT model is formally defined as a collection of JSON schema documents,
+one for each output file type.
+
+The current version specifies only one output file type:
+Info output for test case.
+
+The authoritative JSON schema documents are in JSON format.
+Git repository also contains YAML formatted document and conversion utility,
+which simplifies maintaining of the JSON document
+(no need to track brackets and commas), but are not authoritative.