Anatomy Of The Twine File

The main point of twined is to enable engineers and scientists to easily (and rigorously) define a digital twin or data service.

This is done by adding a twine.json file to the repository containing your code. Adding a twine means you can:

  • communicate (to you or a colleague) what data is required by this service

  • communicate (to another service / machine) what data is required

  • deploy services automatically with a provider like Octue.

To just get started building a twine, check out the Quick Start. To learn more about twines in general, see About Twines. Here, we describe the parts of a twine (“strands”) and what they mean.

Strands

A twine has several sections, called strands. Each defines a different kind of data required (or produced) by the twin.

Strand

Describes the twin’s requirements for…

Configuration Values

Data, in JSON form, used for configuration of the twin/service.

Configuration Manifest

Files/datasets required by the twin at configuration/startup

Input Values

Data, in JSON form, passed to the twin in order to trigger an analysis

Input Manifest

Files/datasets passed with Input Values to trigger an analysis

Output Values

Data, in JSON form, that will be produced by the twin (in response to inputs)

Output Manifest

Files/datasets that will be produced by the twin (in response to inputs)

Credentials

Credentials that are required by the twin in order to access third party services

Children

Other twins, access to which are required for this twin to function

Monitors

Visual and progress outputs from an analysis

Twine File Schema

Because the twine.json file itself is in JSON format with a strict structure, twined uses a schema to make that twine files are correctly written (a “schema-schema”, if you will, since a twine already contains schema). Try not to think about it. But if you must, the twine schema is here.

The first thing twined always does is check that the twine.json file itself is valid, and give you a descriptive error if it isn’t.

Other External I/O

A twin might:

  • GET/POST data from/to an external API,

  • query/update a database,

  • upload files to an object store,

  • trigger events in another network, or

  • perform pretty much any interaction you can think of with other applications over the web.

However, such data exchange may not be controllable by twined (which is intended to operate at the boundaries of the twin) unless the resulting data is returned from the twin (and must therefore be compliant with the schema).

So, there’s nothing for twined to do here, and no need for a strand in the twine file. However, interacting with third party APIs or databases might require some credentials. See Credentials Strand for help with that.

Note

This is actually a very common scenario. For example, the purpose of the twin might be to fetch data (like a weather forecast) from some external API then return it in the output_values for use in a network of digital twins. But its the twin developer’s job to do the fetchin’ and make sure the resulting data is compliant with the output_values_schema (see Values-based Strands).