Commits

Robert Brewer committed d600cad

Draft 03 alpha

  • Participants
  • Parent commits 575816b

Comments (0)

Files changed (1)

 
 1. Introduction
 
-Shoji is a set of JSON-based document formats that describe sets of related
-information known as "catalogs". Catalogs are composed of a number of items,
+Shoji is a set of JSON-based document formats that describe sets of information
+relations known as "catalogs". Catalogs refer to any number of items,
 known as "entities", each with an extensible set of attached data known as
-"values". For example, a "users" Catalog might contain zero or more "user"
+"values". For example, a "users" Catalog might refer to zero or more "user"
 Entities; each "user" Entity, for example, might possess "login_name"
 and "address" Values.
 
 The primary use case that Shoji addresses is the exposure of Web content,
-such as e-commerce products and transactions, to Web sites as well as directly
+such as products and transactions, to Web sites as well as directly
 to user agents.
 
 1.1 Examples
      "self": "http://example.org/users/1",
      "body": {
          "last_modified": "2003-12-13 18:30:02Z",
-         "first_name": "Katsuhiro",
-         "last_name": "Shoji",
+         "name": {"first": "Katsuhiro", "last": "Shoji"},
          "sold_count": 387
          }
     }
      "title": "Users Catalog",
      "description": "The set of user entities for this application.",
      "updated": "#2003-12-13T18:30:02Z#",
-     "catalogs": {"bills": "bills",
-                  "sellers": "sellers",
-                  "sellers by sold count": "sellers{?sold_count}"
+     "catalogs": {"bills": "bills",
+                  "sellers": "sellers",
+                  "sellers by sold count": "sellers{?sold_count}"
                   },
      "entities": ["1", "2", "88374", "9843"],
      "views": {"Sold Counts": "sold_counts"},
  * Ease client construction of hyperlinks.
  * Allow linking to, and other metadata descriptions of, other media-types.
  * Support both complete dataset exposure and sparse, restricted exposure.
- * Encourage caching.
+ * Encourage caching in a way that minimizes synchronization issues.
  * Have payloads be persisted to filesystems and databases without loss of information.
  * Be independent of any particular device or implementation language.
 
 
 All three kinds of Shoji Documents are specified in terms of JavaScript
 Object Notation ("JSON", specified in [RFC4627]). Shoji Documents MUST be 
-well-formed JSON; however, Shoji Value Documents are not "JSON texts" and
+well-formed JSON; however, Shoji Value Documents are not "JSON texts" and
 therefore may be an object, array, string, number, or literal.
 
 Shoji allows the use of IRIs [RFC3987]. Every URI [RFC3986] is also an IRI,
  (2) when an IRI is serving as a "self" value (see Section 3.3.1), it MUST NOT
      be so mapped, so that the comparison works as described in Section 3.2.1.
 
-Shoji Processors MAY keep state sourced from Shoji Documents and combine them
-with other Shoji Documents, in order to facilitate a contiguous view of the
-contents of a catalog. The manner in which Shoji Documents are combined in
-order to reconstruct a catalog (e.g., updating entities and metadata, dealing
-with missing entities) is out of the scope of this specification.
-
 
 3. Common Shoji Constructs
 
 productions in the IRI specification [RFC3987], encompassed in double quotes:
 
     shojiIRI = DQUOTE IRI DQUOTE
-    shojiIdentifier = DQUOTE IRI-reference DQUOTE
+    shojiIdentifier = DQUOTE IRI-reference DQUOTE
     
     shojiIdentifierArray =
         begin-array
         [ shojiIdentifier *( value-separator shojiIdentifier ) ]
-        end-array
+        end-array
 
 Example Identifiers:
 
 relative reference.
 
     shojiIRIPattern = DQUOTE IRI-Pattern DQUOTE
-    
+    
     shojiIRIPatternArray =
         begin-array
         [ shojiIRIPattern *( value-separator shojiIRIPattern ) ]
         end-array
-    
+    
     shojiIRIPatternElement = string name-separator shojiIRIPattern
     shojiIRIPatternObject =
-        begin-object
+        begin-object
         [ shojiIRIPatternElement *( value-separator shojiIRIPatternElement ) ]
         end-object
-
-3.2.1 IRI Pattern Object Names
-
-When IRI Patterns are contained within a shojiIRIPatternObject, the name
-portion of each shojiIRIPatternElement identifies the semantics of the link.
-For example, an Entity that represents a User resource might include a single
-shojiCatalog member; the identified resource returns a Catalog, to be sure,
-but the IRIPattern which identifies that resource may be opaque. By supplying
-the member name "orders", the Entity declares that the Catalog resource
-returns Order resources related to the current User resource. In this way,
-shojiIRIPatternObject names function similarly to link relation types found
-in other specifications. Authors MAY use existing registries of link relation
-types, but are not bound to.
+
+3.2.1 IRI Pattern Object Names
+
+When IRI Patterns are contained within a shojiIRIPatternObject, the name
+portion of each shojiIRIPatternElement identifies the semantics of the link.
+For example, an Entity that represents a User resource might include a single
+shojiCatalog member; the identified resource returns a Catalog, to be sure,
+but the IRIPattern which identifies that resource may be opaque. By supplying
+the member name "orders", the Entity declares that the Catalog resource
+returns Order resources related to the current User resource. In this way,
+shojiIRIPatternObject names function similarly to link relation types found
+in other specifications. Authors MAY use existing registries of link relation
+types, but are not bound to.
 
 3.2.2 IRI Pattern Substitution
 
 3.3 Identifier members
 
 Shoji objects may employ a variety of reserved object member names to
-declare that a given member's value is an IRI, and IRI-reference or an
+declare that a given member's value is an IRI, an IRI-reference or an
 array or object of IRI-references.
 
 3.3.1 Absolute Reference Members
 exported, or imported, the content of its self member MUST NOT change.
 Put another way, a self member pertains to all instantiations of a
 particular Shoji entity or catalog; revisions retain the same content
-in their self elements. It is suggested that the self element be stored
+in their self members. It is suggested that the self member be stored
 along with the associated resource.
 
-The content of a shojiSelfIRI element MUST be created in a way that assures
+The content of a shojiSelfIRI member MUST be created in a way that assures
 uniqueness.
 
 3.3.2 Relative Reference Members
 
 Shoji objects may employ a variety of reserved object member names to
-declare that a given member's value is an IRI-reference or an array or object
+declare that a given member's value is an IRI-reference or an array or object
 of IRI-references:
 
     shojiIdentifierMember =
     shojiIRIPatternMember =
         string name-separator
         ( shojiIRIPattern / shojiIRIPatternArray /shojiIRIPatternObject )
-
+
 Application authors should be aware of the many details of relative URI
 resolution described in Section 5.2 of [RFC2396]; in particular, that
 "all but the last segment of the base URI's path component is copied
 
 For Shoji documents, this implies two different approaches depending on
 whether trailing slashes are preferred. If catalog resources employ
-trailing slashes, then their links to subcatalogs, entities, views,
-and so on are simpler. For example, the Catalog resource at "/users/" may
+trailing slashes, then their links to subcatalogs, entities, views, and
+so on may be simpler. For example, the Catalog resource at "/users/" may
 include a "bills" subcatalog. But if the Catalog is instead exposed at the
 URI "/users" (no trailing slash), then the subcatalog IRI-reference must
 be written as "users/bills" in order to be resolved correctly. Both forms
 are permitted by this specification; application authors SHOULD use
 HTTP redirects to help enforce one or the other as canonical.
 
-If trailing slashes are preferred, then trailing slashes should be used
-whenever the return type changes from the parent resource, and omitted when
-the type does not change. For example, if the resource at "/users/" is a
-Catalog for User resources, and the application designer wishes to include
-subcatalogs for, on the one hand, active users, and on the other, Bill
-resources, then they should expose the former without a trailing slash
-("/users/active") since it will return User representations and the latter
-with a trailing slash ("/users/bills/") since it will not return User
-representations.
-
 Shoji Entity resources MUST be exposed with trailing slashes so that their
 body member names may serve as IRI's relative to them; that is, omitting
-the trailing slash would force body member names to change unacceptably.
+the trailing slash would force body member names to include slashes.
 For example, the following entity:
 
    {"element": "shoji:entity",
     "body": {"1234/first_name": "David",
              "1234/last_name": "Robinson"}}
 
-Authors who can't help but think of a trailing slash as indicating an index or
-collection are encouraged to view an Entity object as a collection of its values
+Authors who can't help but think of a trailing slash as indicating an index or
+collection are encouraged to view an Entity object as a collection of its values
 for their own sanity.
 
 3.3.2.1 catalogs
 
     shojiCatalogs = DQUOTE "catalogs" DQUOTE name-separator shojiIRIPatternObject
 
-A GET on any of the dereferencedIRI's in the object MUST result in a Shoji
-Catalog Document.
+A GET on any of the dereferencedIRI's in the array MAY result in a Shoji
+Catalog Document, or MAY result in a response with any other media type.
+Implementers are encouraged to use Shoji Catalog documents to gain their
+benefits where possible; however, not all resources are a good fit for
+the Shoji media type.
 
 3.3.2.2 entities
 
 Shoji Catalog objects may employ a reserved object member to declare the
-IRI's of contained entities:
+IRI's of collected entities:
 
     shojiEntities = DQUOTE "entities" DQUOTE name-separator shojiIdentifierArray
 
-A GET on any of the dereferencedIRI's in the array MUST result in a Shoji
-Entity Document.
+A GET on any of the dereferencedIRI's in the array MAY result in a Shoji
+Entity Document, or MAY result in a response with any other media type.
+Implementers are encouraged to use Shoji Entity documents to gain their
+benefits where possible; however, not all resources are a good fit for
+the Shoji media type.
+
+The presence of an IRI in an "entities" array does not inherently imply
+that the entity is contained by the catalog, or that the IRI of the entity
+or catalog share any path information, or even host or scheme. Some catalogs
+contain their entities but not all. For example, one catalog might be
+designed such that an HTTP POST of an entity to the catalog URI results
+in a new resource entity being created, and its IRI appended to the
+catalog's "entities" member. However, other catalogs may be designed to
+be updated directly with, for example, an HTTP PUT to the catalog IRI
+(perhaps with an ETag) to replace it wholesale. Others may be updated
+internally with no user-facing interface to alter them at all. A catalog
+merely indicates that its entities are related somehow. Catalogs should
+indicate the process by which a client updates their entities array,
+perhaps in a "description" member, but such mechanisms are outside
+the scope of this specification.
+
+The "entities" member is purposefully an array of IRI's instead of an object,
+to constrain the most common applications to be scale-agnostic by default.
+That is, if an application uses a catalog's "entities" member properly,
+then clients can remain unaware of whether the entities in a given catalog
+reside on the same system or not, and the server is then free to distribute
+them to multiple partitions as it sees fit.
+
+For example, if a catalog resource accepts an HTTP POST to simultaneously
+create a new Entity resource and append it to the catalog's "entities"
+member, then the server would return a Location header with the URI of
+the new Entity resource (which might reside on a different host, or even
+use a different scheme than "http"). When the entities are few, or all
+managed by the same partition, then it seems simple to return a JSON
+object which maps ids to complete entities, or at least names to IRI's.
+But when the number of entities grows very large (let's choose 1 billion
+for a small example), then the server implementation must be modified to
+store those entities on multiple partitions, and it becomes prohibitively
+expensive for the server to emit names or other entity data along with
+the IRI's.
+
+No catalog would choose to include a billion entity IRI's, of course;
+subcatalogs would be used to manage smaller collections. But a subcatalog
+of even 100 entities might then refer to 100 different hosts. The subcatalog
+resource could poll every entity in every partition to obtain additional data,
+but that quickly degrades performance when the number of partitions grows
+very large. A server might instead try keeping those names or other data
+within the "entities" index itself, but that duplicated information then
+gets out of sync with the actual entities, especially in the presence of
+aggressive cache networks. An application might attempt to align subcatalog
+partitions with implementation partitions, but this is a design choice that
+is not universally applicable, such as the case where multiple catalogs are
+used to implement additional alternate indices.
+
+Constraining the "entities" member to be an array of IRI's encourages
+applications to be scale-agnostic. Applications MAY implement additional
+members which are objects that map ids to entity data, or names to entity
+IRI's; however, they should only do so with the understanding that they
+will need to be redesigned if the number of entities in the map grows large.
 
 3.3.2.3 fragments
 
 
     shojiFragments = DQUOTE "fragments" DQUOTE name-separator shojiIRIPatternObject
 
-A GET on any of the dereferencedIRI's in the object MUST result in a Shoji
-Entity Document.
+A GET on any of the dereferencedIRI's in the object MAY result in a Shoji
+Entity Document, or MAY result in a response with any other media type.
+The exact semantics of what constitutes a "fragment" of an entity of any
+media type is not defined by this specification.
 
-Fragment entities are entities which contain a subset of the values for the
-parent Entity. For example, if a single "user" Entity has public and private
+Shoji fragment entities are entities which contain a subset of the values for
+the parent Entity. For example, if a single "user" Entity has public and private
 attributes, a parent Entity at /users/1234/ might contain the public values,
 and possess a fragment at /users/1234/private/ containing private values;
 in this example, the parent Entity would possess a "fragments" member with
-the value {"Priavte members": "private"}.
+the value {"Private members": "private"}.
 
 Parent Entities MAY include shojiValueMembers whose values are complete
 fragment Entity objects, or MAY include none, any or all of the value
 
 A GET on any of the dereferencedIRI's in the object SHOULD result in a Shoji
 Value Document. Unlike body members (section 3.4), which are designed to return
-mostly scalar values, views are preferred for returning tabular datasets.
+mostly scalar or object values, views are preferred for returning tabular
+datasets; that is, arrays of arrays.
 
 3.4 Body Members
 
 
     shojiBodyMember = DQUOTE "body" DQUOTE name-separator value
 
+In general, when a body member is present, processors SHOULD expect the
+values present within the body to be potentially mutable (via an HTTP PUT
+or POST, for example) and SHOULD expect any values outside the body member
+to be immutable; that is, (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.
 
 3.5 Element Declarations
 
 
 This is a generic, namespaced element declaration approach that we hope will be
 adopted by other JSON-based media types.
-
+
 
 4. Shoji Object Definitions
 
 associated with the catalog. Its members consist of a "self" attribute,
 other metadata members, an optional catalogs object (with references to
 its contained catalog documents), an optional entities array (with
-references to its contained entity documents), and an optional views
-object (with references to its contained value documents):
+references to its collected entity documents), and an optional views
+object (with references to its collected value documents):
 
     shojiCatalogElement = DQUOTE "element" DQUOTE
                           name-separator "shoji:catalog"
     shojiCatalog = begin-object
                    shojiCatalogElement
                    shojiSelfIRI
-                   *( value-separator member )
                    *1( value-separator shojiCatalogs )
                    *1( value-separator shojiEntities )
                    *1( value-separator shojiViews    )
+                   *( value-separator member )
                    end-object
 
 Shoji catalog objects MAY follow the order of member elements given above;
 Shoji Entity objects, or IRI's identifying such. Their syntax is not
 mandated nor constrained by this specification.
 
+Note that Catalog objects MAY collect zero, one or any number of resources
+by presenting their identifiers in the "entities" member. The referenced
+resources MAY be Shoji Entity documents, or MAY be any other media type.
+
+Although Catalog objects often "contain" entities, in the sense that the
+entities are considered to have no existence outside of the containing
+catalog, this is not always the case. In many circumstances, multiple
+catalogs MAY refer to the same entity. In other situations, a catalog
+will refer to one or more entities without containment; that is, the
+entity resources are considered to exist whether the referring catalog
+exists or not.
+
 4.1.2 The "Entity" Object
 
 The "shojiEntity" object acts as a container for data associated with the
     shojiEntity = begin-object
                   shojiEntityElement
                   shojiSelfIRI
-                  *1( shojiEntityBodyMember )
                   *1( value-separator shojiCatalogs )
                   *1( value-separator shojiFragments )
                   *1( value-separator shojiViews )
+                  *( value-separator member )
+                  *1( shojiEntityBodyMember )
                   end-object
 
 Each member contained in the EntityBody SHOULD be referenceable by combining its
 Server authors MAY elect to return 404 Not Found for any Value resource (and
 indeed, any code including 405 Method Not Allowed if desired to restrict
 the set of HTTP methods); however, this does not nullify the expectation
-that the Value IRI points to the expected resource. This promotes evolvable
+that the Value IRI identifies a Value resource. This promotes evolvable
 structures; the Value resource can be added or modified at a later date
 without changing the Entity which refers to it.
 
 Catalog or Entity is not intended to "stand on its own" outside the Value
 (that is, answer to various HTTP methods on "self" and its member values'
 IRI's), authors are encouraged to emit tabular data rather than lists of
-Catalog or Entity objects.
+Catalog or Entity objects. The lack of a common idiom for returning arrays
+of objects is intentional, because they lead to implementations that heavily
+duplicate data and rely on fine-grained queries for network efficiency.
+Shoji is designed to rely on caching for network efficiency.
 
 Note that documents of the media type "application/json" must be of type
 "object" or "array", but Shoji Value Documents may be any valid JSON type,
-including false, null, true, object, array, number, or string.
+including false, null, true, object, array, number, or string. Because Shoji
+documents do not have this restriction, Shoji clients MUST NOT use Javascript
+eval() or equivalent mechanisms in other languages to parse Shoji documents.
 
 The "shojiValueMember" object is the combination of a value name
 and value for inclusion within a shojiEntity:
     shojiValueMember = shojiValueName name-separator shojiValue
 
 
-5. Control and Publishing
+5. IANA Considerations
 
-The Shoji Catalog Protocol uses HTTP methods to author Shoji Resources as follows:
-
- * GET is used to retrieve a representation of a known Catalog, Entity, or Value.
- * POST is used to create a new, dynamically identified, Entity.
- * PUT is used to create or edit an Entity, or edit a Value, with a known identity.
- * DELETE is used to remove a known Entity.
-
-The Shoji Protocol only covers the creating, editing, and deleting of Entity and
-Value Resources. Other Resources could be created, edited, and deleted as the result
-of manipulating a Catalog, but the number of those Resources, their media types,
-and effects of the Shoji Protocol operations on them are outside the scope of this
-specification.
-
-While specific HTTP status codes are shown in the interaction diagrams below, a Shoji
-client should be prepared to handle any status code. For example, a PUT to an Entity
-URI could result in the return of a "204 No Content" status code, which still indicates
-success.
-
-Since all aspects of client-server interaction are defined in terms of HTTP,
-[RFC2616] should be consulted for any areas not covered in this specification.
-
-5.1 Catalogs
-
-5.1.1 Retrieving a Catalog
-
-Client                                     Server
-  |                                           |
-  |  1.) GET to Catalog URI                   |
-  |------------------------------------------>|
-  |                                           |
-  |  2.) 200 OK                               |
-  |      Shoji Catalog Document               |
-  |<------------------------------------------|
-  |                                           |
-
-   1. The client sends a GET request to the URI of the Catalog Document.
-   2. The server responds with a Catalog Document whose entities enumerate
-      the IRIs of its contained Entities and/or whose catalogs enumerate its
-      sub-Catalogs and/or whose views enumerate its value queries. The content
-      of this document can vary based on aspects of the client request, including,
-      but not limited to, authentication credentials.
-
-If the returned Catalog Document contains an entities member, that member MUST
-refer to all accessible Entities included in the Catalog.
-If the returned Catalog Document contains a catalogs member, that member MUST
-refer to all accessible Catalogs included in the Catalog.
-If the returned Catalog Document contains a views member, that member MUST
-refer to all accessible Views included in the Catalog.
-
-5.2 Entities
-
-5.2.1 Creating an Entity
-
-Client                                     Server
-  |                                           |
-  |  1.) POST to Catalog URI                  |
-  |      Entity Representation                |
-  |------------------------------------------>|
-  |                                           |
-  |  2.) 201 Created                          |
-  |      Location: Entity URI                 |
-  |<------------------------------------------|
-  |                                           |
-
-   1. The client POSTs a representation of the Entity to the URI of the Catalog.
-      If the Entity includes a self member, the server MAY use it as a hint to
-      construct the returned Entity URI, or it MAY ignore it.
-   2. If the Entity Resource was created successfully, the server responds with
-      a status code of 201 and a Location header that contains the IRI of the
-      newly created Entity Resource. If the client is storing the Entity Document
-      it passed in the request, it SHOULD incorporate the returned Entity IRI as
-      the self member of the Entity, overwriting any existing self member.
-
-5.2.2 Retrieving an Entity
-
-Client                                     Server
-  |                                           |
-  |  1.) GET to Entity URI                    |
-  |------------------------------------------>|
-  |                                           |
-  |  2.) 200 OK                               |
-  |      Entity Representation                |
-  |<------------------------------------------|
-  |                                           |
-
-   1. The client sends a GET request to the URI of an Entity Resource to retrieve
-      its representation.
-   2. The server responds with the representation of the Entity Resource, a Shoji
-      Entity Document.
-
-5.2.3 Editing an Entity
-
-Client                                     Server
-  |                                           |
-  |  1.) PUT to Entity URI                    |
-  |      Entity Representation                |
-  |------------------------------------------>|
-  |                                           |
-  |  2.) 200 OK                               |
-  |<------------------------------------------|
-
-   1. The client sends a PUT request to store a representation of an Entity.
-   2. If the request is successful, the server responds with a status code of 200.
-
-5.2.4 Deleting an Entity
-
-Client                                     Server
-  |                                           |
-  |  1.) DELETE to Entity URI                 |
-  |------------------------------------------>|
-  |                                           |
-  |  2.) 200 OK                               |
-  |<------------------------------------------|
-  |                                           |
-
-   1. The client sends a DELETE request to the URI of an Entity.
-   2. If the deletion is successful, the server responds with a status code of 200.
-
-5.3 Values
-
-The set of Value Names of a given Entity are fixed by the server. Their values
-are all considered potentially mutable, however, and may be any valid JSON value.
-It is important to note that a Shoji Value document may be more than just JSON
-text, which is limited to objects or arrays in part to reduce security concerns.
-Because Shoji documents do not have this restriction, Shoji clients MUST NOT use
-Javascript eval() or equivalent mechanisms in other languages to parse Shoji
-documents.
-
-5.3.1 Retrieving a Value
-
-Client                                     Server
-  |                                           |
-  |  1.) GET to Value URI                     |
-  |------------------------------------------>|
-  |                                           |
-  |  2.) 200 OK                               |
-  |      Value Representation                 |
-  |<------------------------------------------|
-  |                                           |
-
-   1. The client sends a GET request to the URI of a Value Resource to retrieve
-      its representation.
-   2. The server responds with the representation of the Value Resource,
-      a Shoji Value Document.
-
-5.3.2 Editing a Value
-
-Client                                     Server
-  |                                           |
-  |  1.) PUT to Value URI                     |
-  |      Value Representation                 |
-  |------------------------------------------>|
-  |                                           |
-  |  2.) 200 OK                               |
-  |<------------------------------------------|
-
-   1. The client sends a PUT request to store a representation of a Value.
-   2. If the request is successful, the server responds with a status code of 200.
-
-
-5.4 Use of HTTP Response Codes
-
-The Shoji Protocol uses the response status codes defined in HTTP to indicate
-the success or failure of an operation. Consult the HTTP specification [RFC2616]
-for detailed definitions of each status code. Implementers are asked to note
-that according to the HTTP specification, HTTP 4xx and 5xx response entities
-SHOULD include a human-readable explanation of the error.
-
-
-6. IANA Considerations
-
-6.1 The "application/shoji" media-type
+5.1 The "application/shoji" media-type
 
 A Shoji Document, when serialized as JSON, can be identified with the following
 media type:
 Change controller: Robert Brewer <fumanchu@aminus.org>
 
 
-7. Security Considerations
+6. Security Considerations
 
-7.1 URIs
+6.1 URIs
 
 Shoji Processors handle URIs. See Section 7 of [RFC3986].
 
-7.2 IRIs
+6.2 IRIs
 
 Shoji Processors handle IRIs. See Section 8 of [RFC3987].
 
-7.3 Spoofing
+6.3 Spoofing
 
 Shoji Processors should be aware of the potential for spoofing attacks where
 the attacker publishes a Shoji document with self or entities members,
 also take steps to determine whether the entries originated from the same
 publisher before considering them duplicates.
 
-7.4 Shoji Document Parsing
+6.4 Shoji Document Parsing
 
 Shoji Processors MUST NOT use Javascript eval() or similar mechanisms to
 parse Shoji Documents; doing so could expose them to malicious code from
 of top-most type "object" or "array", which ameliorates these vectors
 somewhat. Shoji documents do not have this restriction.
 
-8. References
+7. References
 
-8.1 Normative References
+7.1 Normative References
 [RFC2119] Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels”,
           BCP 14, RFC 2119, March 1997.
 [RFC2396] Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource"
           (JSON)", RFC 4627, July 2006
 
 
-8.2 Informative References
+7.2 Informative References
 [RFC2434] Narten, T. and H. T. Alvestrand, “Guidelines for Writing an IANA
           Considerations Section in RFCs”, BCP 26, RFC 2434, October 1998.
 [RFC4234] Crocker, D. and Overell, P., “Augmented BNF for Syntax Specifications: ABNF”,
     
     shojiIRIPatternElement = string name-separator shojiIRIPattern
     shojiIRIPatternObject =
-        begin-object
+        begin-object
         [ shojiIRIPatternElement *( value-separator shojiIRIPatternElement ) ]
         end-object
-    
+    
     shojiIdentifierMember =
         string name-separator
         ( shojiIdentifier / shojiIdentifierArray )
     shojiEntity = begin-object
                   shojiEntityElement
                   shojiSelfIRI
-                  *1( shojiEntityBodyMember )
                   *1( value-separator shojiCatalogs )
                   *1( value-separator shojiFragments )
                   *1( value-separator shojiViews )
+                  *( value-separator member )
+                  *1( shojiEntityBodyMember )
                   end-object
     
     shojiCatalogElement = DQUOTE "element" DQUOTE
     shojiCatalog = begin-object
                    shojiCatalogElement
                    shojiSelfIRI
-                   *( value-separator member )
                    *1( value-separator shojiCatalogs )
                    *1( value-separator shojiEntities )
                    *1( value-separator shojiViews )
+                   *( value-separator member )
                    end-object