Goals for this Structure Proposal

Knowledge Structure

Hypermedia sites should enable an expressive intellectual structure for creators. Good organization should be easy to create, but the responsibility for creating well-organized content ultimately lies with the creators.

Map to Presentation

The site and document structure should declare a framework for how content should be presented. It does not need to be pixel-perfect, but instead provide a guideline for client implementers so that content can be presented roughly in-line with the expectations of the creators.

Coherence and clarity of API

Site and document model should have well-defined terms, and the API should reflect the goals and principles described here.

Consistency

The Hypermedia API should be consistent throughout, when it comes to naming and design patterns.

Minimalist

Hypermedia Sites should avoid extra complexity, to reduce the implementation cost and to make it easier to learn.

Non-Goals

Changes/Operations API

This proposal describes the structure of the current state of a site. For now, the signed permanent data describes changes to the site+document model. These signed changes will be documented elsewhere.

Previous design, backwards compatibility, implementation path

Seed Hypermedia has an existing implementation with certain constraints. This proposal does not take any limitations from the existing system. Instead it is a clean approach and may make backwards-incompatible changes. If we decide that sites+documents should have this structure, we can decide what the migration strategy is. Or if we want to bend this proposal to the existing implementation

Incomplete Implementations Acceptable

Here we are focusing on the approach to the design, not on specific features. Some features described are very low-priority, and we won't ever need to implement them. The idea is to sketch our current feature requests into this model so we can figure out how they would be implemented if we do decided to build them.