diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 696b275..c0e155f 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -76,7 +76,7 @@ - [Overview](./guide/index.md) - [Preserves](./guide/preserves.md) -- [Schemas and schema bundles]() +- [Working with schemas]() - [Language-neutral protocols]() - [Rust]() - [Python]() diff --git a/src/guide/preserves.md b/src/guide/preserves.md index 2b3ce54..c2cbf32 100644 --- a/src/guide/preserves.md +++ b/src/guide/preserves.md @@ -25,25 +25,24 @@ document](https://preserves.gitlab.io/preserves/preserves.html): ## Why does Synit rely on Preserves? -There are five aspects of Preserves that make it particularly relevant to Synit: +There are four aspects of Preserves that make it particularly relevant to Synit: - the core Preserves [data language](#grammar-of-values) has a robust *semantics*; - - Preserves values may have [capability references() embedded within them; - - Preserves has a [schema language](#schemas) useful for specifying protocols among actors; - - a [canonical form](#canonical-form) exists for every Preserves value; and - - Preserves has a [query language](#preserves-path) for extracting portions of a Preserves value. + - a [canonical form](#canonical-form) exists for every Preserves value; + - Preserves values may have [capability references](#capabilities) embedded within them; and + - Preserves has a [schema language](#schemas) useful for specifying protocols among actors. ## Grammar of values -The main reason Preserves is useful for Synit is that it has *semantics*: the specification -defines a language-independent *equivalence relation* over Preserves -values.[^preserves-ordering-exists-too] This makes it a solid foundation for a multi-language, -multi-process, potentially distributed system like Synit. -[^dataspaces-need-data-with-semantics] +Preserves has programming-language-independent *semantics*: the specification defines an +*equivalence relation* over Preserves values.[^preserves-ordering-exists-too] This makes it a +solid foundation for a multi-language, multi-process, potentially distributed system like +Synit. [^dataspaces-need-data-with-semantics] ### Abstract syntax: Values -The *abstract syntax* of Preserves values is as follows (from the specification): +The *abstract syntax* of Preserves values includes a few basic atomic types, plus sequence, +set, dictionary, and record compound types. From the specification: Value = Atom Atom = Boolean | Compound | Float @@ -56,24 +55,25 @@ The *abstract syntax* of Preserves values is as follows (from the specification) ### Concrete syntax -Because Preserves has semantics independent of its syntax, we are free to define *syntax* -appropriate for its use in different settings. Values can be automatically, *losslessly* -translated from one syntax to another. The core Preserves specification defines both a -*text-based*, human-readable, JSON-like syntax, that is a syntactic superset of JSON, and a -completely equivalent compact *binary* syntax, crucial to the definition of [canonical -form](#canonical-form) for Preserves values.[^syrup] +Because Preserves' semantics are independent of its syntax, we may use different syntax for it +in different settings. Values can be automatically, losslessly translated from one syntax to +another. + +The core Preserves specification defines a text-based, human-readable, JSON-like syntax, that +is a syntactic superset of JSON, and a completely equivalent compact binary syntax, crucial to +the definition of [canonical form](#canonical-form) for Preserves values.[^syrup] Here are a few example values, written using the text syntax (see [the specification](https://preserves.gitlab.io/preserves/preserves.html#textual-syntax) for the grammar): - Boolean : #t, #f - Float : 1.0f, 10.4e3f, -100.6f - Double : 1.0, 10.4e3, -100.6 - Integer : 1, 0, -100 + Boolean : #t #f + Float : 1.0f 10.4e3f -100.6f + Double : 1.0 10.4e3 -100.6 + Integer : 1 0 -100 String : "Hello, world!\n" - ByteString : #"bin\x00str\x00", #[YmluAHN0cgA], #x"62696e0073747200" - Symbol : hello-world, |hello world|, =, !, hello?, ||, ... + ByteString : #"bin\x00str\x00" #[YmluAHN0cgA] #x"62696e0073747200" + Symbol : hello-world |hello world| = ! hello? || ... Record :