A better description of TRPs

[larsvilhuber]

We should add information to the TRP description that can be preconfigured and corresponds to particular workflows at the institution running the TRACE workflow.

[larsvilhuber]

Currently, a TRP has

rdfs:comment

as unstructured text. Without requiring that institutions deploy their own custom vocabulary, suppose that an institution has three types of processes that their system will allow execution of (these would be high-level)

• run of a container
• manual processing by staff member
• output vetting by disclosure review board

Then a more structured and informative TRP description might be

...
"@id" : " trp/0",
...
"trov:trp_type" : "Container run",
"trov:trp_type_url" : "https://docs.sivacor.org/docs/executions/#1"
...
"@id" : " trp/2",
...
"trov:trp_type" : "Output vetting",
"trov:trp_type_url" : "https://docs.sivacor.org/docs/executions/#3"

The additional info about specific details (proposed enhancements, for instance, name of the container, etc.) may then also make more sense.

[Xarthisius]

I don't understand the need to wrap it in words. Wouldn't it be better to simply provide a command that was run?

"@id" : " trp/0",
"trov:command": "/usr/local/stata/stata-mp -b do main.do"
...
"@id" : "trp/1",
"trov:command": '/bin/sh -c "for fname in $sivacor_ignore; do rm -rf $fname; done"'
...

isn't that way more transparent than trying to explain what "container run" or "output vetting" means using 500 words essays?

Update: I re-read your comment and noticed the whole "manual" part...

[larsvilhuber]

Because output vetting is FAR more complex usually then a simple command. I'm fine to have "command" as an option. But I want to insist that all these institutes describe what exactly they do. That is important not just AFTER the fact (in which case it can be picked from a JSON file using a Python command... sure, that works for a lot of people), but BEFORE the fact. Transparency about what WILL happen. And the description (500 word essay...) needs to be in sync with what the process actually does...

[larsvilhuber]

But +1 to trov:command.

[tmcphillips]

Focusing first on distinguishing between different types of TRPs: there's probably a lot of variety here worth mapping out. A starting point would be to make a list of likely variants we can dream up and see how they cluster, how many dimensions they fall along, which are more specialized variants of each other, etc.

There is a lot of flexibility we can take advantage of and still keep things simple. Because we can apply multiple types to a TRP, we can declare one TRP to be Manual (as opposed to Automated), a Vetting (as opposed to a Computation, say), or both Manual and a Vetting.

Going the other direction, we can use subtyping. If we said that DisclosureReview is a special kind of Vetting, then some TRPs could be declared Vettings, and others declared DisclosureReviews, with those TRPs that are DisclosureReviews automatically considered Vettings.

[larsvilhuber]

I absolutely am NOT suggesting that we define the various types. there is too much variety, and no consensus will ever emerge. We should not try to even attempt that. It is for each TRS to define its types. I just want to introduce the concept of types, which then must be defined by the host of the TRS. Transparency of what they are doing, but at a certain level of abstraction.

…

-- Lars Vilhuber On mobile device

________________________________ From: Timothy McPhillips ***@***.***> Sent: Sunday, May 3, 2026 12:25:53 AM To: transparency-certified/trace-specification ***@***.***> Cc: Lars Vilhuber ***@***.***>; Author ***@***.***> Subject: Re: [transparency-certified/trace-specification] A better description of TRPs (Issue #36) [https://avatars.githubusercontent.com/u/3218259?s=20&v=4]tmcphillips left a comment (transparency-certified/trace-specification#36)<#36 (comment)> Focusing first on distinguishing between different types of TRPs: there's probably a lot of variety here worth mapping out. A starting point would be to make a list of likely variants we can dream up and see how they cluster, how many dimensions they fall along, which are more specialized variants of each other, etc. There is a lot of flexibility we can take advantage of and still keep things simple. Because we can apply multiple types to a TRP, we can declare one TRP to be Manual (as opposed to Automated), a Vetting (as opposed to a Computation, say), or both Manual and a Vetting. Going the other direction, we can use subtyping. If we said that DisclosureReview is a special kind of Vetting, then some TRPs could be declared Vettings, and others declared DisclosureReviews, with those TRPs that are DisclosureReviews automatically considered Vettings. — Reply to this email directly, view it on GitHub<#36 (comment)>, or unsubscribe<https://github.com/notifications/unsubscribe-auth/ABVSQ6CBQ4WSYERNHY2S7G34Y3C5DAVCNFSM6AAAAACYOOP5ZCVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DGNRVGM4DENRYGY>. You are receiving this because you authored the thread.Message ID: ***@***.***>

[larsvilhuber]

Summarizing lightly:

One or the other of

"trov:trp_type" : (free form text field, but consistent across multiple TROs from the same TRS)
"trov:trp_type_url" : (URL providing more information about these. Unique across all TROs generated by this TRS)

and/or

"trov:command": (specific and sole command run within this TRP)

The latter makes sense when that is an exhaustive description. To take SIVACOR as an example,

• currently only one TRP_TYPE, "Run Docker container". The TRP_TYPE_URL might then contain exactly how we run the docker container (which, as Kacper and I have figured out, is not QUITE the same as running it from a generic command line). trov:command: : "/usr/local/stata/stata-mp -b do main.do" might then ALSO describe what is run inside the specific TRP, but is by itself insufficient to give a curious reader enough information.
• I have sketched out demonstration functionality to use on SIVACOR ... Create an example for dataset or file removal in the SIVACOR interface SIVACOR/aea-sivacor#27 It would be complemented by updates to sivacor/documentation that describes in much more detail the processing that is done.

[tmcphillips]

Got it. What we're aiming to do then is to allow a TRS to associate TRPs with processes specific to the particular organization.

Here's a way to support this following the extensibility pattern we established for capabilities: the TRS declares (in its TRS certificate, copied into each TRO) a handful of identifiers for its procedure types (I'm calling them "procedures" here rather than "processes" to avoid confusion with OS-level processes), and then the TRPs reference these via the standard @type property.

This does ask each TRS to mint identifiers for its procedures (e.g. sivacor:ContainerRun), but that's just naming a few terms in the TRS certificate, not deploying a full custom vocabulary with namespace resolution or documentation infrastructure (the rdfs:seeAlso links suffice). Because the TRS certificate is copied into every TRO, the same identifiers automatically appear across all TROs produced by that TRS, achieving your "consistent across multiple TROs" requirement without an external vocabulary.

Using the information in your first example:

// The TRS declaration in the TRO provides identifiers and optional information 
// for each of the organization-specific procedures the TRS implements
"trov:customTerm": [
  {
    "@id": "sivacor:ContainerRun",
    "@type": "trov:Procedure",
    "rdfs:label": "Container run",
    "rdfs:comment": "Execution of a researcher-submitted Docker container in a network-isolated environment with no interactive access.",
    "rdfs:seeAlso": { "@id": "https://docs.sivacor.org/docs/executions/#container-run" }
  },
  {
    "@id": "sivacor:OutputVetting",
    "@type": "trov:Procedure",
    "rdfs:label": "Output vetting",
    "rdfs:comment": "Review of execution outputs by disclosure review board. Board members inspect outputs for disclosure risk before release.",
    "rdfs:seeAlso": { "@id": "https://docs.sivacor.org/docs/executions/#output-vetting" }
  }
]

// Each TRP then references the organization-specific procedure it implements
// by adding the corresponding identifier defined above to its @type array
{ "@id": "trp/0", "@type": ["trov:TrustedResearchPerformance", "sivacor:ContainerRun"] }
{ "@id": "trp/1", "@type": ["trov:TrustedResearchPerformance", "sivacor:OutputVetting"] }

Only @id and @type: trov:Procedure are required for the custom terms to serve ("JSON-LDiomatically") as types. The rdfs:label and rdfs:seeAlso correspond to your trp_type and trp_type_url respectively. The rdfs:comment here allows the TRS to commit (in its certificate and via its signature on the TRO) to a minimum description of the procedure (because the content referenced by an external URL isn't signed along with the TRO and could change or vanish).

This gives us a procedural complement to TRS capabilities: capabilities describe what the system can do (block internet access, prevent user intervention, etc.); procedure types describe what type of activity the system performed in a given TRP. Both use the same declare-then-reference pattern in the TRO, and both provide a warrant relationship (a TRP can't claim a procedure type its TRS hasn't declared in its certificate).

[larsvilhuber]

@tmcphillips I like this, except for the fact that the ID is custom to each TRS. I would like to be able to require it, and an iterative property (trov:Procedure, >= 1) would seem to allow that better. So

{ "@id": "trp/0", "@type": ["trov:TrustedResearchPerformance", "trov:Procedure:1"] }
{ "@id": "trp/1", "@type": ["trov:TrustedResearchPerformance", "trov:Procedure:2"] }

would seem a bit better suited to making it a requirement.

[tmcphillips]

An issue with shared identifiers like trov:Procedure:1 is that in JSON-LD (this is the "linked data" stinger: all identifiers share a single namespace) they expand to the same URI regardless of which TRS wrote them. So SIVACOR's "Procedure 1" and REX's "Procedure 1" become indistinguishable to any consumer looking across TROs. Custom identifiers (sivacor:ContainerRun, rex:BatchExecution) keep them distinct.

On requiring it, validation can still mandate that every TRP declares at least one procedure type even with custom identifiers. It's a cross-reference check within the JSON (does this TRP's @type array include a value that appears as an @id in the TRS's customTerm list with "@type": "trov:Procedure"?). Straightforward to implement in tro-utils I suspect.

[larsvilhuber]

That makes sense. I'm in. Propose it as an amendment for the next release, and let's get input from the central banks and the World Bank as a "review period".