@ -10,7 +10,7 @@ But unfortunately, we did not have enough time for now to test it with a screen
We will do so in the coming months in order to offer you the best experience if you have special needs for accessibility.
#### About translation
### About translation
Our apps are available in several languages, but we are still in the process of establishing a reliable translation mechanism, and for now, only the German translation is available.
@ -44,7 +44,7 @@ This Identifier is a valid URI that can be used to link a document with another
It follows the **DID** (Decentralized Identifier) format, and an adhoc DID Method will be specified and registered shortly.
#### Type of a Document (primary class)
### Type of a Document (primary class)
When you create a new Document, you first have to select its **type**, which is also called "primary class" internally.
@ -65,7 +65,7 @@ Here is a short list of the most used types :
In order to create a new Document, you can use the "plus" button on the main screen of the App.
#### Viewer, Editor and Apps
### Viewer, Editor and Apps
A document can be opened in
@ -88,7 +88,7 @@ Viewers and Editors are what we call "Apps". And they can be installed from the
NextGraph comes with a set of Official Apps (listed in [Features](/en/features)) that are always available (they don't need to be installed), and developers can also create new apps, that will need to be installed by the final user (but when the user receives a link to a Document for which they don't have the necessary app installed, we will propose them to install this missing app automatically).
#### History
### History
Each document keeps track of the whole history of modifications. This is accessible from the History pane, from within the Document menu.
@ -24,7 +24,7 @@ Here is the breakdown of the problem.
### No more DNS, TLS nor HTTPS
DNS and TLS certificates are not fully decentralized and they both rely on some single points of failure (and domains are expensive, and hard to setup and manage for the end-user). TLS was discarded by the creator of Signal Protocol by example, because his main goal was to offer a secure and totally decentralized chat protocol. We also have to forgo DNS and TLS in our architecture, for similar reasons. That's not an easy task. Matrix, by example, that is just another iteration on the above mentioned Signal Protocol (reimplemented in permissive licensing, and with a slightly different protocol for group encryption), felt the need to wrap all the E2EE protocol within some classical REST apis with TLS and a domain name, so basically they voided the advantage that Signal had created: no need for DNS nor TLS certificates. The result is Synapse protocol and Home Server: a mix of E2EE and plain old TLS APIs. That's not what we did. In our protocol, every peer is known by its IP and a PeerID that is a public key. There is no DNS, there is no TLS certificate. We use the Noise protocol for encryption of communication between peers, which is, for now, channeled into a WebSocket, but could be transported over other protocols, including UDP or QUIC, by example.
DNS and TLS certificates are not fully decentralized and they both rely on some single points of failure (and domains are expensive, and hard to setup and manage for the end-user). TLS was discarded by the creator of Signal Protocol by example, because his main goal was to offer a secure and totally decentralized chat protocol. We also have to forgo DNS and TLS in our architecture, for similar reasons. That's not an easy task. Matrix, by example, that is just another iteration on the above mentioned Signal Protocol (reimplemented in permissive licensing, and with a slightly different protocol for group encryption), felt the need to wrap all the E2EE protocol within some classical REST apis with TLS and a domain name, so basically they voided the advantage that Signal had created: no need for DNS nor TLS certificates. The result is Synapse protocol and Home Server: a mix of E2EE and plain old TLS APIs. That's not what we did. In our protocol, every peer is known by its IP and a PeerID that is a public key. There is no DNS, there is no TLS certificate. We use the Noise protocol for encryption of communication between peers, which is, for now, channeled into a WebSocket, but could be transported over other protocols, including UDP, QUIC or WebRTC, by example.
### P2P isn't viable. we need 2-Tier network with Brokers
@ -36,7 +36,7 @@ Now comes another problem. If the concept of a “server” is back in the pictu
### Group encryption is not enough
All 3 existing protocols I just mentioned, are derived from the first one: double ratchet by Moxie Marlinspike et al. This protocol is very good at one thing: enforce privacy for the participants **within the group**. And prevent any other agent that is **outside of the group**, from seeing any plaintext (the messages in clear, unencrypted form). The guarantees are simple: Or you are inside the group and you can see everything within this group. Or you are outside of the group and you cannot see anything. Very nice! Very useful. Everybody uses it on a daily basis, in WhatsApp, by example. In addition, it adds a guarantee called Perfect Forward Secrecy (PFS) which has a negative side-effect for newcomers that will join the group later on (that are invited to join after a while). hey will not be able to see the historical content of the group. That's good for paranoid people who are afraid a compromised key would let unauthorized people see all the past conversation. And it also is based on the concept that this compromised key would be detected, and the intruder would be kicked out fast enough so he doesn’t see any newer messages neither (that's Post Compromise Security), which is another problem difficult to solve. Anyway, it turns out that PFS is an anti-feature in our case, because we obviously want a joining collaborator to **have access to all the historical data** of a DAG of modification of a document. If they wouldn't have that, they wouldn't be able to reconstruct the document's content at all. This is a problem that Matrix is facing. So basically, we do not want PFS. And this problem is being addressed in a [new draft specification called MIMI](https://datatracker.ietf.org/group/mimi/about/), a working group of the IETF. But even if this is solved, I am afraid it will not be enough for our use cases.
All 3 existing protocols I just mentioned, are derived from the first one: double ratchet by Moxie Marlinspike et al. This protocol is very good at one thing: enforce privacy for the participants **within the group**. And prevent any other agent that is **outside of the group**, from seeing any plaintext (the messages in clear, unencrypted form). The guarantees are simple: Or you are inside the group and you can see everything within this group. Or you are outside of the group and you cannot see anything. Very nice! Very useful. Everybody uses it on a daily basis, in WhatsApp, by example. In addition, it adds a guarantee called Perfect Forward Secrecy (PFS) which has a negative side-effect for newcomers that will join the group later on (that are invited to join after a while). They will not be able to see the historical content of the group. That's good for paranoid people who are afraid a compromised key would let unauthorized people see all the past conversation. And it also is based on the concept that this compromised key would be detected, and the intruder would be kicked out fast enough so he doesn’t see any newer messages neither (that's Post Compromise Security), which is another problem difficult to solve. Anyway, it turns out that PFS is an anti-feature in our case, because we obviously want a joining collaborator to **have access to all the historical data** of a DAG of modification of a document. If they wouldn't have that, they wouldn't be able to reconstruct the document's content at all. This is a problem that Matrix is facing. So basically, we do not want PFS. And this problem is being addressed in a [new draft specification called MIMI](https://datatracker.ietf.org/group/mimi/about/), a working group of the IETF. But even if this is solved, I am afraid it will not be enough for our use cases.
Like with the double ratchet, we want to renew epoch from time to time. Specially when we revoke the access of a specific user. In this case, the encryption keys need to be refreshed. We can also do so in a periodic manner, for extra security. Another reason why existing group E2EE protocols are not adapted for us, is that the “all or nothing“ access pattern is not what we need neither.
@ -58,9 +58,9 @@ A Document in NextGraph is composed of 3 parts :
>
> 3 CRDT models in 1
NextGraph combines together those 3 CRDT models in order to benefit from all the advantages of each one. As you will see below, they are complementary and the developer of an app using our framework, can decide which model to use based on the data requirements of the app. We tightly integrated the 3 models in order to normalize the APIs and to offer an **interoperable, unified and feature-rich data layer** to the developer.
NextGraph combines together those 3 CRDT models in order to benefit from all the advantages of each one. As you will see below, they are complementary and the developer of an app using our framework, can decide which model to use based on, depending on the data requirements of the app. We tightly integrated the 3 models in order to normalize the APIs and to offer an **interoperable, unified and feature-rich data layer** to the developer.
As you will see in the **branch** section below, the programmer decides which CRDT model to use, not at the Document level, but at the Branch level. As Documents can be composed of many branches (that act like "blocks"), you are not restricted to one model or another. Your application can use the 3 CRDT models combined inside one Document, hence benefiting from all the features offered by each model. Even more, you can divide your data into several sections, and use a different block for each one, specifying which Discrete model to use block by block. Remember that in any case the Graph model is included by default in every block. So the question to ask yourself is which of the Automerge or Yjs model you want to use for the Discrete part of the block. Eventually, all the data blocks of your document are available as one to your application, and can be queried, mutated, and read seamlessly. More on that below in the section about the APIs.
As you will see in the **Sync Protocol** chapter below, the programmer decides which CRDT model to use, not at the Document level, but at the Branch level. As Documents can be composed of many branches (that act like "blocks"), you are not restricted to one model or another. Your application can use the 3 CRDT models combined inside one Document, hence benefiting from all the features offered by each model. Even more, you can divide your data into several sections, and use a different block for each one, specifying which Discrete model to use block by block. Remember that in any case the Graph model is included by default in every block. So the question to ask yourself is which of the Automerge or Yjs model you want to use for the Discrete part of the block. Eventually, all the data blocks of your document are available as one to your application, and can be queried, mutated, and read seamlessly. More on that below in the section about the APIs.
Now let's have a look at what those CRDTs have in common and what is different between them. We have marked 🔥 the features that are unique to each model and that we find very cool.
@ -14,13 +14,13 @@ Here we will detail the DID method and its format, and how it relates to RDF.
Most of the identifiers used in this scheme are of the PubKey, SymKey or Digest types, which are all 32 bytes arrays. They are all preceded by a byte detailing the version number of the format, which is zero at the moment.
The byte array is reversed, and for this reason all the IDs end with the A letter. The arrays are encoded into base64_url string and always have 44 characters. Here is an example of an ID : `JQ5gCLoX_jalC9diTDCvx-Wu5ZQUcYWEE821nhVRMcEA`
The byte array is reversed, and for this reason all the IDs end with the A letter. The arrays are encoded into base64_url strings and always have 44 characters. Here is an example of an ID : `JQ5gCLoX_jalC9diTDCvx-Wu5ZQUcYWEE821nhVRMcEA`
We will use here the placeholder `[XXX]` to denote one of those IDs in the format, and explain which part it is for.
Those IDs and Keys will be combined in different ways detailed below, in order to form different types of capabilities and links.
#### capabilities
### Capabilities
Some special format that need explanation :
@ -54,7 +54,7 @@ We omit here the prefix did:ng as it is common to all the schemes.
overlay and peers can be omitted if the capability is about a repo/object that belongs to the same store.
#### Nuri stored in triplestore
### Nuri stored in triplestore
When those capabilities are stored inside an RDF document, they are decomposed into several parts, and each part is inserted as a separate triple. Here more details :
@ -92,7 +92,7 @@ The decomposition into several triples enables to deduplicate some information (
We should probably mention here also that NextGraph is fully compatible with `<http(s)://…>` URIs and that they can coexist in any Document. `<ng:includes>` might work for http resources that can be dereferenced online with a GET, but we are not going to implement that right now (not a priority) and `<ng:subscribe>` will never work for those URLs, but we thought of using `<ng:refresh> "3600“ ` and `<ng:cache> “3600"` instead, which would refresh periodically the dereferenced resource in the former case, every hour, or would cache the resource after the first dereferencing for a period of 1h in the later case, but then would delete the cache to save space and would only dereference again if need be (before processing any query on the resource) and cache again for another hour. those 2 addition predicate are not planned for now as they are not a priority.
#### Identifiers
### Identifiers
Here are the identifiers that can be used to refer to any resource anywhere in the graph. they are unique global identifiers. You can see that they are all (except users) suffixed with the overlayid, which reduces the risk of collision.
@ -108,7 +108,7 @@ Here are the identifiers that can be used to refer to any resource anywhere in t
`did:ng:o:[repoid]` can be omitted when the identifier is understood as being within a specified named graph, or when using a BASE in queries.
#### Nuri in SPARQL
### Nuri in SPARQL
The graph part of any quad in NextGraph is reserved. The GSP (Graph Store Protocol) is not accessible by any client. Still, it is possible to use the graph part in SPARQL Query and SPARQL Update, with some limitations :
@ -140,13 +140,14 @@ The graph part of any quad in NextGraph is reserved. The GSP (Graph Store Protoc
when no default graph is included in the Query (with USING, GRAPH, FROM), the target passed in the App API call is used. Target URIs given in the following table can also be used in the graph part of a SPARQL query. Target can have the form :
@ -173,7 +174,7 @@ for all the above URIs that are stores, adding a trailing :r will restrict the g
| Follower | :h | list of followers |
| Following | :y | list of following |
#### context and ontologies
### Context and ontologies
As shown above, there is a Context branch in each Document.
@ -185,7 +186,7 @@ It expresses the mapping of prefixes to the URI of the ontologies used in the do
In order to see and modify the triples of the context, the suffix `:x` should be added at the end of the URI of the document, as this is the shortcut to access the context branch.
#### binary files
### Binary files
Binary files can be uploaded to an overlay, and then linked to a specific branch of a repo.
@ -205,7 +206,7 @@ Once this is done, there are 4 cases on how to use those files within the branch
All the files of a branch (added with the AddFile commit) will be listed by the meta predicate `<ng:f>`
@ -4,17 +4,17 @@ description: Describe the Schema of your data with a set of Semantic Ontologies
layout: ../../../layouts/MainLayout.astro
---
As explained in the previous chapter about the [Semantic Web and Ontologies](/en/framework/semantic), NextGraph is based on RDF, and OWL is used to defined Ontologies, which are equivalent to a Schema definition.
As explained in the previous chapter about the [Semantic Web and Ontologies](/en/framework/semantic), NextGraph is based on RDF, and OWL is used to defined Ontologies, which are equivalent to a Schema definitions.
Every document can list a set of prefixes and associated ontology that the Document is using.
This is done with the `context` branch internally and is accessible from the document Menu, under Tools, then Schema. (not implemented for now).
This is done with the `context` branch internally and is accessible from the Document Menu, under Tools, then Schema. (not implemented for now).
The schema is defined at the Document level, not at the branch or block level.
It can updated at any time, and prefixes can be removed too, that will not affect the predicates that are using it, as all predicates are encoded and saved with their full URI anyway.
It can be updated at any time, and prefixes can be removed too, that will not affect the predicates that are using them, as all predicates are encoded and saved with their full URI anyway.
The context is useful for SPARQL Queries and for JSON-LD output.
The context is useful for SPARQL Queries and for JSON-LD format.
JSON-LD is not available yet but will be included in an upcoming release.
@ -23,17 +23,17 @@ The list is detailed below. This prefix cannot be overridden.
In this `ng` ontology, we also define the primary classes of all the types of documents that are officially supported in our Apps.
We also can expose some common prefixes if requested, that are listed a bit below.
We can also expose, on request, some common prefixes that are listed a bit below.
And in general we strive to map our official primary classes with existing ontologies for backward compatibility. You are encouraged too to reuse existing ontologies or directly in your prefixes, or by inheriting from them in your own ontology definitions.
And in general we strive to map our official primary classes with existing ontologies for backward compatibility. You are encouraged too to reuse existing ontologies, directly in your prefixes, or by inheriting from them in your own ontology definitions.
We will also keep a repository of wellknown ontologies of specific interest.
We will also keep a repository of well-known ontologies of specific interest.
A new ontology can be defined by creating a new Document of type Data / Ontology (not available yet)
### ng ontology
There is a special prefix ng: for the NextGraph ontology (not to be confused with the did:ng method). It is available in all RDF documents and cannot be overridden by other prefixes/context.
There is a special prefix `ng:` for the NextGraph ontology (not to be confused with the `did:ng` method of the Nuri). This prefix is available in all RDF documents and cannot be overridden by other prefixes/context.
It has a list of predicates that help manage the Documents. It is also a way for us to offer a metadata API on each document, that can be queries with SPARQL. This API automatically generates some virtual triples about the document. let's have a look more in details about them.
@ -77,7 +77,7 @@ Apart from `ng:f`, `ng:g`, `ng:p` and `ng:q`, all the other predicates sit in th
see [Features](/en/features) for a list of all official primary classes
@ -77,17 +77,17 @@ Then some specialized ontologies have also emerged, often created in cooperation
They form some **shared schema** that has been agreed globally and that can be reused, and amended of course if need, by anybody.
If need be, it is always possible to define also your own ontologies. if they are of any interest to others, they might be published too, and reused.
If need be, it is always possible to define also your own ontologies. And if they are of any interest to others, they might be published too, and reused.
This mechanism tends to foment **interoperability**.
First of all because the technology itself of predicate encoded as URIs is very much supporting interoperability of itself.
First of all because the technology itself of predicates encoded as URIs is very much supporting interoperability in and of itself.
But also because groups of interest tend to gather and establish standard ontologies in many fields of concern, which enhance even more interoperability and portability of data.
At NextGraph, we strive to gather the best existing ontologies out there and propose them to you so you can reuse them. We also make it easy for you to create new ones with graphical tools and editors, so you don't have to have a headache when trying to understand exactly how OWL works. If you know about UML, object-oriented programming, or modelling of data, then you can easily create new ontologies. **It is all about defining classes, properties, and relationships between them**.
One last word about RDF and ontologies: because the schema of data is encoded inside in each triple (in the predicate part), there is no need to keep track of the schema of your data, as we normally do with relational databases or even in JSON. The advantage of RDF is that predicates get assigned with globally unique identifiers too, so there is never any ambiguity about the schema of the data. No separate schema definition that sits outside of the data itself (with problems to keep the 2 in sync). No migrations needed. No data inconsistency neither.
One last word about RDF and ontologies: because the schema of data is encoded inside each triple (in the predicate part), there is no need to keep track of the schema of your data, as we normally do with relational databases or even in JSON. The advantage of RDF is that predicates get assigned with globally unique identifiers too, so there is never any ambiguity about the schema of the data. No separate schema definition that sits outside of the data itself (with problems to keep the 2 in sync). No migrations needed. No data inconsistency neither.
### SPARQL
@ -117,17 +117,17 @@ When you are using the native app, all your documents of all your stores, are al
While for the webapp, you only get to have locally the documents that you manually opened since the last login. This is because the webapp, for now, cannot store locally all your documents, because there is not enough room for that. This will be improved at some point, but it needs more work on our side.
In the future, we will also be able to run federated queries, which means that part of all of the query is gonna be ran on someone else's data, remotely. This is not ready yet, but that's the goal of NextGraph. If we want to query the social graph, by example, we have to go to out contacts, friends, followers and run some queries there on their data.
In the future, we will also be able to run federated queries, which means that part or all of the query is gonna be ran on someone else's data, remotely. This is not ready yet, but that's the goal of NextGraph. If we want to query the social graph, by example, we have to go to our contacts, friends, followers and run some queries there on their data.
Of course, this will only work if we got the permission to run those remote queries. And about that you should read our chapter about [permissions](/en/framework/permissions).
In the same manner, we just explained that when you query with the "Query all docs", you directly have access to all your local documents. First of all, we have to be precise and say that the set of documents you have access to is by user/identity. If you have several Identities in your wallet, then only the current identity will be queried.
Secondly, we have to clarify also that only the official apps can have such unlimited access to all your documents. This is because those apps have been coded and audited by us, they are open source, and we know they are ot going to do malicious things with your data. They will never connect to remote machines and send your data there. They will never gather statistics or tracking on you. They can only manipulate your data locally, and they have to behave! you also trust those apps because you trust us. If you wouldn't trust us in general, then there would be absolutely no point in using our products. Your trust though is not "requested" from you. You can easily check our claims about security, privacy and encryption, as all our code is open source, and you can also compile it yourself, as ask an export programmer to audit it or compile it for you.
Secondly, we have to clarify also that only the official apps can have such unlimited access to all your documents. This is because those apps have been coded and audited by us, they are open source, and we know they are not going to do malicious things with your data. They will never connect to remote machines and send your data there. They will never gather statistics or tracking on you. They can only manipulate your data locally, and they have to behave! you also trust those apps because you trust us. If you wouldn't trust us in general, then there would be absolutely no point in using our products. Your trust though is not "requested" from you. You can easily check our claims about security, privacy and encryption, as all our code is open source, and you can also compile it yourself, or ask an expert programmer to audit it or compile it for you.
Then, when you install third party apps, those apps will NOT get unlimited access to all your data. Those applications will have to request permissions from you, before being able to read or write some of your data. At nay moment, you can revoke this grant. More about that in the [permissions](/en/framework/permissions) chapter.
Then, when you install third party apps, those apps will NOT get unlimited access to all your data. Those applications will have to request permissions from you, before being able to read or write some of your data. At any moment, you can revoke this grant. More about that in the [permissions](/en/framework/permissions) chapter.
Those 3rdparty apps are mostly safe, because we also review them. But because you also have the option to bypass the App Store and install any app that you want, those apps will obviously not be reviewed by us, so as a matter of principle, any thirdparty app needs to present some capability in order to access your data, even if you are the author of such app.
Those 3rd-party apps are mostly safe, because we also review them. But because you also have the option to bypass the App Store and install any app that you want, those apps will obviously not be reviewed by us, so as a matter of principle, any third-party app needs to present some capability in order to access your data, even if you are the author of such app.
It should be noted that permissions can span a whole UserStorage, or a whole Store, or a set of Documents, or even, for read permission only, a specific branch or block.
@ -137,13 +137,13 @@ As we already mentioned shortly when we talked about blocks [here](/en/documents
This is very handy when you are in Document A, and you need to access some extra data coming from another Document or Branch B, and you want to make sure that anybody who will read the current Document A, will also fetch and include the other Document or Block B automatically. If you have some logic in your document tha depends on such data, in a SPARQL query by example, this **include** mechanism will solve the headache of fetching and caching the foreign data.
The included block can be from the ame document, from another document in the same store, or not, and even in someone else's document, on a remote machine. hanks to the pub/sub and synchronization mechanism of NextGraph, this foreign block will always stay up to date aas it will synchronize with the original source.
The included block can be from the same document, from another document in the same store, or not, and even in someone else's document, on a remote machine. Thanks to the pub/sub and synchronization mechanism of NextGraph, this foreign block will always stay up to date as it will synchronize with the original source.
### Named graphs and blank nodes
And this leads us to an explanation about what happens to named graphs in NextGraph.
Named Graphs are an RDF and SPARQL feature that lets you organize your triples into a bag. This bag contains your triples, and we can this bag a Graph. it also gets an ID in the form of a URI (URL normally. In NextGraph, a Nuri).
Named Graphs are an RDF and SPARQL feature that lets you organize your triples into a bag. This bag contains your triples, and we call this bag a Graph. it also gets an ID in the form of a URI (URL normally. In NextGraph, a Nuri).
SPARQL has options to specify which named graph(s) you want the query to relate to.
@ -153,25 +153,25 @@ NextGraph is a quadstore, but there are some limitations.
We do not let the user create graphs manually and arbitrarily. Instead, we associated each new resource/document (with its unique subject ID of the form `did:ng:o:...`) to a new graph, **of the same name as the resource**.
Even creating a new resource od document doesn't happen freely in the quadstore. Instead, there is a special API call for creating a new document, that must be called before any triple can be inserted in this Document. THis API call return the newly generated document ID.
Even creating a new resource or document doesn't happen freely in the quadstore. Instead, there is a special API call for creating a new document, that must be called before any triple can be inserted in this Document. This API call returns the newly generated document ID.
Then it is possible to add new triples in the this Document, and the ID of the document has to be passed to the SPARQL query, as a named graph, or as an argument in the API call itself. This way, we always know in which named graph the data should be saved or retrieved from.
In this Document/Named Graph, the user can add triples, and most of the time, they will add triples that have this Document ID as subject. That's what we call **authoritative triples** because we know that the subject is the same ID as the named graph, (as the document ID) and because we have signatures on every commit and also threshold signatures too, then we can prove that those triples have been authored by the users that claim to be members of such document.
In this Document/Named Graph, the user can add triples, and most of the time, they will add triples that have this Document ID as subject. That's what we call **authoritative triples** because we know that the subject is the same ID as the named graph, (as the document ID) and because we have signatures on every commit and also threshold signatures too, then we can prove that those triples have been authored by the users that claim to be editors of such document.
In order to facilitate adding those kind of authoritative triples with a SPARQL UPDATE, or to retrieve them with a SPARQL QUERY, the user has access to the BASE shortcut, which is `<>` in SPARQL, and that represents the current document. it will be replaced internally by the exact ID of the current document. This placeholder is handy and helps you manipulate the authoritative triples of your document. The default graph of any SPARQL Query is also the current Document, so you do not need to specify it explicitly (except when you select the "Query all docs" option, i this case, the default graph is the union graph of all the graphs).
In order to facilitate adding those kind of authoritative triples with a SPARQL UPDATE, or to retrieve them with a SPARQL QUERY, the user has access to the BASE shortcut, which is `<>` in SPARQL, and that represents the current document. it will be replaced internally by the exact ID of the current document. This placeholder is handy and helps you manipulate the authoritative triples of your document. The default graph of any SPARQL Query is also the current Document, so you do not need to specify it explicitly (except when you select the "Query all docs" option, in this case, the default graph is the union graph of all the graphs).
If we had stopped here, there would be no real interest in having a named graph mechanism.
But you also are able to add triples in the Document/Named graph, that are not authoritative. Those are the triples that have as subject, some other ID than the current Document.
What is it useful for? RDF let's anybody establish facts about any resources. If there is a foreign Document that I am using in my system, and I want to add extra information about this resource, but I don't have write permission on that foreign Document, I can add the triples in one of the Documents that I own. External people who would see those triples that I added, would immediately understand that they are not authoritative, because they were not signed with the private key of the Document ID that they establish facts about (the subject of the triples). So it is possible to say, by example, that `London -> belongs_to -> Africancontinent` but of course, this is not the official point of the view of the author that manages the `London` Document. it only is "my point of view", and people who will see this triple, will also be notified that it isn't authoritative (I think they can easily understand that by themselves without the need for signatures).
What is it useful for? RDF let's anybody establish facts about any resources. If there is a foreign Document that I am using in my system, and I want to add extra information about this resource, but I don't have write permission on that foreign Document, I can add the triples in one of the Documents that I own. External people who would see those triples that I added, would immediately understand that they are not authoritative, because they were not signed with the private key of the Document ID that they establish facts about (the subject of the triples). So it is possible to say, by example, that `London -> belongs_to -> African_continent` but of course, this is not the official point of the view of the author that manages the `London` Document. it only is "my point of view", and people who will see this triple, will also be notified that it isn't authoritative (I think they can easily understand that by themselves without the need for signatures).
Then we have other use cases for extra triples in the Document :
- fragments, that are prefixed with the authoritative ID, and followed by a hash and a string (like in our previous example `#label`).
- blank nodes that have been skolemized. They get a Nuri of the form `did:ng:o:...:u:...`. this is because blank nodes cannot exist in a local-first system, as we needto give them a unique ID. This is done with the [skolemization procedure](https://www.w3.org/TR/rdf11-concepts/#section-skolemization). For the user or programmer, skolemization is transparent. You can use blank nodes in SPARQL UPDATE and they will be automatically translated to skolems. For SPARQL QUERY anyway, blank nodes are just hidden variables, so there is no impact.
- blank nodes that have been skolemized. They get a Nuri of the form `did:ng:o:...:u:...`. this is because blank nodes cannot exist in a local-first system, as we needto give them a unique ID. This is done with the [skolemization procedure](https://www.w3.org/TR/rdf11-concepts/#section-skolemization). For the user or programmer, skolemization is transparent. You can use blank nodes in SPARQL UPDATE and they will be automatically translated to skolems. For SPARQL QUERY anyway, blank nodes are just hidden variables, so there is no impact.
But those extra triples (fragments and skolems) are all prefixed with the authoritative ID, so they are considered authoritative too.
For unsupported devices, we offer a web version at [nextgraph.eu](https://nextgraph.eu), and will also provide a local install based on ngd soon.
#### Create a Wallet
### Create a Wallet
The first step that is waiting for you when you start using our apps, is to create a Wallet for yourself.
@ -30,17 +30,17 @@ We have made the transfer of the wallet easy, and you have several options. The
If this is not available to you (if none of your devices has a camera) then you can use the TextCode option, or transfer your Wallet File with a USB key. Those other options are also described inside the app. You can also find more information about that in the [Wallet section](/en/wallet) here below.
#### Choose a Broker
### Choose a Broker
All the apps (native or web) need to have a Broker configured in order to operate well. This is due to the **2-tier** decentralized peer-to-peer network of NextGraph.
When you create your wallet, you will be asked to select a Broker. This is a server that is running 24/7 and that will help you synchronize your data with all your devices and with other users.
For now, we only offer you one Broker (nextgraph.eu) located in France. In the future, there will be other options too with Brokers available in other countries, and also with the option to self-host your own broker.
For now, we only offer you one Broker (nextgraph.eu) located in Germany. In the future, there will be other options too with Brokers available in other countries, and also with the option to self-host your own broker.
You will be able to change your broker later on. Your data will move to the new broker and all your documents will be accessible from the new broker. With NextGraph, all your data is totally **portable** and there is no fear to have with being locked-in with one provider or another. All your contacts will be transparently informed that you have moved your account to another Broker and everything will work seamlessly.
#### Use the App
### Use the App
Once your wallet is created and you are entering the App main screen for the first time, you will have to learn how to use it. here is a brief introduction to the App.
@ -48,7 +48,7 @@ You have created a Wallet, and inside this wallet, there is one default `Identit
Within each Identity, your data is organized into **3 different Stores**.
##### Stores
### Stores
- the public store : is equivalent to your website, blog, or public profile on social networks. You can put in this store all the documents, pictures, videos, posts, data, etc... that you want everybody to have access to, without the need for special permissions.
@ -64,7 +64,7 @@ Then you can access your protected store with the icon that represents 2 users.
And your public profile/store can be found with the icon that represents one user.
##### Documents
### Documents
The app is based on the concept of Documents. Everything is a Document in NextGraph. Even your 3 stores' homepage are Documents themselves.
@ -86,7 +86,7 @@ Documents can be moved from one place to another within the store. You can reorg
You can read more about [Documents and Stores](/en/documents) in the corresponding section below.
##### Document Menu
### Document Menu
We bring your attention shortly on the Document's Menu that is accessible from the button with 3 vertical dots, at the top-right corner of the screen.
@ -96,7 +96,7 @@ Each Document has a double nature :
- A Document also has a _Graph_ nature, which is something new that NextGraph added (hence the name "NextGraph"). This "graph nature" of the document let's you link this document to other documents. It also let's you enter some specific data or meta-data about this document, that will be part of the Graph of all your documents. This graph is something important, that you are not used to. Social networks are all based on Graphs. The Web itself is a huge Graph. When you follow or get followed, when you like or comment on a Post, when you write a DM to someone, all this information is stored as a Graph, that connects different documents together. Later, you will probably need to _query_ this graph. This is done transparently when you want to see all your followers, and when you want to consult the **stream** of all the posts that they have published recently, or when you want to search for something. It is also used for recommendations. But in any case, what is important to understand is that internally, each Document can be linked to any other Document (like the classical Web that links webpages) and that the applications you will use on NextGraph, will also store more Graph information. Because NextGraph is local-first and decentralized, this **graph** information is available to you at all time. And if you want to see it, you can go to any Document and in the Document Menu, you can select "Graph" and you will see options to view and edit the Graph. This is a bit technical for now (you will see things like Turtle, SPARQL etc) but in the future, we will provide here some nice tools where you will be able to explore your own graph easily. The Graph-like nature is represented with a "sun" icon.
##### Viewer and Editor
### Viewer and Editor
Also from this Document Menu, you always have the option to switch from the 2 different modes:
@ -109,7 +109,7 @@ For now, only one editor is provided for each Document type, but in the future,
If you open the same document in 2 different tabs or browser windows, or with different apps (on mobile, desktop, etc), and when you edit the Document in one of the windows, it automatically updates itself in the viewer or editor that is opened in the other window(s). Try it! it works great.
But please pay attention to the fact that by default, the **live editing** mode is not activated, and instead, you have to click on the blue mark button that appears at the topright corner of the screen, in order to **save** your changes.
But please pay attention to the fact that by default, the **live editing** mode is not activated, and instead, you have to click on the blue mark button that appears at the top-right corner of the screen, in order to **save** your changes.
If you want to switch to **live editing** you can do so with the toggle button accessible from the Document Menu.
@ -119,7 +119,7 @@ Viewers and Editors are what we call "Apps". And they can be installed from the
NextGraph comes with a set of Official Apps (listed in [Features](/en/features)) that are always available, and developers can also create new apps, that need to be installed with the App Store.
##### Attachments and Files
### Attachments and Files
From the Document Menu, you will see many other options, most of them are not implemented yet, and will not do anything when clicked. They are there to tease you about the upcoming features ;)
@ -127,7 +127,7 @@ Three menu options are implemented for now : History, "Attachments and Files" an
The second one is, as its name indicates, about adding some images or any other attachment file to the Document. Images will be useful when you want to insert some picture in a Rich-Text document (not available yet. but you can already add pictures in the Attachments and Files).
##### History
### History
History is another Pane that is already implemented. It shows all the history of modifications on the Document.
You will be able (in the future) to select a specific revision and "revert" to it. Or to see more details about each modification (that are called "Commits").
@ -138,7 +138,7 @@ Once the two devices will be back online, you will see that they will automatica
You can try this between 2 tabs in your browser, or a browser tab and a native app, or 2 different native apps (desktop and android by example).
##### User Panel
### User Panel
The User Panel is another menu that is accessible from the logo of NextGraph at the top-left corner of the screen.
@ -152,7 +152,7 @@ If your internet connection is down, you can also see the status here ( there wi
The App always tries to connect to the Broker every 5 seconds, unless you have toggled down the "Personal" connection.
##### Magic carpet
### Magic carpet
You might ask yourself what the magic carpet is.
@ -161,3 +161,5 @@ It is not functional yet, but it will be something like a "clipboard" where you
But unlike the clipboard we are used to (with CMD+C and CMD+V), the Magic Carpet can keep a list of many items, not just the latest one. This is useful when you want to move things around. Also the Magic Carpet is always reachable from anywhere in the app, and let's you drag and drop things, and see the list visually.
Stay tuned for more features, by checking out the [roadmap](/en/roadmap).
And if you want to continue reading more about NextGraph, here is the next chapter, about what [Local-First](/en/local-first) really is about.
@ -17,7 +17,7 @@ We aim at becoming a serious alternative to the Big-Tech products and services,
You can read more about NextGraph on [our website](https://nextgraph.org).
#### App & Platform
### App & Platform
[Get started](/en/getting-started) with our official App by [installing it](https://nextgraph.org/download/), or using the web app at [nextgraph.eu](https://nextgraph.eu).
@ -31,7 +31,7 @@ You can find help in the [FAQ section](/en/help) where frequently asked question
If you have any more questions or want to get in touch with us, the simplest way is to join the [forum](https://forum.nextgraph.org). For bug reports, please create an account and submit a new issue in our [Gitea instance](https://git.nextgraph.org/NextGraph). Stay tuned by subscribing to our [newsletter](https://list.nextgraph.org/subscription/form).
#### Framework
### Framework
As a programmer, you can develop apps with our Framework and benefit from all the features of our platform.
@ -43,8 +43,8 @@ You can also develop **services**, based on NodeJs/Deno or Rust, and access the
Discover more about the features of our framework and [get started](/en/framework/getting-started) with your first app in the following sections.
#### Design, Reference & Specifications
### Design, Reference & Specifications
If you are curious about how NextGraph works internally, you can find more information about that in the [Design](/en/design) section.
If you are curious about how NextGraph works internally, you can find more information about that in the [Architecture](/en/architecture) section.
The reference on all our APIs and SDKs, including the specifications of our protocols and formats can be found in the [Reference](/en/specs) section.
@ -34,6 +34,6 @@ This by itself, is a big paradigm shift for the developers, who is more used to
Here the data is always accessed locally (in this sense, the backend sits in the “client” or in the “front-end" if you prefer).
It is the NextGraph protocol that deals transparently with the syncing mechanism. The developer does not need to deal with it. We provide access to a local API (in javascript by example) and data read and write happen on this local API.
It is the NextGraph protocol that deals transparently with the syncing mechanism. The developer does not need to deal with it. We provide access to a local API (in javascript by example) and data reads and writes happen on this local API.
We will come back to our [syncing protocol](/en/protocol) further down, but before that, we would like to explain our [P2P network and why everything is encrypted](/en/encryption).
@ -20,7 +20,7 @@ This protocol is available directly from the JS and Rust APIs and you do not nee
All the protocol messages are embedded inside an `AppRequest` message, and are replied by the Verifier with an `AppResponse`.
Some Requests will respond will a stream of AppResponses, while others will respond with only one.
Some Requests will respond with a stream of AppResponses, while others will respond with only one.
Streamed responses :
@ -29,6 +29,8 @@ Streamed responses :
A new session needs to be opened with the LocalBroker methods, not documented here (it will be documented in the APIs reference). Once the session is opened, the session_id needs to be passed in every request.
For a reference of the common types, please refer to the [Repo format documentation](/en/specs/format-repo/#common-types)
### AppRequest
#### Request
@ -524,9 +526,9 @@ Subscribes to all the events/commits of a branch.
The response is streamed and long-lived, until cancelled.
The first response contains some meta-data about the branch called `TabInfo`. It is used mostly bt the App to display the document header and instantiate the document's viewer.
The first response contains some meta-data about the branch called `TabInfo`. It is used mostly by the App to display the document header and instantiate the document's viewer.
Then a second response contains the **materialized state** of the document as it is known by the local Verifier.
Then a second response contains the **materialized state** of the document as it is known by the local Verifier at the moment of the subscribe request.
Later on, new updates are added to the stream as they arrive on the local replica (including from the changes made locally by the user).
@ -816,7 +818,7 @@ struct CommitInfo {
}
```
- AppHistory.history : is order with the newest commits first.
- AppHistory.history : in order, with the newest commits first. The first part of the tuple (ObjectId) is the CommitID.
- AppHistory.swimlane_state : can be discarded. it is only used by our GUI representation of the history in the Apps. Same with the x and y values in CommitInfo.
@ -874,7 +876,7 @@ AppRequestV0 {
#### Response
If the signature is immediately available, the response is `AppResponseV0::True`. The new HEADs containing the signature can be immediately fetched with a call to `SignatureStatus`.
If the signature is immediately available, the response is `AppResponseV0::True`. The new HEAD containing the signature can be immediately fetched with a call to `SignatureStatus`.
If the signature is not immediately available (because the quorum needs to sign it and it can take some time), the response is `AppResponseV0::False`. A notification will be sent to the user once the signature is ready (not implemented yet).
@ -10,7 +10,7 @@ The Client Protocol is used by the Verifier in order to contact the Broker of th
It maintain this connection throughout the session that was opened by the User (by opening the wallet in the app, by example).
From this connection, the Verifier gets al the pushed updates, after it subscribed to some branches.
From this connection, the Verifier gets all the pushed updates (called Events), after it subscribed to some topics.
The verifier also sends the updates that it wants to publish, in the form of an Event to the Pub/Sub Topic, and the Broker deals with forwarding this Event to all the other devices and users that have subscribed to this topic.
@ -127,6 +127,8 @@ enum ClientResponseContentV0 {
When an error occurs (result >= 3), the content is of the type ClientResponseContentV0::EmptyResponse
- ClientMessageContentV0::ForwardedEvent(Event) is used by the Broker when it wants to **push** the events it received from other brokers or devices, down to the Client.
