diff --git a/docs/source/images/digital_twin_hierarchy.svg b/docs/source/images/digital_twin_hierarchy.svg
new file mode 100644
index 0000000..e6c68e7
--- /dev/null
+++ b/docs/source/images/digital_twin_hierarchy.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/docs/source/images/placeholder.png b/docs/source/images/placeholder.png
deleted file mode 100644
index 2f4cfb3..0000000
Binary files a/docs/source/images/placeholder.png and /dev/null differ
diff --git a/docs/source/images/schema_form_example.png b/docs/source/images/schema_form_example.png
new file mode 100644
index 0000000..c27816a
Binary files /dev/null and b/docs/source/images/schema_form_example.png differ
diff --git a/docs/source/index.rst b/docs/source/index.rst
index b68f691..8c3d728 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,9 +1,11 @@
.. image:: https://codecov.io/gh/octue/twined/branch/master/graph/badge.svg
:target: https://codecov.io/gh/octue/twined
:alt: Code coverage
+ :align: right
.. image:: https://readthedocs.org/projects/twined/badge/?version=latest
:target: https://twined.readthedocs.io/en/latest/?badge=latest
:alt: Documentation Status
+ :align: right
======
twined
@@ -12,6 +14,10 @@ twined
**twined** is a library to help digital twins talk to one another.
+.. epigraph::
+ "Twined" [t-why-nd] - encircled, twisted together, interwoven
+
+
.. ATTENTION::
This library is in very early stages. Like the idea of it? Please
`star us on GitHub `_ and contribute via the
@@ -19,9 +25,22 @@ twined
`roadmap `_.
+.. _digital_twins:
+Digital Twins
+=============
+
A digital twin is a virtual representation of a real life being - a physical asset like a wind turbine or car - or even
a human.
+.. figure:: images/digital_twin_hierarchy.png
+ :width: 500px
+ :align: center
+ :figclass: align-center
+ :alt: Hierarchy of digital twins
+
+ A hierarchy of digital twins. Each blue circle represents a twin, coupled to its neighbours. Yellow nodes are where
+ schema are used to connect twins.
+
There are three reasons why you might want to create a digital twin:
- Monitoring
- Prediction
@@ -34,14 +53,6 @@ Coupling digital twins is generally even more useful. You might wish to couple y
of the local power grid, and a representation of a factory building to determine power demand... enabling you to
optimise your factory plant for lowest energy cost whilst intelligently selling surplus power to the grid.
-.. figure:: images/placeholder.png
- :width: 500px
- :align: center
- :figclass: align-center
- :alt: Just a figure placeholder for the time being
-
- A hierarchy of digital twins. Each circle represents a twin, coupled to its neighbours.
-
.. _aims:
Aims
@@ -50,7 +61,14 @@ Aims
**twined** provides a toolkit to help create and validate "schema" - descriptions of a digital twin, what data it
requires, what it does and how it works.
-You'll find an in depth description in the :ref:`schema` section.
+The goals of **twined** are as follows:
+ - Provide a clear framework for what a digital twin schema can and/or must contain
+ - Provide functions to validate incoming data against a known schema
+ - Provide tools to create schema describing what you require
+ - Provide a function to check that a schema itself is valid
+
+Using schema, we can describe how digital twins connect and interact... building them together in hierarchies and
+networks. You'll find an in depth description in the :ref:`schema` section.
.. _reason_for_being:
diff --git a/docs/source/schema.rst b/docs/source/schema.rst
index 614ea59..001d9f8 100644
--- a/docs/source/schema.rst
+++ b/docs/source/schema.rst
@@ -4,7 +4,11 @@
Schema
======
-This is the core of **twined**.
+This is the core of **twined**, whose whole purpose is to provide and use schemas for digital twins..
+
+.. _requirements:
+Requirements of digital twin schema
+===================================
A *schema* defines a digital twin, and has multiple roles. It:
@@ -19,35 +23,23 @@ If this weren't enough, the schema:
#. Must be human-readable
#. Must be searchable/indexable
+Fortunately for digital twin developers, many of these requirements have already been seen for data interchange formats
+developed for the web. **twined** uses `JSON` and `JSONSchema` to interchange data between digital twins. If you're not
+already familiar with JSONSchema (or wish to know why **twined** uses `JSON` over the seemingly more appropriate `XML`
+standard), see :ref:`introducing_json_schema`.
-.. _schema_json:
-Using JSON Schema
-=================
-
-Fortunately for digital twin developers, many of these
-
-.. tabs::
-
- .. code-tab:: py
- import numpy as np
- import es
+.. _specifying_a_framework:
+Specifying a framework
+======================
- def main():
- pass
-
-
-.. _why_not_xml:
-Why not XML
------------
-
-In a truly `excellent three-part blog`_
+We cannot simply expect many developers to create digital twins with a `JSONSchema` then to be able to connect them all
+together. **twined** makes things slightly more specific
.. toctree::
:maxdepth: 0
:hidden:
- turbulence_coherent_structures
- turbulence_wind
- turbulence_tidal
+ schema_introducing_json
+
diff --git a/docs/source/schema_introducing_json.rst b/docs/source/schema_introducing_json.rst
new file mode 100644
index 0000000..84c8644
--- /dev/null
+++ b/docs/source/schema_introducing_json.rst
@@ -0,0 +1,118 @@
+.. _introducing_json_schema:
+
+=======================
+Introducing JSON Schema
+=======================
+
+``JSON`` is a data interchange format that has rapidly taken over as the defacto web-based data communication standard
+in recent years.
+
+``JSONSchema`` is a way of specifying what a ``JSON`` document should contain. The Schema are, themselves, written in
+``JSON``!
+
+Whilst schema can become extremely complicated in some scenarios, they can also become quite succinct. See below for the
+schema (and matching ``JSON``) for an integer and a string variable.
+
+.. tabs::
+
+ .. tab:: JSON
+ {
+ "id": 1,
+ "name": "Tom"
+ }
+
+ .. tab:: Schema
+ {
+ "type": "object",
+ "title": "An id number and a name",
+ "properties": {
+ "id": {
+ "type": "integer",
+ "title": "An integer number",
+ "default": 0
+ },
+ "name": {
+ "type": "string",
+ "title": "A string name",
+ "default": ""
+ }
+ }
+ }
+
+.. list-table:: Some useful resources for JSON Schema
+ :widths: auto
+ :header-rows: 1
+
+ * - https://jsonschema.net/
+ - Useful web tool for inferring schema from existing json
+ * - https://jsoneditoronline.org
+ - A powerful online editor for json, allowing manipulation of large documents better than most text editors
+ * - https://www.json.org/
+ - The JSON standard spec
+ * - https://json-schema.org/
+ - The (draft standard) JSONSchema spec
+ * - https://rjsf-team.github.io/react-jsonschema-form/
+ - A front end library for generating webforms directly from a schema
+
+
+.. _human_readbility:
+Human readability
+=================
+
+Back in our :ref:`requirements` section, we noted it was important for humans to read and understand schema.
+
+The actual documents themselves are pretty easy to read by technical users. For non technical users, readability can be
+enhanced even further by the ability to turn ``JSONSchema`` into web forms automatically. For our example above, we can
+autogenerate a web form straight from the schema:
+
+.. figure:: images/schema_form_example.png
+ :width: 500px
+ :align: center
+ :figclass: align-center
+ :alt: Web form from an example schema
+
+ Web form generated from the example schema above.
+
+Thus, we can take a schema (or a part of a schema) and use it to generate a control form for a digital twin in a web
+interface without writing a separate form component - great for ease and maintainability.
+
+
+.. _why_not_xml:
+Why not XML
+===========
+
+In a truly excellent `three-part blog `_, writer Seva Savris takes us
+through the ups and downs of ``JSON`` versus ``XML``; well worth a read if wishing to understand the respective technologies
+better.
+
+In short, both ``JSON`` and ``XML`` are generalised data interchange specifications and can both can do what we want here.
+We choose ``JSON`` because:
+
+#. Textual representation is *much* more concise and easy to understand (very important where non-developers like
+ engineers and scientists must be expected to interpret schema)
+
+#. `Attack vectors `_. Because entities in ``XML``
+ are not necessarily primitives (unlike in ``JSON``), an ``XML`` document parser in its default state may leave a system
+ open to XXE injection attacks and DTD validation attacks, and therefore requires hardening. ``JSON`` documents are
+ similarly afflicated (just like any kind of serialized data) but default parsers, operating on the premise of only
+ deserializing to primitive types, are safe by default - it is only when nondefault parsering or deserialization
+ techniques (such as ``JSONP``) are used that the application becomes vulnerable. By utilising a default ``JSON`` parser
+ we can therefore significantly shrink the attack surface of the system. See
+ `this blog post `_ for further discussion.
+
+#. ``XML`` is powerful... perhaps *too* powerful. The standard can be adapted greatly, resulting in high encapsulation
+ and a high resilience to future unknowns. Both beneficial. However, this requires developers of twins to maintain
+ interfaces of very high complexity, adaptable to a much wider variety of input. To enable developers to progress, we
+ suggest handling changes and future unknowns through well-considered versioning, whilst keeping their API simple.
+
+#. ``XML`` allows baked-in validation of data and metadata. Whilst advantageous in some situations, this is not a
+ benefit here. We wish validation to be one-sided: validation of data accepted/generated by a digital twin should be
+ occur within (at) the boundaries of that twin.
+
+#. With ``JSON`` Schema, we can add the majority of the required validation capabilities (otherwise missing from JSON
+ but present in ``XML``) to ``JSON`` documents, with our schema specified where we need them.
+
+#. ``JSON`` is a much more compact expression than XML, significantly reducing memory and bandwidth requirements. Whilst
+ not a major issue for most modern PCS, sensors on the edge may have limited memory, and both memory and bandwidth at
+ scale are extremely expensive. Thus for extremely large networks of interconnected systems there could be significant
+ speed and cost savings.