From 5a3ab2bae9c0ccd09bcfabbeac89db232f84f68d Mon Sep 17 00:00:00 2001 From: Joep Meindertsma Date: Fri, 19 Jun 2020 15:56:44 +0200 Subject: [PATCH 1/2] move mdbook --- SUMMARY.md => src/SUMMARY.md | 0 atomic-mutations.md => src/atomic-mutations.md | 0 atomic-schema.md => src/atomic-schema.md | 0 json.md => src/json.md | 0 ownership.md => src/ownership.md | 0 rdf.md => src/rdf.md | 2 +- tooling.md => src/tooling.md | 0 7 files changed, 1 insertion(+), 1 deletion(-) rename SUMMARY.md => src/SUMMARY.md (100%) rename atomic-mutations.md => src/atomic-mutations.md (100%) rename atomic-schema.md => src/atomic-schema.md (100%) rename json.md => src/json.md (100%) rename ownership.md => src/ownership.md (100%) rename rdf.md => src/rdf.md (97%) rename tooling.md => src/tooling.md (100%) diff --git a/SUMMARY.md b/src/SUMMARY.md similarity index 100% rename from SUMMARY.md rename to src/SUMMARY.md diff --git a/atomic-mutations.md b/src/atomic-mutations.md similarity index 100% rename from atomic-mutations.md rename to src/atomic-mutations.md diff --git a/atomic-schema.md b/src/atomic-schema.md similarity index 100% rename from atomic-schema.md rename to src/atomic-schema.md diff --git a/json.md b/src/json.md similarity index 100% rename from json.md rename to src/json.md diff --git a/ownership.md b/src/ownership.md similarity index 100% rename from ownership.md rename to src/ownership.md diff --git a/rdf.md b/src/rdf.md similarity index 97% rename from rdf.md rename to src/rdf.md index 37e7ece..7e41c99 100644 --- a/rdf.md +++ b/src/rdf.md @@ -8,6 +8,7 @@ Because of that, Atomic Data is also highly compatible with RDF - **all Atomic D Atomic Data can be thought of as a **more constrained, type safe version of RDF**. However, it does differ in some fundamental ways. +- Atomic only allows those who control a resource's `subject` URI endpoint to edit the data. This means that you can't add triples about something that you don't control. - Atomic has no seperate `datatype` field, but it requires that `Properties` (the resources that are shown when you folllow a `predicate` value) specify a datatype - Atomic has no seperate `language` field, but it does support language strings as a Datatype in Properties. - Atomic has a native Event (state changes) model ([Atomic Mutations](/ATOMIC-MUTATIONS.md)), which enables communication of state changes @@ -15,7 +16,6 @@ However, it does differ in some fundamental ways. - Atomic does not support `graph` fields in statments. - Atomic does not support `blank nodes`. - Atomic does not support having multiple statements with the same ` `, every combination should be unique. -- Atomic only allows those who control a resource's `subject` URI endpoint to edit the data. ## Why these changes? diff --git a/tooling.md b/src/tooling.md similarity index 100% rename from tooling.md rename to src/tooling.md From d9207228d2c7d21596f3f0722380aa16ad298e56 Mon Sep 17 00:00:00 2001 From: Joep Meindertsma Date: Fri, 19 Jun 2020 16:38:47 +0200 Subject: [PATCH 2/2] mdbook wip --- .gitignore | 1 + README.md | 87 +++++----------------------------------------- src/SUMMARY.md | 8 +++-- src/atomic-data.md | 84 ++++++++++++++++++++++++++++++++++++++++++++ src/tooling.md | 3 +- 5 files changed, 100 insertions(+), 83 deletions(-) create mode 100644 .gitignore create mode 100644 src/atomic-data.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5a0bf03 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +/book diff --git a/README.md b/README.md index c85ac8f..583d69f 100644 --- a/README.md +++ b/README.md @@ -1,84 +1,13 @@ -# Atomic data +# Atomic Data Docs -_status: early draft, far from usable_ +_A standard for data exchange of decentralized, typed graphs._ -A standard for data exchange that enables decentralized, typed graphs. -Inspired by linked data, but more constrained (and easier to use) than RDF. +## About this repo -It consists of three parts: +This repository holds the markdown book for the Atomic Data standard. +View it on [atomicdata.dev](https://atomicdata.dev). -- Atomic Data: typed, linked data -- [Atomic-Schema](atomic-schema.md): defining and sharing models / shapes of data -- [Atomic-Mutations](atomic-mutations.md): sharing state changes +## Contributing -## Design goals - -* **Typed**. All Atomic data has an unambiguous, static datatype. Models expressed in Atomic Data can be mapped to programming langauge models, such as `structs` or `interfaces` in Typescript / Rust / Go. -* **Semantic**. Every data Atom and relation has a clear semantic meaning. -* **Browseable**. Data should explicitly link to other pieces of data, and these links should be followable. -* **ORM-friendly**. Navigate a _decentralized_ graph by using dot.syntax, similar to how you navigate a JSON object in javascript. -* **Open**. Free to use, open source, no strings attached. -* **Interoperable**. Can easily and consitently be converted to other data formats \(e.g. JSON, XML, and all RDF formats\). -* **Clear Ownership**. The URI of the data shows who is in control of the data -* **Extensible**. Anyone can define their own data types and create Atoms with it. -* **Mergeable**. Any two sets of Atoms can be merged into a sinlge graph without any merge conflicts / name collissions. - -## Motivation - -Linked data \(RDF / the semantic web\) enables us to use the web as a large, decentralized graph database. -However, it's been almost 20 years since the introduction of linked data, and its adoption has been slow. -We believe this lack of growth has to do with [some problems that lie in the RDF data model](rdf.md). -Atomic Data aims to take the best parts from RDF, and learn from the past to make a more developer-friendly, performant and reliable data model to achieve a truly linked web. - -## Concepts - -The base URL for following concepts will be `https://atomicdata.dev/core/`. - -### Atom - -The smallest possible piece of meaningful data / information. -The model of an Atom is comparable with an RDF Triple / Statement \([although there are imporant differences](rdf.md)\). -An Atom consists of a: - -* `subject` - the Thing that the atom is providing information about. \(must be a URI to an Atomic Thing\) -* `predicate` - the property of the Thing that the atom is about. \(must be a URI to an Atomic Property\) -* `object` - the new piece of information about the Atom \(can be any datatype, as long as its defined by the predicate\) - -```n-triples - "1991-01-20". - "Arnold". - . -``` - -### Resource - -A Resource is a set of Atoms where the subject has the same value. -It's a thing, such as a Person or an Issue. - -### Subject - -The Resource that the Atom is providing information about. -MUST be a URI to a Resource, which SHOULD resolve and return the Resource. - -### Predicate - -The predicate is a link that points to an Atomic Property. For example `https://example.com/createdAt` or `https://example.com/firstName`. -The predicate MUST be a URI, and that URI MUST resolve to an Atomic Property. - -When Atomic Properties correctly resolve, that's when most of the benefits of Atomic Data become real: the static types and the - -### Object - -A set of Atoms that describe how an object should be updated. - -### Serialization - -For the time being, existing RDF serialization formats can be used, such as N-Triples, Turtle, HexTuples or JSON-LD. -In the future, new \(more constrained and optimized\) serialization formats will be introduced. - -### Compatibility with other data formats - -Atomic data is designed to be highly interoperable. It is possible to convert Atomic to many types of serialization formats. - -* [RDF](rdf.md): some RDF can be automatically converted into valid Atomic data. -* [JSON](json.md): JSON requires a mapping to Atomic Properties, and explicit +Add an issue or open a PR! +All thoughts are welcome. diff --git a/src/SUMMARY.md b/src/SUMMARY.md index a7b9715..85e187c 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -1,7 +1,9 @@ # Table of contents -* [Atomic data](README.md) +* [Atomic Data - Intro](atomic-data.md) * [Atomic Schema](atomic-schema.md) * [Atomic Mutations](atomic-mutations.md) -* [How does Atomic Data relate to JSON?](json.md) -* [How does Atomic Data relate to RDF?](rdf.md) +* [Relation to RDF](rdf.md) +* [Relation to JSON](json.md) +* [Ownership](ownership.md) +* [Tooling](tooling.md) diff --git a/src/atomic-data.md b/src/atomic-data.md new file mode 100644 index 0000000..f24c8e1 --- /dev/null +++ b/src/atomic-data.md @@ -0,0 +1,84 @@ +# Atomic Data + +_status: early draft, far from usable_ + +A standard for data exchange that enables decentralized, typed graphs. +Inspired by linked data, but more constrained (and easier to use) than RDF. + +It consists of three parts: + +- [Atomic Data](readme.md): typed, linked data +- [Atomic Schema](atomic-schema.md): defining and sharing models / shapes of data +- [Atomic Mutations](atomic-mutations.md): sharing state changes + +## Design goals + +* **Typed**. All Atomic data has an unambiguous, static datatype. Models expressed in Atomic Data can be mapped to programming langauge models, such as `structs` or `interfaces` in Typescript / Rust / Go. +* **Semantic**. Every data Atom and relation has a clear semantic meaning. +* **Browseable**. Data should explicitly link to other pieces of data, and these links should be followable. +* **ORM-friendly**. Navigate a _decentralized_ graph by using dot.syntax, similar to how you navigate a JSON object in javascript. +* **Open**. Free to use, open source, no strings attached. +* **Interoperable**. Can easily and consitently be converted to other data formats (e.g. JSON, XML, and all RDF formats). +* **Clear Ownership**. The URI of the data shows who is in control of the data +* **Extensible**. Anyone can define their own data types and create Atoms with it. +* **Mergeable**. Any two sets of Atoms can be merged into a sinlge graph without any merge conflicts / name collissions. + +## Motivation + +Linked data (RDF / the semantic web) enables us to use the web as a large, decentralized graph database. +However, it's been almost 20 years since the introduction of linked data, and its adoption has been slow. +We believe this lack of growth has to do with [some problems that lie in the RDF data model](rdf.md#Why-these-changes). +Atomic Data aims to take the best parts from RDF, and learn from the past to make a more developer-friendly, performant and reliable data model to achieve a truly linked web. + +## Concepts + +The base URL for following concepts will be `https://atomicdata.dev/core/`. + +### Atom + +The smallest possible piece of meaningful data / information. +The model of an Atom is comparable with an RDF Triple / Statement ([although there are imporant differences](rdf.md)). +An Atom consists of a: + +* `subject` - the Thing that the atom is providing information about. (must be a URI to an Atomic Thing) +* `predicate` - the property of the Thing that the atom is about. (must be a URI to an Atomic Property) +* `object` - the new piece of information about the Atom (can be any datatype, as long as its defined by the predicate) + +```n-triples + "1991-01-20". + "Arnold". + . +``` + +### Resource + +A Resource is a set of Atoms where the subject has the same value. +It's a thing, such as a Person or an Issue. + +### Subject + +The Resource that the Atom is providing information about. +MUST be a URI to a Resource, which SHOULD resolve and return the Resource. + +### Predicate + +The predicate is a link that points to an Atomic Property. For example `https://example.com/createdAt` or `https://example.com/firstName`. +The predicate MUST be a URI, and that URI MUST resolve to an Atomic Property. + +When Atomic Properties correctly resolve, that's when most of the benefits of Atomic Data become real: the static types and the + +### Object + +A set of Atoms that describe how an object should be updated. + +### Serialization + +For the time being, existing RDF serialization formats can be used, such as N-Triples, Turtle, HexTuples or JSON-LD. +In the future, new (more constrained and optimized) serialization formats will be introduced. + +### Compatibility with other data formats + +Atomic data is designed to be highly interoperable. It is possible to convert Atomic to many types of serialization formats. + +* [RDF](rdf.md): some RDF can be automatically converted into valid Atomic data. +* [JSON](json.md): JSON requires a mapping to Atomic Properties, and explicit diff --git a/src/tooling.md b/src/tooling.md index abf997f..2b7585a 100644 --- a/src/tooling.md +++ b/src/tooling.md @@ -1,4 +1,4 @@ -# Atomic Data Tooling +# Tooling for Atomic Data At this moment, no real tooling for Atomic Data exists. However, basic tooling is required to make this a succes. @@ -7,6 +7,7 @@ The following list is a set of ideas that we're working on. ## Atomic creator (CLI) A CLI tool for generating Atomic Data. +Should produce Atomic Mutations. ```sh # Create an atom