From 8f1b58e256f64457784f1a37761c0ea2020ce954 Mon Sep 17 00:00:00 2001 From: Dmitri Zagidulin Date: Tue, 23 Feb 2016 19:59:09 -0500 Subject: [PATCH] Move the following sections from solid-spec to solid: * Project Overview * Project Workflow * Pre-Requisites * Standards Used * Platform Notes Addresses https://github.com/solid/solid-spec/issues/36 and https://github.com/solid/solid/issues/72 --- README.md | 189 ++++++------------------------------------------------ 1 file changed, 20 insertions(+), 169 deletions(-) diff --git a/README.md b/README.md index d490b9a..d8cdbae 100644 --- a/README.md +++ b/README.md @@ -6,64 +6,9 @@ **Current Spec version:** `v.0.5.0` (see [CHANGELOG.md](CHANGELOG.md)) -## Project Overview - -[Solid](https://github.com/solid/solid) (derived from "**so**cial **li**nked -**d**ata") is a proposed set of conventions and tools for building -*decentralized social applications* based on [Linked -Data](http://www.w3.org/DesignIssues/LinkedData.html) principles. Solid is -modular and extensible. It relies as much as possible on existing -[W3C](http://www.w3.org/) standards and protocols. - -Specifically, [Solid](https://github.com/solid/solid) is: - -* A tech stack -- a set of complementary [standards](#standards-used) and - [data formats/vocabularies](https://github.com/solid/vocab) that together - provide capabilities that are currently available only through centralized - social media services (think Facebook/Twitter/LinkedIn/many others), such as - *identity*, *authentication and login*, *authorization and permission lists*, - *contact management*, *messaging and notifications*, *feed aggregation and - subscription*, *comments and discussions*, and more. -* A **[Specifications document](https://github.com/solid/solid-spec)** - (that's this repo here) that describes a REST API that extends those existing - standards, contains design notes on the individual components used, and is - intended as a guide for developers who plan to build servers or applications. -* A set of [servers](https://github.com/solid/solid-platform#servers) that - implement this specification. -* A [test suite](https://github.com/solid/solid-tests) for testing and validating - Solid implementations. -* An ecosystem of [social apps](https://github.com/solid/solid-apps), - [identity providers](https://github.com/solid/solid-idp-list) and helper - libraries (such as [solid.js](https://github.com/solid/solid.js)) that run on - the Solid platform. -* A community providing documentation, discussion (see the - [solid gitter channel](https://gitter.im/solid/solid)), - [tutorials](https://github.com/solid/solid#tutorials) and - [talks/presentations](https://github.com/solid/talks). - -## Solid Project Workflow - -To contribute to Solid development, and to bring up issues or feature requests, -please use the following workflow: - -1. Have a question or a feature request or a concern about the Solid framework, - or on one of its servers? **Open an issue on - [solid/solid](https://github.com/solid)**. - -2. Have an issue with the *Solid spec* specifically? **Open an issue on - [solid/solid](https://github.com/solid) anyway.** And then, as a result of - discussion, if it's agreed that it is actually a Spec issue, it will be moved - to `solid-spec`. - -3. The individual [solid/solid](https://github.com/solid) issues can coordinate - and track component/dependent issues on the various affected Solid servers, - apps, and so on. - ## Table of contents -* [Pre-Requisites](#pre-requisites) -* [Standards Used](#standards-used) -* [Platform Notes](#solid-platform-notes) +* [Overview](#overview) * [Profiles](#profiles) * [Authorization and Access Control](#web-access-control) * [Reading](#reading) @@ -74,119 +19,25 @@ please use the following workflow: * [Example](#example) * [Other Considerations](#other-considerations) -## Pre-Requisites - -In order to try out some of the apps built using Solid, you will need the -following things: - -1. A WebID profile from one of the Solid-compliant - [identity providers](https://solid.github.io/solid-idps/), such as - [databox.me](https://databox.me/). - -2. A WebID browser certificate from the above profile (this is usually created - when you sign up for a WebID profile account). - -Additionally, to get started with developing for the Solid platform, you'll -need: - -1. A Solid-compliant [server](https://github.com/solid/solid-platform#servers) - -2. While not required, an understanding of - RDF/[Turtle](http://www.w3.org/TR/turtle/) principles and - [Linked Data Platform](http://www.w3.org/TR/ldp-primer/) concepts will help - you understand the general workflow. - -## Standards Used - -The Solid platform uses the following standards. - -* [RDF 1.1 (Resource Description Framework)](http://www.w3.org/RDF/) - (see also [RDF Primer](http://www.w3.org/TR/rdf11-concepts/)) is heavily - used in Solid data models. By default, the *preferred* RDF serialization - format is [Turtle](http://www.w3.org/TR/turtle/). Alternative serialization - formats such as [JSON-LD](http://www.w3.org/TR/json-ld/) and - [RDFa](http://www.w3.org/TR/rdfa-primer/) can also be used. - -* The [WebID 1.0 (Web Identity and Discovery)](http://www.w3.org/2005/Incubator/webid/spec/identity/) - standard is used to provide universal usernames/IDs for Solid apps, and to - refer to unique Agents (people, organizations, devices). See also the - [WebID interoperability notes](http://www.w3.org/2005/Incubator/webid/wiki/Identity_Interoperability) - for an overview of how WebID relates to other authentication and identity - protocols. - -* WebIDs, when accessed, yield - [WebID Profile](http://www.w3.org/2005/Incubator/webid/spec/identity/#dfn-webid_profile) - documents (in Turtle and other RDF formats). - -* The [FOAF vocabulary](http://xmlns.com/foaf/0.1/) is used both in WebID - profiles, and in specifying Access Control lists (see below). - -* Authentication (for logins, page personalization and more) is done via the - [WebID-TLS protocol](http://www.w3.org/2005/Incubator/webid/spec/tls/). - WebID-TLS extends WebID Profiles to include references to the subject's - [public keys](https://en.wikipedia.org/wiki/Public-key_cryptography) in - the form of [X.509 Certificates](https://en.wikipedia.org/wiki/X.509), using - [Cert Ontology 1.0](http://www.w3.org/ns/auth/cert) vocabulary. - The authentication sequence is done using the - [HTTP over TLS](https://tools.ietf.org/html/rfc2818) protocol. Unlike normal - HTTPS use cases, WebID-TLS is done without referring to - [Certificate Authority](https://en.wikipedia.org/wiki/Certificate_authority) - hierarchies, and instead encourages host server-signed (or self-signed) - certificates. - -* In Solid, certificate creation is typically done in the browser using the - HTML5 [keygen - element](http://www.w3.org/TR/html5/forms.html#the-keygen-element), - to provide a one-step creation and certificate publication user experience. - -* Authorization and access lists are done using - [Basic Access Control ontology](http://www.w3.org/ns/auth/acl) (see also the - [WebAccessControl wiki page](http://www.w3.org/wiki/WebAccessControl) for - more details). - -* Solid uses the [Linked Data Platform (LDP)](http://www.w3.org/TR/ldp/) standard - (see also [LDP Primer](http://www.w3.org/TR/ldp-primer/)) extensively, as a - standard way of reading and writing generic Linked Data resources. - -## Solid Platform Notes - -Solid applications are somewhat like multi-user applications where instances talk -to each other through a shared filesystem, and the Web is that filesystem. - -1. The [LDP specification](http://www.w3.org/TR/ldp/) defines a set of rules for - HTTP operations on Web resources, some based on [RDF](http://www.w3.org/RDF/), - to provide an architecture for reading and writing Linked Data on the Web. The - most important feature of LDP is that it provides us with a standard way of - RESTfully writing resources (documents) on the Web, without having to rely on - less flexible conventions (APIs) based around sending form-encoded data using - POST. For more insight into LDP, take a look at the examples in the LDP - [Primer document](http://www.w3.org/TR/ldp-primer/). - -2. Solid's basic protocol is REST, as refined by LDP with minor extensions. New - items are created in a *container* (which could be called a collection or - directory) by sending them to the container URL with an HTTP POST or issuing - an HTTP PUT within its URL space. Items are updated with HTTP PUT or HTTP - PATCH. Items are removed with HTTP DELETE. Items are found using HTTP GET and - following links. A GET on the container returns an enumeration of the items in - the container. - -3. Servers are application-agnostic, so that new applications can be developed - without needing to modify servers. For example, even though the [LDP - 1.0](http://www.w3.org/TR/ldp/) specs contains nothing specific to - "social", many of the [W3C Social Work Group](http://www.w3.org/Social/WG)'s - [User Stories](http://www.w3.org/wiki/Socialwg/Social_syntax/User_Stories) can - be implemented using only **application logic**, with no need to change code on - the server. The design ideal is to keep a small standard data management core - and extend it as necessary to support increasingly powerful classes of - applications. - -4. The data model is RDF. This means the data can be transmitted in various - syntaxes like [Turtle](http://www.w3.org/TR/turtle/), - [JSON-LD](http://www.w3.org/TR/json-ld/) (JSON with a "context"), or - [RDFa](http://www.w3.org/TR/rdfa-primer/) (HTML attributes). RDF is - REST-friendly, using URLs everywhere, and it provides **decentralized - extensibility**, so that a set of applications can cooperate in sharing a new - kind of data without needing approval from any central authority. +## Overview + +[Solid](https://github.com/solid/solid) (derived from "**so**cial **li**nked +**d**ata") is a proposed set of conventions and tools for building +*decentralized social applications* based on [Linked +Data](http://www.w3.org/DesignIssues/LinkedData.html) principles. Solid is +modular and extensible. It relies as much as possible on existing +[W3C](http://www.w3.org/) standards and protocols. + +See Also: + +* [About Solid](https://github.com/solid/solid#about-solid) +* [Contributing to Solid](https://github.com/solid/solid#contributing-to-solid) + * [Pre-Requisites](https://github.com/solid/solid#pre-requisites) + * [Solid Project + Workflow](https://github.com/solid/solid#solid-project-workflow) +* [Standards Used](https://github.com/solid/solid#standards-used) +* [Platform Notes](https://github.com/solid/solid#solid-platform-notes) +* [Solid Project directory](https://github.com/solid/solid#project-directory) ## Profiles