Specification

[jondashkyle]

Talking about this with @jongacnik this recently, we began thinking it could be useful to create a formal specification for the type of data structure nanopage digests. This would then be applied to hypha, enoki, and other libraries could hook into this and reference it, too. A good example is monoimage.

The discussion surrounding image sizes is a good example of what could be covered in this specification. The flat-structure and paths as keys is another good example.

Another discussion could be around urls. For instance, hypha generates url, path, and source keys, each which behaves differently and is at the moment somewhat convoluted.

• url is the formatted path (e.g. /about)
• path is the actual path to the content (e.g. /content/about)
• source is the remote path for content which exists elsewhere (e.g. https://example.com/content/about)

Part of this specification could be a testing tool to ensure data is structured correctly. In this way, you wouldn’t be required to follow step-by-step to follow the specification, but could simply evaluate your tool against the specification.

Looking to collect some good resources here, and perhaps we can create a repository for this.

@jongacnik @s3ththompson

[jongacnik]

Agreed. You already mentioned, but just to concur, the main items I see to address:

• content structure: are files nested within pages? are files and pages all flat? are files and pages separate objects?
• keys: can we use keys as the definitive url?
• urls: related to above, but just agreement on url/path/source. should they look different?
• multiple image sizes (thumbnails): what does this structure look like?
• image dimensions: width, height, aspect ratio?
• incomplete content: for lazy/progressive loading of content

What's cool is seems like the spec really doesn't need much. I feel like once we agree on the above the spec is more or less there, since any other keys (things like title, text, etc) are really up to the implementer to decide.

FWIW, gonna give my initial 2-cents on the above 6:

• content structure: single content object with with files and pages on same level
• keys: key is the id of the page, rather than thinking of it as the url. The reason here is that the url for pages and files differ slightly. You want the url for a page to be the pretty one, whereas you want the url for a file to be the real path. All lookups w/in nanopage would use this id for lookups (children, files, etc) kinda like we were thinking here Use key as url if unavailable #6 (comment)
• urls: ideally we only need url. For a page, url is the formatted path, for a file, url is the content path. I could be missing something with omitting path and source here, so just lmk
• multiple image sizes (thumbnails): Multiple image sizes #9 (comment)
• image dimensions: see below
• incomplete content: _loaded key Files #7 (comment)

More or less, the shape based on above looks like:

{
  '/': {
    url: '/'
  },
  '/about': {
    url: '/about',
    title: 'About',
    text: 'Beep Boop',
    _loaded: true
  },
  '/about/file.jpg': {
    url: '/content/about/file.jpg',
    sizes: {
      500: '/content/about/file-500.jpg',
      1000: '/content/about/file-1000.jpg',
      1600: '/content/about/file.jpg', // full size file
    },
    dimensions: {
      width: 1600,
      height: 1200,
      ratio: 75
    }
  }
}

Happy to expand if any q's!

[jondashkyle]

Gonna close this in favor of the conversation being moved to a separate schema repository.

[s3ththompson]

@jondashkyle ping me when you start the schema respository! I couldn't get to this earlier in the week but I think this is a great idea and have a few things to contribute.

Generally, though +1 to everything above