Item Reference
Doorstop items are files formatted using YAML. When a new item is added using
doorstop add
, Doorstop will create a YAML file and populate it with all
required attributes (key-value pairs). The UID of an item is defined by its
file name without the extension. An UID consists of two parts, the prefix and a
number or name. The two parts are divided by an optional separator. The prefix
and separator are determined by the document to which the item belongs. By
default, the number is automatically assigned by Doorstop. Optionally, a user
can specify a name for the UID during item creation. The name must not contain
separator characters.
Items can be stored in different formats. Two types are currently supported and
can be configured via itemformat in the
.doorstop.yml
configuration file:
The default yaml
format stores the requirement items completely as yaml.
Advantage is the standardized and easily parsable format in case the files
need to be processed furher. The disadvantage is that there is little editor
support when writing longer requirement texts, as the text need to adhere to the
yaml formatting rules (e.g. indentation).
The alternative markdown
format stores requirement items as markdown text with
yaml frontmatter. This concept is used by many other tools as well (e.g.
jekyll). With this format, the
header
attribute is automatically derived from the first level 1 header
line within the text, the remaining content of the markdown text section
is used as text
attribute.
Example item in yaml
format: REQ_000.yml
active: true
derived: false
header: |
Identifiers
level: 2.1
links: []
normative: true
ref: ''
reviewed: 9TcFUzsQWUHhoh5wsqnhL7VRtSqMaIhrCXg7mfIkxKM=
text: |
Doorstop **shall** provide unique and permanent identifiers to linkable
sections of text.
The equivalent item in markdown
format: REQ_000.md
---
active: true
derived: false
level: 2.1
links: []
normative: true
ref: ''
reviewed: 9TcFUzsQWUHhoh5wsqnhL7VRtSqMaIhrCXg7mfIkxKM=
---
# Identifiers
Doorstop **shall** provide unique and permanent identifiers to linkable
sections of text.
Regarding the documentation below both formats are equivalent, besides the
specific header
and text
handling as shown above. The decision can be based
on whether the better text editing support of the markdown
format or the
consistent yaml structure is more important. The formats can also be freely
mixed within a document tree, the decision can be made and configured
per document.
Standard Item Attributes
active
Determines if the item is active (true) or not (false). Only active items are included when the corresponding document is published. Inactive items are excluded from validation.
The value of this attribute does not contribute to the fingerprint of the item.
derived
Indicates if the item is derived (true) or not (false).
AcqNotes defines derived requirements as:
'...requirements that are not explicitly stated in the set of stakeholder requirements yet is required to satisfy one or more of them. They also arise from constraints, consideration of issues implied but not explicitly stated in the requirements baseline, factors introduced by the selected architecture, Information Assurance (IA) requirements and the design.'
Doorstop does not expect parent links on derived items.
The value of this attribute does not contribute to the fingerprint of the item.
normative
Indicates if the item is normative (true) or non-normative (false).
Wikipedia on Normative in standards documents:
'In standards terminology still used by some organizations, "normative" means "considered to be a prescriptive part of the standard". It characterizes that part of the standard which describes what ought (see philosophy above) to be done within the application of that standard. It is implicit that application of that standard will result in a valuable outcome (ibid.). For example, many standards have an introduction, preface, or summary that is considered non-normative, as well as a main body that is considered normative. "Compliance" is defined as "complies with the normative sections of the standard"; an object that complies with the normative sections but not the non-normative sections of a standard is still considered to be in compliance.'
The value of this attribute does not contribute to the fingerprint of the item.
level
Indicates the presentation order within a document. A level of 1.1 will display above level 1.2 and 1.1.5 displays below 1.1.2.
If the level ends with .0 and the item is non-normative, Doorstop will treat the item as a document heading. See the text-section for an example.
The value of this attribute does not contribute to the fingerprint of the item.
If you edit the item file by hand or use other tools be aware of the implicit typing rules in YAML. For example the following level value
level: 1.10
will parsed as a 1.1 float value. Doorstop will interpret this as level 1.1
and store this level in the item file. Use quotes around non-float values,
e.g. level: '1.10'
.
header
Gives a header (i.e. title) for the item. It will be printed alongside the item UID when published as HTML and Markdown. Links will also include the header text. This is different from a heading item.
The value of this attribute does not contribute to the fingerprint of the item.
Example: Header
TST007.yml
level: 1.5
normative: true
links:
- REQ023: null
header: |
Gradual Temperature Drop Test
text: |
Lower the external air temperature gradually from 0 to -15 degrees Celsius over a period of 30 minutes.
Ensure the system performs a safe shutdown when -15 degrees Celsius is reached.
When this item is published, Doorstop will place the item's Header next to its UID.
TST007 Gradual Temperature Drop Test
Lower the external air temperature gradually from 0 to -15 degrees Celsius over a period of 30 minutes.
Ensure the system performs a safe shutdown when -15 degrees Celsius is reached.
Parent Item: REQ023 Temperature Interlock
reviewed
Each item has a fingerprint. By default, the UID of the item, the values of the text and ref attributes, and the UIDs of the links attribute contribute to the fingerprint. Optionally, values of extended attributes can be added to the fingerprint through a document configuration option.
The value of the reviewed attribute indicates the fingerprint of the item when it was last reviewed. "null" if the item has not yet been reviewed. Doorstop will use this to detect unreviewed changes to an item by comparing the current item fingerprint to the last reviewed fingerprint. The fingerprint hash algorithm is SHA256 stored in URL-safe Base64 encoding.
You should not calculate this value manually, use doorstop review
.
links
A list of links to parent item(s). A link indicates a relationship between two items in the document tree.
In the following example, REQ001
is a parent to the item.
links:
- REQ001: avwblqPimDJ2OgTrRCXxRPN8FQhUBWqPIXm7kSR95C4=
A link consists of two parts, the parent item UID and the fingerprint of the parent when it last reviewed. If the link has not yet been reviewed, the fingerprint is set to "null" or omitted.
links:
- REQ001: null
is equivalent to
links:
- REQ001
In the cases where no fingerprint exists or a null-fingerprint is specified, Doorstop will add a new fingerprint whenever a review occurs.
The link fingerprint is used by Doorstop to detect when a parent item is changed, as a convenience to the writer since such change may also affect its children.
Only the UID part of the link contributes to the fingerprint of the item (the item of the reviewed attribute, not the parent item of the link). The fingerprint of the link is does not contribute to the fingerprint of the item.
references
(new array behavior)
An array of external references. An item may reference a number of external files. The external references are displayed in a published document.
Doorstop will search in the project root for a file matching the specified reference. If multiple matching files exist, the first found will be used.
The value of this attribute contributes to the fingerprint of the item.
Example: Reference files
references:
- path: tests/test1.cpp
type: file
- path: tests/test2.cpp
type: file
Note: new behavior vs old behavior
Note: Newer references
attribute is a new array behavior compared to the
original ref
attribute's string behavior. The old behavior supports referencing
only one file via file name or referencing a file that contains a given
keyword.
The new behavior of references
attribute allows referencing many files. The
old behavior matching a specified keyword is enabled via optional keyword
parameter:
references:
- path: tests/test1.cpp
type: file
keyword: REQ1
- path: tests/test2.cpp
type: file
keyword: REQ2
Doorstop will search a specified file to find the specified reference.
ref
(deprecated behavior, see 'references')
Please check the "references
(new array behavior)" section before reading further.
External reference. An item may reference an external file or a line in an external file. An external reference is displayed in a published document.
Doorstop will search the project root and it's sub-directories for a filename matching the specified reference. If multiple matching files exist, the first found will be used.
If a file is not found, Doorstop will also search the contents of all text-files in the project root and it's sub-directories. If a line contains the referenced keyword, Doorstop will reference the file and line number where it found the keyword. If the keyword is found in multiple lines or files, the first found will be used.
A file is considered a text-file unless its file extension is listed in
SKIP_EXTS
(settings.py).
The value of this attribute contributes to the fingerprint of the item.
Example: Reference keyword
ref: 'TST001'
References the filename and line number of a text-file that contains the keyword "TST001".
Example: Reference file
ref: 'test-tst001.c'
References a file called "test-tst001.c".
If a reference is specified and Doorstop is unable to find it, Doorstop will exit with an error unless reference checking is disabled.
text
Item text. This is the main body of the item. Doorstop treats the value as markdown to support rich text, images and tables. To specify a multi-line text, use block scalar types as specified by the YAML standard.
The value of this attribute contributes to the fingerprint of the item.
Example: Heading
REQ001.yml
level: 1.1.0
normative: false
text: |
This is the heading
This is some text that goes into chapter 1.1.0.
When this item is published, Doorstop will create a new heading with the text "1.1.0 This is the heading" and put the remaining text into its body.
Example: Normative item
REQ001.yml
level: 1.1.0
normative: true
text: |
Doorstop **shall** support exporting to the ReqIF file format.
When this item is published, Doorstop will create a new heading with the text "1.1.0 REQ001" and put the all of the text in its body.
Example: LaTeX-like math expressions
You can use math expressions in LaTeX interpreted by the markdown extension python-markdown-math and rendered by MathJax, when using the HTML publisher.
TST008.yml
level: 1.6
normative: true
links:
- REQ023: null
text: |
When $a \ne 0$, there are two solutions to \(ax^2 + bx + c = 0\) and they are
$$x = {-b \pm \sqrt{b^2-4ac} \over 2a}.$$
Extended Item Attributes
In addition to the standard attributes, Doorstop will allow any number of custom extended attributes (key-value pairs) in the YAML file. The extended attributes will not be part of a published document, but they can be queried by a 3rd party application through the REST interface or the Python API.
In this example, an extended attribute invented-by
is added to the item.
invented-by: jane@example.com
Defaults for extended attributes
Optionally, you can add custom default values for extended attributes. Add
them as key-value pairs to the defaults
dictionary under the attributes
section in the corresponding document configuration file .doorstop.yml
.
There is no command to maintain this configuration option. You have to edit
the document configuration file .doorstop.yml
by hand.
settings:
digits: 3
prefix: REQ
sep: ''
attributes:
defaults:
attribute-key-0: a scalar default value
attribute-key-1:
- default values can
- be lists
attribute-key-2:
default: values can
be: dictionaries
attribute-key-3: ... default values can be arbitrarily complex
Extended reviewed attributes
By default, the values of extended attributes do not contribute to the
fingerprint of the item. Optionally, you can add the
values of extended attributes to the fingerprint through the reviewed
list
under the attributes
section in the corresponding document configuration file
.doorstop.yml
. The reviewed
list must be a non-empty list of attribute
keys. There is no command to maintain this configuration option. You have to
edit the document configuration file .doorstop.yml
by hand.
settings:
digits: 3
prefix: REQ
sep: ''
attributes:
reviewed:
- type
- verification-method
If attributes listed in reviewed
do not exist in an item of this document,
then these attributes are skipped in the fingerprint calculation and no warning
is issued by the validation command doorstop
. Validation of items against a
template should be done by third-party tools. Changing the order of reviewed
attributes listed in the document configuration changes the fingerprint of
existing item of the documents which have these attributes. Adding new
reviewed attributes to the document configuration does not change the
fingerprint of existing items of the document, if they do not have them,
otherwise the fingerprint changes. Removing a reviewed attribute from the
document configuration changes the fingerprint of all items of the document
with such an attribute. The type of the values, empty strings, lists, and
dictionaries affect the fingerprint.
Publishing extended attributes
Introduced in v2.2, Doorstop can include extended attributes in published output.
Edit the document configuration file .doorstop.yml
by hand to include the desired attributes.
For example, to include the invented-by
extended attribute key and value in the published output:
settings:
digits: 3
prefix: REQ
sep: ''
attributes:
publish:
- invented-by