HONEY

HONEY is the human-friendly object notation that easily converts to JSON.

Built by @rymohr for Kumu.

Here's an example of what it looks like:

// WARNING: The syntax is still evolving and awaiting a solid round of
// constructive feedback and criticism. Do not use in production until
// a 1.0 release is reached.

name
  HONEY

version
  0.1.0

description
  HONEY is the human-friendly object notation that easily converts to JSON.

  It's a simple line-based, whitespace-sensitive file format, designed to
  play well with humans.

tags
  - stringify
  - parse
  - honey
  - json
  - javascript

HONEY is a blend of JSON's simplicity and markdown's legibility, designed to play well with version control systems and not scare off humans.

// lists of lists (yup, comments are supported)
-
  - one
  - two

-
  - three
  - four


// list of objects
-
  id
    1

  name
    One

-
  id
    2

  name
    Two

// empty values
empty list
  []

empty object
  {}

empty string
  ""

null value
  null

Goals

• don't scare humans
• minimize syntax handling in version control conflicts

Features

• minimal syntax
• comments
• multi-line strings without funky escape sequences
• implicit type inference following JSON rules
• easily translates to / from JSON

Usage

This repo includes a reference implementation written in es6. You are free to copy, modify, and redistribute it at will. For convenience the package is available as hny on NPM. It will be updated as the spec evolves.

import HONEY from "hny";

HONEY.parse(string)
HONEY.stringify(value)

Specifics

Naming

HONEY files should use .hny or .honey. The shorter form is preferred.

Indentation

HONEY strictly requires soft two-space indentation.

// right
name
  HONEY

// wrong
name
    HONEY

// wrong
name
\tHONEY

Comments

HONEY supports single-line comments, javascript style. Inline and multi-line comments are not supported.

// this is
// a comment
name
  HONEY // this is NOT a comment

Type inference

HONEY supports the same types as JSON:

• string
• number
• object
• array
• true
• false
• null

You can wrap any value in double quotes to skip the implicit typecasting:

// this will be a number
version
  1.0

// this will be a string
version
  "1.0"

Multi-line strings / heredocs

Multi-line strings should work just fine in most cases without any special handling. However, if you have text that looks similar to HONEY's object notation you'll need to use the heredoc form:

description
  This is a multi-line string.
  It doesn't require anything fancy.

// if in doubt, use a heredoc
description
  """
  - one
  - two
  - three
  """

Leading whitespace is automatically trimmed up to the natural indentation.

Why not use JSON / CSON / YAML / TOML?

JSON's simple structure is great but the syntax is a little too technical for humans. Being scolded for forgetting a comma (or adding a trailing one) is something only developers put up with. It's also really awful for multi-line strings (such as markdown fields) and doesn't allow comments.

YAML is potentially dangerous, mostly because it tries to do too much. And the syntax is still a little too technical.

CSON is getting closer, but doesn't permit special characters in object keys unless you quote them and still requires colons for each key. The markdown approach to lists is much more intuitive than brackets, quotes, and commas for each value. It's nice to be able to omit the commas, but for long lists the arrays-without-commas syntax quickly stops looking like a list.

TOML claims to be obvious and minimal, but that's only the case if you're a developer. Overall it still feels like you're writing code, which is fine since it was designed for config files, not general data. Still too technical for humans.

Contributing

git clone [email protected]:honey/honey.git
cd honey
npm install -g babel
npm install
npm test

Got a proposal for simplifying HONEY's syntax even further? Great! Open an issue or submit a pull request.

I'd still love to see a more natural way to handle empty lists and objects.

TODO

• [ ] decide if stringify should enforce newline at end of file
• [ ] add tests for invalid syntax
• [ ] write syntax highlighter for atom
• [ ] write syntax highlighter for linguist