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.