shoji / spec.txt

Diff from to

File spec.txt Modified

  • Ignore whitespace
  • Hide word diff
             2.1.4.1 IRI Pattern Object Names
             2.1.4.2 IRI Pattern Substitution
             2.1.4.3 IRI Pattern Matching
-        2.1.5 Reserved object members
+        2.1.5 Reserved IRI members
             2.1.5.1 self
             2.1.5.2 catalogs
             2.1.5.3 views
+            2.1.5.4 orders
+        2.1.6 graph
+        2.1.7 body
     2.2 Shoji Object Definitions
         2.2.1 The "Catalog" Object
             2.2.1.1 index
             2.2.1.2 Collection versus containment
             2.2.1.3 Representing objects at scale
             2.2.1.4 Using a Catalog with HTTP PATCH
-            2.2.1.5 orders
         2.2.2 The "Entity" Object
             2.2.2.1 fragments
-            2.2.2.2 body
-            2.2.2.3 Using an Entity with HTTP PATCH
+            2.2.2.2 Using an Entity with HTTP PATCH
         2.2.3 The "View" Object
             2.2.3.1 value
         2.2.4 The "Order" Object
-            2.2.4.1 graph
 3. IANA Considerations
     3.1 The "application/shoji+json" media-type
 4. Security Considerations
 
 1. Introduction
 
-Shoji is a JSON-based document format that describe sets of information
-relations known as "catalogs". Catalogs refer to any number of structured
-items, known as "entities", each with an extensible set of attached data
-known as "attributes". For example, a "users" Catalog might refer to zero
-or more "user" Entities; each "user" Entity, for example, might possess
-"login_name" and "address" attributes, while the Catalog possesses
-"full name" and "status" attributes. Data projections are exposed
-via "views": arbitrary arrangements of values.
+When we think of "objects" in reality, we often think of them as having
+a number of "attributes": an apple might have a red or green color,
+taste sweeter or more tart, be a Fuji or a Gala, be mine or yours,
+be made into cider or dipped in caramel.
+
+When it comes to representing such objects, we find that these attributes
+are often used to categorize them into groups, or to order them within
+a group. We might group apples by ownership and then order by sweetness.
+
+Shoji is a JSON-based document format to represent large numbers of
+objects efficiently. "Entities" are used to represent individual objects
+which are collected into "catalogs" and arranged by "orders". For example,
+a "users" Catalog might refer to zero or more "user" Entities; each "user"
+Entity, for example, might possess "login_name" and "address" attributes,
+while the Catalog possesses "full name" and "status" attributes.
+Data projections are exposed via "views": arbitrary arrangements of values.
 
-The primary use case that Shoji addresses is the exposure of Web content,
-such as products and transactions, to Web sites as well as directly
-to user agents.
+However, the attributes of an object are *not* always all exposed in
+a Shoji Entity. Attributes which are amenable to simple GET and PUT,
+which define the display and behavior of the object in isolation,
+are generally best represented in a Shoji Entity object. Attributes
+which govern how to arrange an object in relation to other objects
+of the same class are better represented in a Shoji Catalog.
+Attributes which are function outputs, especially from multiple
+objects as inputs (that is, extended projections), are best placed
+in a Shoji View.
+
+This is somewhat contrary to the point of view of most object-oriented
+programming environments; for example, an Employee in an object-oriented
+program would likely be an instance of a class with the attributes,
+"name", "birthday", and "hours_worked()" as peers. But these would
+be better served as a Catalog which included the "name" attribute
+from all Employees, a separate set of Entities, each with a "birthday"
+attribute, and a single View (or configurable set of Views) showing
+"hours worked" calculated across multiple Employees.
+
+In addition, a group of objects may itself be an object with particular
+attributes. For example, a set of "files" may be arranged in a hierarchy
+of "folders", each with a "name" that is editable and therefore distinct
+from its unique, permanent identifier (URI). These may then also be
+collected into larger groups with their own attributes.
 
 1.1 Examples
 
     {
         "element": "shoji:catalog",
         "self": "http://example.org/users/",
-        "title": "Users Catalog",
-        "description": "The set of user entities for this application.",
-        "updated": "2003-12-13T18:30:02Z",
+        "body": {
+            "title": "Users Catalog",
+            "description": "The set of user entities for this application.",
+            "updated": "2003-12-13T18:30:02Z"
+        },
         "catalogs": {
             "bills": "bills/",
             "sellers": "sellers/",
         },
         "views": {
             "Sold Counts": "sold_counts/"
-        },
+        }
     }
 
 ...with an Order:
 
 1.2 Namespace and Version
 
-For convenience, this format may be referred to as "Shoji 2.0".
+For convenience, this format may be referred to as "Shoji 2.1".
 This specification uses "Shoji" internally.
 
 1.3 Notational Conventions
 
-This specification describes conformance in terms of three artifacts:
-Shoji Category Objects, Shoji Entity Objects, and Shoji View Objects.
+This specification describes conformance in terms of four artifacts:
+Shoji Category Objects, Shoji Entity Objects, Shoji View Objects,
+and Shoji Order Objects.
 
 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
         *1([ shojiAttributeMember *( value-separator shojiAttributeMember ) ])
         end-object
 
-It is helpful to consider attributes as properties of abstract objects
-which likely do *not* map one-to-one with a single Shoji object.
-Attributes which are amenable to simple GET and PUT, which define
-the display and behavior of the object in isolation, are generally
-best represented in a Shoji Entity object. Attributes which govern
-how to arrange an object in relation to other objects of the same
-class are better represented in a Shoji Catalog. Attributes which
-are function outputs, especially from multiple objects as inputs
-(that is, extended projections), are best placed in a Shoji View.
-
-This is somewhat contrary to the point of view of most object-oriented
-programming environments; for example, an Employee in an object-oriented
-program would likely be an instance of a class with the attributes,
-"name", "birthday", and "hours_worked()" as peers. But these would
-be better served as a Catalog which included the "name" attribute
-from all Employees, a separate set of Entities, each with a "birthday"
-attribute, and a single View (or configurable set of Views) showing
-"hours worked" calculated across multiple Employees.
-
 2.1.3 Identifiers
 
 An Identifier is a textual value whose content MUST conform to one of the
 to reduce HTTP cache variants and to facilitate mapping substituted IRI
 Pattern values to positional arguments in the matching handler.
 
-2.1.5 Reserved object members
+2.1.5 Reserved IRI members
 
 Shoji objects may employ a variety of reserved object member names to
 declare that a given member's value is an IRI, an IRI-reference or an
 "views" member is a hint to the processor that the identified resource
 is a projection of data found elsewhere, and therefore should not be subject
 to the same expectations of atomicity, cache coherence, or mutability.
-Unlike body members (section 2.2.2.2), which are designed to return mostly
+Unlike body members (section 2.1.7), which are designed to return mostly
 a scalar or object as single attribute values, views are preferred for
 returning tabular data; that is, arrays of arrays.
 
+2.1.5.4 orders
+
+Shoji Catalog objects may employ a reserved object member to declare the IRI's
+of related orders:
+
+    shojiOrders =   DQUOTE "orders" DQUOTE name-separator shojiIRIPatternObject
+
+A GET on any of the dereferencedIRI's in the object MAY result in a Shoji
+Order Object or any other media type.
+
+Note that the Catalog does not reserve a member for a single "default order"
+for either a link or an embedded Order object. Applications are free to define
+their own as desired; however, they should carefully weigh the benefits of
+embedding a potentially large order by default (which some applications
+may ignore), as well as the eventual pressure to provide multiple orders.
+Constraining the design to follow links in the "orders" object from the
+beginning eases these concerns immensely.
+
+2.1.6 graph
+
+Shoji Catalog and Order objects employ a reserved object member to declare
+the graph of the order they represent:
+
+    shojiGroupName = string
+    shojiGroup = begin-object
+                 shojiGroupName name-separator shojiGroupArray
+                 end-object
+    shojiGroupMember = string / shojiGroup
+    shojiGroupArray =
+        begin-array
+        *1([ shojiGroupMember *( value-separator shojiGroupMember ) ])
+        end-array
+
+    shojiGraph = DQUOTE "graph" DQUOTE name-separator shojiGroupArray
+
+For example, the order represented by the following directed acyclic graph:
+
+    +------+--------+
+    V      V        V
+    f     {X}      {Y}
+           |        |
+           |    +---+---+
+           V    V   V   V
+           d    b  {Q}  a
+                    |
+                +---+---+
+                V       V
+                e       c
+
+...where the set members a, b, c, d, e, and f are variously members of groups
+X, Y, and Q, is represented in a Shoji Order as:
+
+    {
+        "element": "shoji:order",
+        "graph": [
+            "f",
+            {"X": ["d"]},
+            {"Y": [
+                "b",
+                {"Q": ["e", "c"]},
+                "a"
+            ]}
+        ]
+    }
+
+The "graph" member starts with an array of "top-level" members of the order.
+This allows orders with multiple root nodes to avoid creating a "dummy" root
+node, and also allows orders that have a single root node to name that node.
+Strings from the original set are included as is. Groups are represented as
+an object containing one member: the name of the group mapped to a further
+group array. Both may be interleaved in the graph as desired.
+
+This is purposely generic in order to facilitate multiple orders over the
+same set of identifiers. For example, applications often allow each user
+to maintain their own order over a given set of entities. When an interface
+grows from one fixed order to multiple orders, it is easier to make the
+transition with a separate Order object.
+
+Orders MAY be partial over a subset of a larger set as applications
+see fit. Members of the larger set which are not present in the order
+MAY be ignored, included in a "default" group, or follow some other
+processing rule; this specification does not govern such rules. Note
+that such members will have an undefined order, even if included in a
+group by default.
+
+This specification does not define whether identifiers or groups of
+identifiers may belong to multiple groups within a given order.
+Applications MAY impose additional constraints on this.
+
+2.1.7 body
+
+Shoji Catalog and Entity objects may employ a reserved object member
+to declare a separation of data from metadata in order to reduce
+namespace collisions and ease parsing:
+
+    shojiBody = DQUOTE "body" DQUOTE name-separator shojiTuple
+
+In general, when a body member is present in a document, processors SHOULD
+expect the attributes present within the body to be potentially mutable
+(via an HTTP PUT, PATCH, or POST, for example) and SHOULD expect any
+members outside the body member to be immutable: potentially writable
+on insert but not on update. Servers are free, of course, to allow or
+disallow mutability of any part of the resource. But the presence of
+a "body" member carries with it strong hints regarding the mutability
+of data both within and without that member.
+
 
 2.2 Shoji Object Definitions
 
  * a "self" member,
  * other metadata members,
  * an optional catalogs object (with references to related catalog documents),
- * an optional index object (with references to its collected entity documents),
  * an optional views object (with references to related view documents), and
  * an optional orders object (with references to related order documents):
+ * an optional body object (with attributes of the catalog itself),
+ * an optional index object (with references to its collected entity documents),
+ * an optional graph member (providing a default order to the index),
 
     shojiCatalogElement = DQUOTE "element" DQUOTE
                           name-separator "shoji:catalog"
                    value-separator shojiSelfIRI
                    *1( value-separator shojiCatalogs )
                    *1( value-separator shojiViews    )
-                   *1( value-separator shojiOrders    )
+                   *1( value-separator shojiOrders   )
+                   *1( value-separator shojiBody     )
                    *1( value-separator shojiIndex    )
+                   *1( value-separator shojiGraph    )
                    *( value-separator member )
                    end-object
 
     * This specification does not govern whether PATCH is allowed on a
       non-existent resource or not. The server MAY allow this (according
       to the rules below) or not as it sees fit.
-    * Only the "index" member is considered when mutating the stored
-      representation. No other members shall be altered using this format.
-      Other members MAY be sent in the request payload but SHOULD be ignored.
+    * Only the "index", "body", or "graph" member is considered when mutating
+      the stored representation. No other members shall be altered using this
+      format. Other members MAY be sent in the request payload but SHOULD be
+      ignored.
     * Any index tuple present in the stored representation but not in the
       request payload is not altered.
     * Any index tuple present in both the stored representation and the
       attributes not mentioned in the request payload are not altered.
       There is no facility for removing individual attributes.
       There is no facility for updating only partial contents of an attribute.
+    * Any attribute present in the "body" tuple of the stored representation
+      but not in the request payload is not altered.
+    * Any attribute present in the "body" tuple of the request payload but not
+      in the stored representation shall be added. The server MUST accept any
+      attributes in the tuple which it expects, and SHOULD store any attributes
+      it does not expect, in order to allow clients to evolve independently.
+      The server is free to provide default values for attributes which are
+      not mentioned when PATCH operates on a null representation.
+    * Any body attribute present in both the stored representation and
+      the request payload is overwritten by the value in the payload.
+      There is no facility for removing individual attributes.
+      There is no facility for updating only partial contents of an attribute.
 
 Adding and removing entities from a Catalog requires two different strategies
 depending on whether the Catalog is expected to contain its referenced entities
 errors when Shoji is used with the HTTP PATCH method, including
 suggested status codes to use to indicate various conditions.
 
-2.2.1.5 orders
-
-Shoji Catalog objects may employ a reserved object member to declare the IRI's
-of related orders:
-
-    shojiOrders =   DQUOTE "orders" DQUOTE name-separator shojiIRIPatternObject
-
-A GET on any of the dereferencedIRI's in the object MAY result in a Shoji
-Order Object or any other media type.
-
-Note that the Catalog does not reserve a member for a single "default order"
-for either a link or an embedded Order object. Applications are free to define
-their own as desired; however, they should carefully weigh the benefits of
-embedding a potentially large order by default (which some applications
-may ignore), as well as the eventual pressure to provide multiple orders.
-Constraining the design to follow links in the "orders" object from the
-beginning eases these concerns immensely.
-
 
 2.2.2 The "Entity" Object
 
 be aware of the cache-invalidation problems which arise when duplicating
 data in multiple resources, and trade simplicity for convenience sparingly.
 
-2.2.2.2 body
-
-Shoji Entity objects may employ a reserved object member to declare a
-separation of data from metadata in order to reduce namespace collisions
-and ease parsing:
-
-    shojiBody = DQUOTE "body" DQUOTE name-separator shojiTuple
-
-In general, when a body member is present in an Entity, processors SHOULD
-expect the attributes present within the body to be potentially mutable
-(via an HTTP PUT, PATCH, or POST, for example) and SHOULD expect any
-members outside the body member to be immutable: potentially writable
-on insert but not on update. Servers are free, of course to allow or
-disallow mutability of any part of the resource. But the presence of
-a "body" member carries with it strong hints regarding the mutability
-of data both within and without that member.
-
-2.2.2.3 Using an Entity with HTTP PATCH
+2.2.2.2 Using an Entity with HTTP PATCH
 
 The Shoji Entity object is its own HTTP PATCH [RFC5789] format.
 When a server allows the PATCH method on a resource, the Entity MAY
                  shojiGraph
                  end-object
 
-2.2.4.1 graph
-
-Shoji Order objects employ a reserved object member to declare
-the graph of the order they represent:
-
-    shojiGroupName = string
-    shojiGroup = begin-object
-                 shojiGroupName name-separator shojiGroupArray
-                 end-object
-    shojiGroupMember = string / shojiGroup
-    shojiGroupArray =
-        begin-array
-        *1([ shojiGroupMember *( value-separator shojiGroupMember ) ])
-        end-array
-
-    shojiGraph = DQUOTE "graph" DQUOTE name-separator shojiGroupArray
-
-For example, the order represented by the following directed acyclic graph:
-
-    +------+--------+
-    V      V        V
-    f     {X}      {Y}
-           |        |
-           |    +---+---+
-           V    V   V   V
-           d    b  {Q}  a
-                    |
-                +---+---+
-                V       V
-                e       c
-
-...where the set members a, b, c, d, e, and f are variously members of groups
-X, Y, and Q, is represented in a Shoji Order as:
-
-    {
-        "element": "shoji:order",
-        "graph": [
-            "f",
-            {"X": ["d"]},
-            {"Y": [
-                "b",
-                {"Q": ["e", "c"]},
-                "a"
-            ]}
-        ]
-    }
-
-The "graph" member starts with an array of "top-level" members of the order.
-This allows orders with multiple root nodes to avoid creating a "dummy" root
-node, and also allows orders that have a single root node to name that node.
-Strings from the original set are included as is. Groups are represented as
-an object containing one member: the name of the group mapped to a further
-group array. Both may be interleaved in the graph as desired.
-
-This is its own object type, rather than a reserved attribute of Catalogs,
-in order to facilitate multiple orders over the same set of identifiers.
-For example, applications often allow each user to maintain their
-own order over a given set. When an interface grows from one fixed
-order to multiple orders, it is easier to make the transition with
-a separate Order object type.
-
-Orders MAY be partial over a subset of a larger set as applications
-see fit. Members of the larger set which are not present in the order
-MAY be ignored, included in a "default" group, or follow some other
-processing rule; this specification does not govern such rules. Note
-that such members will have an undefined order, even if included in a
-group by default.
-
-This specification does not define whether identifiers or groups of
-identifiers may belong to multiple groups within a given order.
-Applications MAY impose additional constraints on this.
-
 
 3. IANA Considerations
 
                    shojiCatalogElement
                    value-separator shojiSelfIRI
                    *1( value-separator shojiCatalogs )
-                   *1( value-separator shojiIndex )
-                   *1( value-separator shojiViews )
-                   *1( value-separator shojiOrders )
+                   *1( value-separator shojiViews    )
+                   *1( value-separator shojiOrders   )
+                   *1( value-separator shojiBody     )
+                   *1( value-separator shojiIndex    )
+                   *1( value-separator shojiGraph    )
                    *( value-separator member )
                    end-object