docs/content/introduction/model_schema.md

   1 ---
   2 bookHidden: true
   3 title: "Model Schema"
   4 ---
   5
   6 # Model Schema
   7
   8 This document describes what is currently implemented in CSIT,
   9 especially the export side (UTI), not import side (PAL).
  10
  11 ## Version
  12
  13 This document is valid for CSIT model version 1.4.0.
  14
  15 It is recommended to use semantic versioning: https://semver.org/
  16 That means, if the new model misses a field present in the old model,
  17 bump the major version. If the new model adds a field
  18 not present in the old model, bump the minor version.
  19 Any other edit in the implmenetation (or documentation) bumps the patch version.
  20 If you change value type or formatting,
  21 consider whether the parser (PAL) understands the new value correctly.
  22 Renaming a field is the same as adding a new one and removing the old one.
  23 Parser (PAL) has to know exact major version and minimal minor version,
  24 and unless bugs, it can ignore patch version and bumped minor version.
  25
  26 ## UTI
  27
  28 UTI stands for Unified Test Interface.
  29 It mainly focuses on exporting information gathered during test run
  30 into JSON output files.
  31
  32 ### Output Structure
  33
  34 UTI outputs come in filesystem tree structure (single tree), where directories
  35 correspond to suite levels and files correspond to suite setup, suite teardown
  36 or any test case at this level of suite.
  37 The directory name comes from SUITE_NAME Robot variable (the last part
  38 as the previous parts are higher level suites), converted to lowercase.
  39 If the suite name contains spaces (Robot converts underscores to spaces),
  40 they are replaced with underscores.
  41
  42 The filesystem tree is rooted under tests/ (as suites in git are there),
  43 and for each component (test case, suite setup, suite teardown).
  44
  45 Although we expect only ASCII text in the exported files,
  46 we manipulate files using UTF-8 encoding,
  47 so if Robot Framework uses a non-ascii character, it will be handled.
  48
  49 ### JSON schemas
  50
  51 CSIT model is formally defined as a collection of JSON schema documents,
  52 one for each output file type.
  53
  54 The current version specifies only one output file type:
  55 Info output for test case.
  56
  57 The authoritative JSON schema documents are in JSON format.
  58 Git repository also contains YAML formatted document and conversion utility,
  59 which simplifies maintaining of the JSON document
  60 (no need to track brackets and commas), but are not authoritative.