Skip to main content

Hjson

Juneau supports converting arbitrary POJOs to and from Hjson (Human JSON) using native serializers and parsers. Hjson is a syntax extension of JSON designed for human-friendly configuration files and hand-edited data. It extends JSON with quoteless strings, multiline strings, comments, optional commas, and unquoted keys.

The HjsonSerializer converts POJOs directly to Hjson format, and the HjsonParser creates POJOs directly from Hjson.

Hjson support is included in juneau-marshall.

Maven
<dependency>
    <groupId>org.apache.juneau</groupId>
    <artifactId>juneau-marshall</artifactId>
    <version>${juneau.version}</version>
</dependency>

Quick Start​

// A simple bean
public class Person {
    public String name;
    public int age;
    public Person() {}
    public Person(String name, int age) { this.name = name; this.age = age; }
}

// Serialize to Hjson (readable mode)
Person alice = new Person("Alice", 30);
String hjson = Hjson.of(alice);

Produces:

{
  name: Alice
  age: 30
}

Parsing​

// Parse Hjson into a bean
Person parsed = Hjson.to(hjson, Person.class);

// Parse into a map
JsonMap map = Hjson.to(hjson, JsonMap.class);

// Parse root-braceless Hjson (no outer {})
String rootBraceless = "name: Bob\nage: 25";
Person bob = Hjson.to(rootBraceless, Person.class);

Serialization Modes​

// Readable mode (default) - newlines between members, quoteless strings
String hjson = Hjson.of(bean);

// Compact mode - single line, comma-separated (via the HjsonC variant marshaller)
String compact = HjsonC.of(bean);

The compact configuration is exposed as the dedicated HjsonC variant marshaller (backed by HjsonSerializer.DEFAULT_COMPACT). It is a first-class Hjson facade, so it exposes the same static of(...) / to(...) shortcut surface as Hjson itself. (This replaces the former Hjson.DEFAULT_COMPACT constant, removed in 10.0.0.)

Hjson Syntax Highlights​

  • Quoteless strings: name: Alice (no quotes when unambiguous)
  • Multiline strings: Triple single-quote blocks with indentation stripping
  • Comments: #, //, and /* ... */ block comments
  • Optional commas: Newlines can separate object members
  • Trailing commas: Ignored
  • Unquoted keys: Object keys need not be quoted when safe

Bean-to-Hjson Mapping​

  • Maps and beans → Hjson objects
  • Collections and arrays → Hjson arrays
  • Strings → Quoteless (when safe), double-quoted, or multiline
  • Numbers → Hjson numbers
  • Booleans → true / false
  • Null → null
  • ObjectSwaps → Applied for non-primitive types (dates, enums, etc.)

Media Types​

  • Produces: application/hjson
  • Accepts: application/hjson, application/hjson+json

REST Integration​

// Hjson is included in BasicUniversalConfig
@Rest
public class MyResource extends RestServlet implements BasicUniversalConfig { ... }

Round-Trip Notes​

  • Root-braceless Hjson can be parsed; serialization always emits root braces by default
  • Strings equal to true, false, null, or parseable as numbers are automatically quoted on output to prevent ambiguity
  • In compact mode, multiline strings use JSON escape sequences instead of ''' blocks

Annotations​

@HjsonConfig sets serializer/parser properties on a REST class or method (see Context Annotations). Attributes are strings ("true"/"false"):

AttributeDescription
useMultilineStringsUse ''' blocks for strings containing newlines (default true).
useQuotelessStringsOmit quotes for simple string values.
useQuotelessKeysOmit quotes for simple keys.
omitRootBracesOmit the root object braces (default false).
useNewlineSeparatorsSeparate members with newlines instead of commas.
rankOrdering relative to other config annotations.
@Rest
@HjsonConfig(useQuotelessKeys="true", omitRootBraces="true")
public class MyResource extends BasicRestServlet { ... }

@Hjson is a marker annotation (no attributes) for classes, methods and fields. @HjsonApply applies it to other classes/members via on()/onClass() (see Dynamically Applied Annotations).

See Also