[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [tsf-dev] Storing TSF `Statement` information in a more structured way
|
Hi Gavin,
Thanks for your response.
For 1, the intention was that a reference could be "inline text" so this
is stored in the file alongside the statement. There could be a separate
"explanation" class if the "context" class doesn't cover it well enough.
The reason for including a file option is that you might want to provide
explanation/context based on the project docs or even some remote docs
so there is not duplication of content.
For 2, My reason for including Child links is that is reading the
argument from the files (without tooling) then that would be nearly
impossible with just parent links. I do not see a problem with changing
multiple files, in fact I think it simplifies visualising changes with a
simple diff, i.e. without custom tooling. Possibly the right option is
to include Child and Parent links so that this is navigation and context
is more easily visible.
As for Object types and Link types, these are wider questions that
better structuring the currently available information, so I think they
are out of scope for this thread.
John
On 18/05/2026 16:39, Gavin McCall via tsf-dev wrote:
Thanks John,
I have two comments / observations / suggestions.
1/
In many cases we want to write a Statement and also write
Explanation_text, which allows us to expand on the Statement with
further test explanation, example, etc.
The current single test-field approach required that the first
Statement is in an object type normative.
The Explanation_text can be the test in a 2nd object type non-normative.
A link is then required to link the 2nd object to the first.
A problem with this, other that the 3x entity multiplication (1st
object, 2nd object, link) is that people read the !st Object and
ignore the linked explanation!
A preferred solution is to allow two text fields per object:
Statement: (required)
Explanation: (optional)
I could go further, and suggest that we define types for Objects, and
each Object type can include additional attributes. The type of an
object - Statement, Argument, Evidence becoming a stated type, rather
than an accident of use.
See https://gitlab.com/CodethinkLabs/trustable/trustable/-/work_items/387
2.
You have Child Link(s). Would a Parent Link be a better alternative?
Are we more likely to work top down, so adding a child is only adding
a new child node with a link to its parent? 1 file changed.
The tooling then doing the work of collecting the list of children for
a given parent?
I would also like us to name the relationship and allow different
types of Link. This will allow a meaning to be placed on a link.
On 18/05/2026 15:14, John Horsley via tsf-dev wrote:
Having (attempted) to use TSF on a couple of projects recently I have
some proposals, that it would be good to get some feedback on, about
what information we should be storing in relation to TSF `Statements`
and in my opinion it should be stored as close to the 'Statement' as
possible i.e. in the same file. This inclusion of a 'tooling-managed'
section brings the relevant tool generated information closer to the
Statements (meaning reviewing diffs is easier as more of the context
is visible) as well as keeping the separation of tooling vs human
managed content visible.
The following proposal is not intended to define the implementation
details, and should not be file format specific (there is no reason
multiple different file formats e.g. YAML, TOML, etc could not be
supported in the tooling).
The `Statement` file **should** include the following properties:
- statement (required)
- this should be explicitly defined, rather than the 'left over
text' as it is currently
- references (optional)
- should be constrained to pre-defined classes, initial
suggestion for available classes:
- context: defined in a file (or inline text)
- rebuttal (or fallacy?): defined in a file (or inline text)
- misbehaviour: defined in a file (or inline text)
- evidence:
- for SME type validation: defined in a file (or inline
text)
- for 'automated' validation: defined location of the
generated file.
- a placeholder should be generated if the validator
has not run
- should contain (at least) the log output of the
validator run
- assessment (required)
- validation (required):
- type (required): None or SME or `validator name`
- configuration (optional): for automated validation only
- confidence (optional): to align with current 'scoring' this
should be the numeric confidence that the Statement is`true`,
attributed to an SME (or SMEs)
- for 'SME' type, stored in git based on the supplied
reference content
- for 'validator' type, generated at `validation` based on
the validator tooling and output
- (not stored in git) verdict: True or False, generated with
`validation` of the graph
- if evidence type is `SME` the verdict should be `True` if
the referenced evidence is available in the trudag context, `False`
otherwise
- if evidence type is `validator` the validator should
provide this
- tooling-managed:
- `state` of the associated content (allows tooling to assess
what has changed), out of date content should cause an error in graph
linting:
- individually stored based on the defined content:
- Statement
- References:
- pointer to the stored `state` for each reference
(should be stored centrally as multiple statements might use the same
reference)
- combined `state` of all references (means that it
is clear the references have changed when `diffing` the file)
- Assessment config:
- pointer to the stored `state` for validator (should
be centrally stored as multiple statements might use the same validator)
- combined `state` of the assessment `configuration`
and the validator `state`
- Child Links
- Total:
- combined state of 'Statement', 'References',
'Assessment config' and 'Child Links'
The `Statement` file **should not** include the following properties,
currently defined as YML `frontmatter` in the Markdown files:
- normative
- I have seen 'non-normative' files used to preface a group of
statements with a summary, if this is required functionality then
there should be a dedicated approach for this rather than abusing the
`doorstop` legacy 'non-normative' option.
- level & publish
- better to have a 'nav' like approach that defines this at a
graph level for the publishing
- evidence
- amalgamated into `assessment` property
- score
- amalgamated into `assessment` property
Regards,
John Horsley
Codethink Ltd
_______________________________________________
tsf-dev mailing list
tsf-dev@xxxxxxxxxxx
To unsubscribe from this list, visit https://accounts.eclipse.org
--
John Horsley (He/Him)
Software Engineer
Codethink Ltd
4th Floor Dale House
35 Dale Street
Manchester
M1 2HF
UK
Codethink delivers cutting edge open source design, development and integration services
http://codethink.co.uk
Office: +44 161 236 5575
We respect your privacy. See https://www.codethink.co.uk/privacy.html
