Update 1.0.0 RFC

Author: smizell

text/0000-refract-1.0.md

@@ -23,7 +23,7 @@ With this in mind, I'd like to start now thinking through the steps on how to pr
 
 In addition to moving to 1.0.0, we need to actually start versioning namespace documents. The reason for this is that we do not want a breaking change in a namespace to require a major version bump for the entire spec.
 
-**Proposal**: Start versioning current and future namespaces and move each namespace to their own repo. We can do this immediately.
+**Proposal**: Move all current namespaces to API Elements project.
 
 ## [Resolved] Namespace Functionality
 
@@ -41,7 +41,13 @@ An important concept of Refract is that it is a model for representing data stru
 
 This decoupling I think is important, because it gives freedom to implementors to implement the best way they see fit in their language/platform, and it allows for other serialization formats to spring up that may be helpful to others.
 
-**Proposal**: Explain the difference in the conceptual model and the serialization formats, and potentially move these serialization descriptions to their own file in the spec repo, separating them from the main spec.
+**Proposal**: Explain the difference in the conceptual model and the serialization formats, and create serialization guidelines for full Refract.
+
+## Inheritance
+
+Inheritance can be handled differently depending on the context in which the element is found. This shows up in how we handle inheritance within the data structure elements (now in API Elements).
+
+**Proposal**: Explain inheritance in some way, either in the base specification or through some type of guidelines document.
 
 # Drawbacks
 

text/0000-refract-path.md

@@ -0,0 +1,140 @@
+- Start Date: 2016-01-22
+- RFC PR: (leave this empty)
+- Refract Issue: (leave this empty)
+
+# Summary
+
+This may scare some, but this is an RFC to propose a first iteration of Refract
+Path for addressing paths throughout a Refract tree.
+
+# Motivation
+
+When interacting with a Refract tree, it becomes cumbersome to walk down a path
+because of the constant need to go into the `content` property of a Refract
+element. It is also difficult to pass around pointers to values in a JSON
+representation.
+
+# Detailed design
+
+This design is modeled after the following:
+
+- [Falcor](https://netflix.github.io/falcor/documentation/jsongraph.html)
+- Clojure's `get-in`
+- Om Next
+
+The idea is the treat the Refract tree as a graph that can be queried and
+navigated.
+
+In this design, I've also refrained as much as possible from building a query
+language and just using normal arrays for giving paths. I have introduced the
+concept of symbols, but we can easily leave them out in the first iteration.
+
+The key to this design is that a path (or query if you will) requires walking
+down the tree and calling various data given the context in which it is found.
+Take this simple object as a first example.
+
+```json
+{
+  "foo": [
+    {
+      "bar": "baz"
+    }
+  ]
+}
+```
+
+Since we know that an object with an `element` property is a Refract element,
+we can treat our objects accordingly. This means if I want the value `baz`
+above, we can use a path like this, represented as a JSON array.
+
+```json
+["foo", 1, "bar"]
+```
+
+There are a few things we would assume here:
+
+1. When in a normal object, a string is a reference to a property of that
+   object (like with `"foo"`).
+2. When in a normal array, an integer gets the item at the given index.
+
+Now as we look at using this for Refract objects, we handle the path a little
+differently.
+
+```json
+{
+  "element": "object",
+  "content": [
+    {
+      "element": "member",
+      "content": {
+        "key": {
+          "element": "string",
+          "content": "foo"
+        },
+        "value": {
+          "element": "array",
+          "content": [
+            {
+              "element": "object",
+               "content": [
+                {
+                  "element": "member",
+                  "content": {
+                    "key": {
+                      "element": "string",
+                      "content": "bar"
+                    },
+                    "value": {
+                      "element": "string",
+                      "content": "baz"
+                    }
+                  }
+                }
+              ]
+            }
+          ]
+        }
+      }
+    }
+  ]
+}
+```
+
+To get the value of `bar`, you would use a very similar path. The path
+`["foo", 1, "bar", ':value']` would return the same value as the one above. What
+`:value` does is ensure that you always get the content of the final path item,
+whether it's an element or whether it's a normal value. There are few rules for
+this here.
+
+1. If an element with a content that is an array, and a number is given, it
+   returns the corresponding index in `content`.
+2. If an element is the current path, and a string is given, it returns the
+   value of where the content of the `key` matches.
+3. The `:value` symbol returns either the `content` of an element or the actual
+   value itself of the element. This is for situations where a value can either
+   be refracted or a primitive JSON value.
+
+We can use similar special symbols for getting the value of element, meta, or
+attributes.
+
+```json
+["foo", ":meta", "title", ":value"]
+```
+
+This path will return the value of `title`, whether it's refracted or not.
+
+In light of this, implementation SHOULD treat paths that did not return value to
+be some form of a "not found" value. It's up the implementation to decide how
+to interpret this kind of query result.
+
+# Drawbacks
+
+Why should we *not* do this?
+
+# Alternatives
+
+What other designs have been considered? What is the impact of not doing this?
+
+# Unresolved questions
+
+What parts of the design are still TBD?