TODO1: Improve this explanation. dataObject configuration could be better explained as well. Add one or more additional Hyperties development. Use more schemas and examples using them.

*TODO2: Add guidelines on what to develop according to type of problem to be addressed: App, Hyperty, Protostub or Idp Proxy. Example of questions to be addressed:

• what is the logic that is supposed to be part of the hyperty or the application?
• should I use one reporter per user (and each has a set of observers for all reporters) or should one user have one reporter and the other observers while communication through dataChilds?

Give use cases and explain how to address and what concepts to explore.*

TODO3: create issues asking for help to improve documentation

Here you may find the basic steps any developer needs to undertake to develop Hyperties. The source code of the Hello World Hyperty used as example, can be found here:

1- Clone the Hyperty Toolkit Repo, the Hyperty Repo and follow the Hyperty Toolkit Installation Guideline.

2- Create a new folder for your Hyperty at src folder and work there.

3- Select or specify the descriptor of the Hyperty Data Objects handled by your Hyperty. These descriptors are defined in JSON-Schema with suffix “.ds.json” e.g. HelloWorldDataSchema.ds.json. Let’s assume we define a simple Hello Hyperty object:

  
		{
			"$schema": "http://json-schema.org/draft-04/schema#",
			"id": "HelloObject",
			"type": "object",
			"required": ["scheme","hello"],
			"additionalProperties": false,
		  "properties": {
				"scheme": {
					"constant": "hello"
				},
				"hello": {
					"type": "string"
				}
			}
		}
	

This is optional in case you are reusing existing data schemas. In that situation, you just have to set in your Hyperty Descriptor the Catalogue URL that points to the data schema (see below).

4- Then we can start developing the Hyperty Reporter of the previously defined Hello Hyperty Object. First the constructor where we are going to instantiate the Hyperty syncher. For that, we take as input parameter the Hyperty address (HypertyURL), the MiniBus used to receive and send data synchronization messages (bus), and any required configuration data.

  
		constructor(hypertyURL, bus, configuration) {

		  let syncher = new Syncher(hypertyURL, bus, configuration);
		}
	

5- Then we prepare the creation of the Hyperty Hello Data Object by defining the Catalogue URL from where the previously defined Hyperty Data Object schema can be retrieved and initial data to be used in the creation:

  
		_this._objectDescriptorURL = 'hyperty-catalogue://example.com/.well-known/dataschemas/HelloWorldDataSchema';

		let hello = {
		   hello : "Hello World!!"
		};
 

6- The object is created and another Hyperty is invited to be an observer.

  
    syncher.create(_this._objectDescriptorURL, [invitedHypertyURL], hello).then(function(dataObjectReporter) {

    console.info('Hello Data Object was created: ', dataObjectReporter);
	

7- From the Observer side, in order to observe the Hello Data Object, it has to subscribe it, by passing its URL and the Catalogue URL from where its schema can be retrieved. As soon as the subscription is accepted the most updated version of the Hello Data Object is received

  
		syncher.subscribe(_this._objectDescriptorURL, ObjectUrl).then(function(dataObjectObserver) {}

		  console.info( dataObjectObserver);

	

8- Any change performed by the Reporter in the the object.

  
  	dataObjectReporter.data.hello = "Bye!!";
	

9- … will be immediately received by the Observer:

  
	  dataObjectObserver.onChange('*', function(event) {
	          // Hello World Object was changed
	          console.info(dataObjectObserver);
	        });
	

10- Define the Hyperty descritor. The most important attributes are:

• constraints to be fullfilled by the Runtime, in this case the only constraint is to be executed in a browser: browser: true

• hypertyType or the schemes of the data objet: "hypertyType": ["hello"]

• the catalogue URL of the data object schemas supported by the Hyperty, in this case: "dataObjects": ["https://%domain%/.well-known/dataschema/HelloWorldDataSchema"]

The complete descriptor is:

  
	{
	  "language": "javascript",
	  "signature": "",
	  "configuration": {},
	  "constraints": {
	    "browser": true
	  },
	  "hypertyType": [
	    "hello"
	  ],
	  "dataObjects": [
	    "https://%domain%/.well-known/dataschema/HelloWorldDataSchema"
	  ]
	}
	

11- develop an App to test your Hyperty by using the template used in “dev-hyperty” repo.

12- test and run your Hyperty,

start the toolkit in development mode:

  
		npm run start:dev
	

Open https://catalogue.localhost/ and accept certificate

Open https://localhost/ and select your Hyperty to be tested

Any changes performed in your Hyperty source code will be automaticaly loaded by the toolkit to be tested … Cool?

Next steps:

Have a look on available APIs to facilitate the development of powerful Hyperties like the ones available in the Hyperty Catalogue

Criteria to use Hyperties

These are guidelines to help developers decide if they should provide specific service logic as Hyperty or via a simple JavaScript library. Consider these as guidelines and not instructions. Before you embark on a new feature development, ask yourself the following questions:

– Is the feature delivery directly associated with a “User” (e.g. Human beings, physical objects, physical spaces, organizations)?

– Does the feature delivery involve communication between “Users”?

– Can the feature be delivered in cross-domain scenarios (i.e interoperability with other domains)?

If at least you have one “YES” answers to the above questions then most likely, you should go for the Hyperty Concept. Some examples are:

– Video Chat between human beings;

– a Human-being or a Data Analysis service collecting data from sensors in a Room.