=============
Transclusions
=============

External resources are defined using @ as a prefix. The resources can be used to load data
into data sections or to reference external models or views.

In the following example the object #richard_langly is transcluded from an external object.


Immutable resources
-------------------

The resource must be content-addressed and immutable.
The current python implementation uses IPFS to retrieve external objects. The objects are stored decentralised and permanent (if pinned). The referencing servers/clients MUST pin the objects to prevent garbage collection.
https://ipfs.io/

By using 'speaking' descriptors for the resource definition (f.e. @mybestfriend) we get a usable 
notation of references to external resources.


Content identifiers
-------------------

CIDs are based on the content’s cryptographic hash. That means:

- Any difference in content will produce a different CID and
- The same piece of content added to two different IPFS nodes using the same settings will produce exactly the same CID.

By using content identifiers instead of URLs, we enforce linking between immutable objects, so the
references can never be broken.

https://docs.ipfs.io/guides/concepts/cid/


::

    @mybestfriend: 'QmPpZzmzgbpqVyqhp8qDWgDPsK4G22xUYrsNpQ5vnKtTYk'

    #person:
      first_name: 'Melvin'
      last_name: 'Frohike'
      profession: 'Developer'
      friend: @mybestfriend#richard_langly

The ZML implementation loads the external object from
http://localhost:8080/ipfs/QmPpZzmzgbpqVyqhp8qDWgDPsK4G22xUYrsNpQ5vnKtTYk

The IPFS object contains the ZML code for the object definition:

::

    #richard_langly:
      first_name: 'Richard'
      last_name: 'Langly'
      profession: 'Developer'

The object is transcluded into the property 'friend' of the object #person.

Transclusion of external defined models
---------------------------------------

In the following example the model 'person' is transcluded from an external document:

::

    &id: 'neo.codes/persons/richard_langly'
    &version: '1.0'
    &description: 'Richard Langly'
    @zmlperson: 'QmZ6s5H3zB8hJyCynKMn7WS3RQ17udZHsFbofcB3aUQBpo'
    @zmladdress: 'QmTCSMqzWZ6MvYekWpEFm7Yf9HLbDWB99vJ48xieauEE7J'
    &type: @zmlperson+person

    #first_name: 'Richard'
    #last_name: 'Langly'
    #email: 'ringo@l4ngly.org'
    #profession: 'Developer'
    #contact:
      &type: @zmladdress+address
      first_name: #first_name
      last_name: #last_name
      email: #email
    #billing_address: #contact


By using external defined models we build up an ubiquitous language of object types.