Skip to content

Commit 79bb09f

Browse files
smizellsmizell
committed
Add writeup in README
1 parent 8608e43 commit 79bb09f

File tree

3 files changed

+132
-16
lines changed

3 files changed

+132
-16
lines changed

‎README.md‎

Lines changed: 132 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,135 @@
11
# Refract
22

3-
- [Specification](refract-spec.md)
3+
Refract is a a recursive data structure for expressing complex structures, relationships, and metadata.
4+
5+
## Documents
6+
7+
- [Full Specification](refract-spec.md)
48
- [JSON Namespace](namespaces/json-namespace.md)
9+
10+
## Version
11+
12+
**Current Version**: 0.1.0
13+
14+
**Note**: This specification is currently in development and may change before getting to a more stable 1.0 version. Please be mindful of this if using this production environments.
15+
16+
## Libraries
17+
18+
- [Minim (JavaScript)](https://github.com/smizell/minim)
19+
20+
## About
21+
22+
The purpose of Refract is to provide a structure for data that is not coupled to the data itself. While this is a departure from how JSON is currently used, it is a way of future-proofing clients.
23+
24+
### Why Refract?
25+
26+
Over and over, standards are created to provide additional layers of data on top of existing data. In the web world, we see this with media types, link relations, profiles, etc., where data and its semantics are being defined in different documents and in different structures.
27+
28+
Additionally, we see JSON formats that couple the representation of data to the structure of the JSON document. Clients are written to utilize this structure, which means if data changes, structure changes, and if structure changes, clients break.
29+
30+
The aim of Refract is to provide a standard structure to prevent clients from breaking in this way. In Refract, the data is decoupled from the structure. It provides a way to focus on semantics at any level rather than worry about the documents structure.
31+
32+
### Annotating JSON
33+
34+
Because of this separation, Refract provides the ability to annotate existing JSON without breaking the structure of the JSON document. XML provides the ability to add attributes about elements, but unfortunately idiomatic JSON does not. Refract can be used to add these attributes.
35+
36+
Many other formats try to annotate JSON by adding properties into the structure of the JSON document. While the aim of this was to provide simplicity, it does not clarity, as it is mainly two documents merged together.
37+
38+
#### Example
39+
40+
Here is an example of a JSON document of a place.
41+
42+
```json
43+
{
44+
"name": "The Empire State Building",
45+
"description": "The Empire State Building is a 102-story landmark in New York City.",
46+
"image": "http://www.civil.usherbrooke.ca/cours/gci215a/empire-state-building.jpg"
47+
}
48+
```
49+
50+
JSON-LD is a format used to annotate JSON structures by adding in semantics and linked data. Here is how the JSON above would be modified to include semantic linked data.
51+
52+
```json
53+
{
54+
"@context": {
55+
"name": "http://schema.org/name",
56+
"description": "http://schema.org/description",
57+
"image": {
58+
"@id": "http://schema.org/image",
59+
"@type": "@id"
60+
}
61+
},
62+
"name": "The Empire State Building",
63+
"description": "The Empire State Building is a 102-story landmark in New York City.",
64+
"image": "http://www.civil.usherbrooke.ca/cours/gci215a/empire-state-building.jpg"
65+
}
66+
```
67+
68+
Instead of merging documents, Refract takes a different approach that creates a layer on top of the existing structure.
69+
70+
```json
71+
{
72+
"element": "object",
73+
"content": [
74+
{
75+
"element": "property",
76+
"attributes": {
77+
"name": "name",
78+
"type": "http://schema.org/name"
79+
},
80+
"content": "The Empire State Building"
81+
},
82+
{
83+
"element": "property",
84+
"attributes": {
85+
"name": "description",
86+
"type": "http://schema.org/description"
87+
},
88+
"content": "The Empire State Building is a 102-story landmark in New York City.",
89+
},
90+
{
91+
"element": "property",
92+
"attributes": {
93+
"name": "image",
94+
"type": "http://schema.org/image"
95+
},
96+
"content": "http://www.civil.usherbrooke.ca/cours/gci215a/empire-state-building.jpg",
97+
}
98+
]
99+
}
100+
```
101+
102+
Refract is not meant to be a replacement for JSON-LD. The purpose of this example is to show the approach that Refract uses in annotating existing JSON structures by expanding them into a new structure that can be easily annotated.
103+
104+
105+
### Richer Data Structures
106+
107+
In addition to providing the ability to annotate existing documents, Refract can be used to create more complex data structures. As mentioned above, XML provides the ability to add attributes to element values, while JSON alone does not have this ability. Refract is meant to be a recursive structure that can do what XML does, but in JSON, and in ways that XML does not provide.
108+
109+
For example, XML cannot provide ways to include meta data about attributes. Refract elements may be used in the content of elements, but also in attributes and even the element name itself.
110+
111+
Because of this, Refract can also be used for JSON documents as well as annotating XML documents.
112+
113+
114+
### Simpler SDKs
115+
116+
Using this data structure allows for writing small, reusable classes that define methods that can be used for each element. Rather than writing an SDK that conforms to a specific data structure, SDKs may be written that provide APIs to elements. Libraries can then be written separate from the structure of data to allow for data to evolve over time.
117+
118+
### JSON Document Object Model
119+
120+
Since JSON libraries can be found in most platforms and languages, Refract provides a structure for cross-platform and cross-language object models.
121+
122+
Additionally, this means that Refract documents could be queried in the same fashion the DOM is queried, providing a more flexible structure.
123+
124+
## Uses
125+
126+
- Replace brittle and complex JSON structures
127+
- Recursively annotate existing JSON structures
128+
- Create markup languages that cross boundaries between formats such as XML and JSON
129+
- Provide a JSON version of an existing XML document structure
130+
131+
## Authors
132+
133+
- [Stephen Mizell](https://github.com/smizell)
134+
- [Mark Foster](https://github.com/fosrias)
135+
- [Zdenek Nemec](https://github.com/zdne)

‎namespaces/json-namespace.md‎

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,3 @@
1-
---
2-
3-
Author: Stephen Mizell
4-
Version: 0.1.0
5-
6-
---
7-
81
# JSON Namespace
92

103
This spec defines JSON primitive types to be used in a Refract document structure. Each type defined here extends the Refract Element as defined in the Refract specification.

‎refract-spec.md‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,3 @@
1-
---
2-
3-
Author: Stephen Mizell
4-
Version: 0.1.0
5-
6-
---
7-
8-
91
# Refract Document Format Specification
102

113
## Introduction

0 commit comments

Comments
 (0)