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… |
---|---|
Data, in JSON form, used for configuration of the twin/service. |
|
Files/datasets required by the twin at configuration/startup |
|
Data, in JSON form, passed to the twin in order to trigger an analysis |
|
Files/datasets passed with Input Values to trigger an analysis |
|
Data, in JSON form, that will be produced by the twin (in response to inputs) |
|
Files/datasets that will be produced by the twin (in response to inputs) |
|
Credentials that are required by the twin in order to access third party services |
|
Other twins, access to which are required for this twin to function |
|
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).