@ -18,7 +18,7 @@ Each Document has a double nature :
It has a **_Document-like_** nature where you can store and edit some rich-text, plaintext, or just some JSON or XML data, according to your needs and the primary class of the Document that you have chosen when you created it. This is so far very consistent with what we expect from a document in general. All the apps that you use or develop with NextGraph, will store their data inside these Documents. The Document-like nature is represented with a "cloud" icon. A note for developers: In the internals of NextGraph, the Document-like nature of a Document is called "discrete", because otherwise it is too many things that are called "document".
It has a **_Document-like_** nature where you can store and edit some rich-text, plaintext, or just some JSON or XML data, according to your needs and the primary class of the Document that you have chosen when you created it. This is so far very consistent with what we expect from a document in general. All the apps that you use or develop with NextGraph, will store their data inside these Documents. The Document-like nature is represented with a "cloud" icon. A note for developers: In the internals of NextGraph, the Document-like nature of a Document is called "discrete", because otherwise it is too many things that are called "document".
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. The Graph part of the document is stored in the RDF format.
A Document also has a **_Graph_** nature, which is something new that NextGraph added (hence the name "NextGraph"). This "graph nature" of the document lets you link this document to other documents. It also lets 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. The Graph part of the document is stored in the RDF format.
In addition, you can also attach some **binary files** to any Document. Those files are immutable in the sense that you can add them or delete them, but you cannot modify their content.
In addition, you can also attach some **binary files** to any Document. Those files are immutable in the sense that you can add them or delete them, but you cannot modify their content.
@ -124,7 +124,7 @@ So, to recap. Each branch holds a separate list of commits, that can be seen in
For now the App does not let you create new blocks and branches, but it will come very soon. internally, the branches are already there, and they work well. What you see for now in the App when you open a document, is called the "main" branch. Later, you will be able to add more blocks and branches.
For now the App does not let you create new blocks and branches, but it will come very soon. internally, the branches are already there, and they work well. What you see for now in the App when you open a document, is called the "main" branch. Later, you will be able to add more blocks and branches.
Those who are more curious about the internals of the branch, commits, DAG (directly acyclic graph) used in NextGraph, can refer to the [Repo format](/en/specs/format-repo) of the specs.
Those who are more curious about the internals of the branch, commits, DAG (Directed Acyclic Graph) used in NextGraph, can refer to the [Repo format](/en/specs/format-repo) of the specs.
@ -65,7 +65,7 @@ As you will see in the **Sync Protocol** chapter below, the programmer decides w
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.
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.
@ -77,7 +77,7 @@ Now let's have a look at what those CRDTs have in common and what is different b
| **sequence** | ❌ \* | ✅ | ✅ |
| **sequence** | ❌ \* | ✅ | ✅ |
| <tdcolspan=3> And like in JSON or Javascript, some keys can be Arrays (aka list), which preserve the ordering of the elements. (\*) In RDF, storing arrays is a bit more tricky. For that purpose, Collections can encode order, but are not CRDT based nor concurrency safe |
| <tdcolspan=3> And like in JSON or Javascript, some keys can be Arrays (aka list), which preserve the ordering of the elements. (\*) In RDF, storing arrays is a bit more tricky. For that purpose, Collections can encode order, but are not CRDT based nor concurrency safe |
| **sets** | 🔺 multiset | ✅ | ✅ |
| **sets** | 🔺 multiset | ✅ | ✅ |
| <tdcolspan=3> RDF predicates (the equivalent of properties or keys in discrete documents) are not unique. they can have multiple values. that's the main difference between the discrete and graph models. We will offer the option to enforce rules on RDF data (with SHACL/SHEX) that could force unicity of keys, but that would require the use of **Synchronous Transactions**. Sets are usually represented in JS/JSON with a map, of which the values are not used (set to null or false), because keys are unique, so we use the keys to represent the set. In RDF, keys are not unique, but a set can be represented by choosing a single key (a predicate) and its many values will represent the set, as a pair "key/value" is unique (aka a "predicate/object" pair). |
| <tdcolspan=3> RDF predicates (the equivalent of properties or keys in discrete documents) are not unique. they can have multiple values. that's the main difference between the discrete and graph models. We will offer the option to enforce rules on RDF data (with SHACL/SHEX) that could force unicity of keys, but that would require the use of **Synchronous Transactions**. Sets are usually represented in JS/JSON with a map, of which the values are not used (set to null or false), because keys are unique, in JSON we use the keys to represent the set. In RDF, keys are not unique, but a set can be represented by choosing a single key (a predicate) and its many values will represent the set, as a pair "key/value" is unique (aka a "predicate/object" pair). |
@ -35,7 +35,7 @@ A new ontology can be defined by creating a new Document of type Data / Ontology
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.
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.
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.
@ -165,7 +165,7 @@ If we had stopped here, there would be no real interest in having a named graph
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.
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 -> 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).
What is it useful for? RDF lets 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 :
Then we have other use cases for extra triples in the Document :
@ -94,7 +94,7 @@ Each Document has a double nature :
- it has a _Document-like_ nature where you can store and edit some rich-text, or just some data, according to the class of the Document that you have chosen. This is so far very consistent with what we expect from a document in general. All the apps that you use with NextGraph, will store their data inside these Documents. The Document-like nature is represented with a "cloud" icon.
- it has a _Document-like_ nature where you can store and edit some rich-text, or just some data, according to the class of the Document that you have chosen. This is so far very consistent with what we expect from a document in general. All the apps that you use with NextGraph, will store their data inside these Documents. The Document-like nature is represented with a "cloud" icon.
- 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.
- A Document also has a _Graph_ nature, which is something new that NextGraph added (hence the name "NextGraph"). This "graph nature" of the document lets you link this document to other documents. It also lets 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
@ -158,7 +158,7 @@ You might ask yourself what the magic carpet is.
It is not functional yet, but it will be something like a "clipboard" where you can store temporary data.
It is not functional yet, but it will be something like a "clipboard" where you can store temporary data.
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.
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 lets you drag and drop things, and see the list visually.
Stay tuned for more features, by checking out the [roadmap](/en/roadmap).
Stay tuned for more features, by checking out the [roadmap](/en/roadmap).
@ -16,7 +16,7 @@ In order to work properly, a Local First app needs to use CRDTs (Conflict-free R
Some rules are agreed upon in advance on how to deal with the conflict, based on the metadata. And those rules lead to a deterministic and consistent conflict resolution mechanism across replicas, regardless of the order in which the updates are applied.
Some rules are agreed upon in advance on how to deal with the conflict, based on the metadata. And those rules lead to a deterministic and consistent conflict resolution mechanism across replicas, regardless of the order in which the updates are applied.
The best CRDTs out there are based on a DAG of dependencies, that encodes the causal past of an update/operation/commit (all synonyms).
The best CRDTs out there are based on a DAG of dependencies (Directed Acyclic Graph), that encodes the causal past of an update/operation/commit (all synonyms).
Each operation indicates which previous operations it “sees” in its “causal past” at the moment when the operation is committed.
Each operation indicates which previous operations it “sees” in its “causal past” at the moment when the operation is committed.
@ -30,7 +30,7 @@ To come back to the higher level overview, local-first apps deal well with offli
Be it a document that is shared between the different devices of a single user, or a document that is shared among several users (and their respective many devices), the user will always be able to view and/or edit the document while being offline, and then sync with the other replicas after regaining connectivity.
Be it a document that is shared between the different devices of a single user, or a document that is shared among several users (and their respective many devices), the user will always be able to view and/or edit the document while being offline, and then sync with the other replicas after regaining connectivity.
This by itself, is a big paradigm shift for the developers, who is more used to calling some remote APIs for accessing the data.
This by itself, is a big paradigm shift for the developers, who are more used to calling remote APIs to access data.
Here the data is always accessed locally (in this sense, the backend sits in the “client” or in the “front-end" if you prefer).
Here the data is always accessed locally (in this sense, the backend sits in the “client” or in the “front-end" if you prefer).
@ -70,7 +70,7 @@ But this has a negative side-effect. The global graph that Meta by example, main
We will overcome this caveat of not having access to the global graph, by enabling peer-to-peer traversal of the graph.
We will overcome this caveat of not having access to the global graph, by enabling peer-to-peer traversal of the graph.
This will be possible very soon in NextGraph, thanks to the use of the Semantic Web and the features of "federated queries" that let's you query the data that is not on your machine, but instead, sits in the machine of your friends and contacts. If those other users give you the permission to do so, you will be able to search in their own graph too.
This will be possible very soon in NextGraph, thanks to the use of the Semantic Web and the features of "federated queries" that lets you query the data that is not on your machine, but instead, sits in the machine of your friends and contacts. If those other users give you the permission to do so, you will be able to search in their own graph too.
This is why NextGraph makes a strong separation between the data that is private and should always stay private, and the data that is public or protected. Public data can be queried by anyone, while protected data needs your permission.
This is why NextGraph makes a strong separation between the data that is private and should always stay private, and the data that is public or protected. Public data can be queried by anyone, while protected data needs your permission.
@ -101,7 +101,7 @@ Sometimes the Verifier and the Broker are on the same machine, in the same proce
Sometimes the Verifier and the App are in the same process, sometimes they need a websocket between them. But all of this are implementation details. For the developers, the same API is available everywhere, in nodeJS, in front-end Javascript, in Rust, and similarly, as commands in the CLI, regardless of where the Verifier and the Broker are actually located.
Sometimes the Verifier and the App are in the same process, sometimes they need a websocket between them. But all of this are implementation details. For the developers, the same API is available everywhere, in nodeJS, in front-end Javascript, in Rust, and similarly, as commands in the CLI, regardless of where the Verifier and the Broker are actually located.
In some cases, a broker (ngd) will run. let's say on localhost or within a LAN network, and will not be directly connected to the core network. This can happen in the following schema. This is called a Server Broker, and it doesn’t join the core network. Instead, it needs to establish a connection to a CoreBroker that will join the core network on its behalf. It will use the ClientProtocol for that, in a special way called “Forwarding", as it will forward all ClientProtocol request coming from the Verifier(s), to another broker called the CoreBroker. It will keep local copies of the events, and manage a local table of pub/sub subscriptions, but will not join overlays by itself. This will be delegated to the CoreBroker(s) it connects to.
In some cases, a broker (ngd) will run. Let's say on localhost or within a LAN network, and will not be directly connected to the core network. This can happen in the following schema. This is called a Server Broker, and it doesn’t join the core network. Instead, it needs to establish a connection to a CoreBroker that will join the core network on its behalf. It will use the ClientProtocol for that, in a special way called “Forwarding", as it will forward all ClientProtocol request coming from the Verifier(s), to another broker called the CoreBroker. It will keep local copies of the events, and manage a local table of pub/sub subscriptions, but will not join overlays by itself. This will be delegated to the CoreBroker(s) it connects to.
This Forwarding Client Protocol is not coded yet (but it is just an add-on to the ClientProtocol).
This Forwarding Client Protocol is not coded yet (but it is just an add-on to the ClientProtocol).
