# RSConf - A data format somewhere between JSON and hjson
Author: Remilia Scarlet<br/>
Version: 1.3<br/>
Last Updated: 12 March 2026
## Introduction
RSConf has a few more features than JSON that make it nicer for config files,
such as comments, not needing commas, and unquoted strings. But it it's less
strict and has fewer features than hjson to keep parsing simple.
It was created to fill a niche and scratch an itch for a nice, easy-to-use
config format that doubles as a data serialization format. JSON is nice and
(usually) easy to visually parse as a human, but is too strict with its syntax,
and doesn't have comments. YAML is nice, but has far too many bells and
whistles, leading to all sorts of strange edge cases, and a large space for
possible security problems. TOML is ugly, and I just don't like it. Hjson is
nice, but has a few too many unnecessary features for my liking, and is a bit
too flexible. Thus, RSConf was born to fill the hole left by these other
formats.
As a high-level overview, RSConf is like JSON, but:
* Keys don't need quoting if they do not contain spaces.
* Commas don't need to come after values/key-value pairs unless there are
multiple values/key-value pairs on the same line.
* Top-level braces (`{` and `}`) can be omitted if the top-level is an object.
* Integers and floats are differentiated.
* Integers can be in hex, octal, or binary. Floats can be in decimal or
"scientific notation" (and accept either `e` or `d` for their character).
* The null value is called `nil`.
* Comments are allowed and use semicolons (`;`)
* Explicit minimum limits for integers and floats.
* Stricter whitespace.
It is also a lot like hsjon, except:
* All strings are multi-line strings; no separate syntax.
* No quoteless strings.
* Integers can be in hex, octal, or binary. Floats can be in decimal or
"scientific notation" (and accept either `e` or `d` for their character).
* The null value is called `nil`.
* Comments are allowed and use semicolons (`;`)
* No multi-line comments.
* Explicit minimum limits for integers and floats.
* Slightly stricter whitespace.
Some well-formatted example RSConf data:
```
;;;;
;;;; Example Document
;;;;
some-object: {
values: [ 1, 2, 3] ;; Recommended syntax for short arrays
;; Better syntax for larger arrays, or ones with long values.
values-2: [
"foo"
"bar"
"baz"
]
name: "test"
sub-obj: {
id: 1, ;; Comma here is optional
enabled: false ;; or "true"
something-else: nil ;; Null values are represented with "nil"
}
}
```
### Notation Used
This spec document uses Common Lisp-style hexadecimal/octal/binary numbers.
This means #xA7 instead of 0xA7, #o25 instead of 025, and #b1011 instead of
0b1011.
## Specification
The name of the format is RSConf, with that capitalization. It is pronounced
"Arr-Ess-Konf" and stands for Remilia Scarlet's Config Format.
### Encoding
Files *MUST* be UTF-8 encoded without a byte-order marker. No other encoding is
valid. The two recommended file extensions are .rsconf and .rsc
The following UTF-8 codepoints are considered whitespace (note the absence of
#x0D, Return): #x0A (newline), #x20 (space), and #x09 (tab). Other UTF-8
codepoints that are normally considered whitespace are not allowed, except
within string values. Other types of whitespace must signal an error.
Additionally, it is highly recommended, but not required, that you use spaces
(#x20) instead of tabs (#x09) for RSConf files.
### Line Endings
Line endings must be "UNIX-Style", meaning only the newline character (UTF-8
character #x0A). Any return character (#x0D) or page character (#x0C) outside
of a string must raise an error and must not be counted as whitespace. All
other valid whitespace characters, as defined in the Encoding section above, are
counted as whitespace and ignored outside of strings.
### Comments
There are only single-line comments, which always starts with one or more
semicolons and continues to a newline (#x0A). Lisp-style comments, where the
number of semicolons vary on the depth, is recommended. Comments **MUST NOT**
contain parsing directives or similar. Conforming implementations **MUST NOT**
allow parsing directives, or they cannot claim to be conforming to the RSConf
specification, nor claim to support RSConf. RSConf explicitly disallows any
sort of data or metadata within comments that can be used during or after
parsing. Comments are there for human eyes only.
### Scalar Values
There are five types of scalar values: integers, floats, strings, booleans, and
the null value.
Integer values can be in decimal (12345), hexadecimal (#xA7, #xDEADBEEF), octal
(#o64, #o23), or binary (#b1100101, #b1011). Non-decimal values must start with
an ASCII `#` (#x35) followed by a letter. This letter indicates the radix. The
entire value, regardless of radix (or lack of radix), continues to the end of
the line, a comma (#x2C), a comment character, or other whitespace as defined in
the Encoding section above.
There are restrictions on the allowed characters in integer values, depending on
the radix.
* For decimal, there must not be a radix. The value must only contain ASCII `0`
through `9`.
* For binary, the radix must be indicated with the ASCII letter `b` or `B` (#x98
or #x66). The value must only contain ASCII `0` or `1`.
* For octal, the radix must be indicated with the ASCII letter `o` or `O` (#x111
or #x79). The value must only contain ASCII `0` through `7`.
* For hexadecimal, the radix must be indicated with the ASCII letter `x` or `X`
(#x120 or #x88). The value must only contain ASCII `0` through `9`, and
either ASCII `A` through `F` or `a` through `f` (or a mixture of these
ranges).
Implementing parsers must support integer values that can be represented as
64-bit signed integers. Greater limits are allowed.
Floats can only use decimal or "scientific notation". Decimal format starts
with a number, then continues until a period (`.`, #x2E) is reached. After that
may be additional decimal numbers. The float continues to the end of the line,
a comma, a comment character, or other whitespace as defined in the Encoding
section above. Only the ASCII digits are allowed (#x48 through #x57) for the
digits. There is no support for floats using any other radix.
Floats can use "scientific notation" in the form `X.Ye+Z` or `X.Ye-Z` or `X.YeZ`
if desired. This form uses the ASCII letter `E` (#x69) or `e` (#x101). The
ASCII letter `D` (#x68) or `d` (#x100) can be used in place of `E` or `e` as
well. This is done for compatibility with Common Lisp. Implementing parsers
must support values that can be represented with *at least* 50 bits of precision
and an 8-bit exponent; larger limits are allowed.
Deserialization of RSConf data can still places stricter/looser restrictions on
the integer and float values as-needed. For example, deserialization code can
place a constraint on an integer key so that it must contain a 8-bit unsigned
integer. But they must allow for values up to at least the minimum limits
described above.
String values must be quote. They start with a double quote (character #x22)
and continue to another double quote. This means all strings are "multi-line"
strings.
The backslash character (`\`, #x5C) is used for escaping characters in a string.
Double quotes that appear within strings must be escaped, e.g. the string
`"hello \"world\""`.
Unicode characters may optionally be escaped with `\u{X}`, where `X` is always
in hexadecimal and is the Unicode code point. It must be at least one hex digit
long.
Given this, the only special escapes that do anything within strings are for
double-quotes (`\"`) and for UTF-8 characters (`\u{X}`). All other escapes
simply produce the character they escape, e.g. `"foo\abar"` results in the same
string as `"fooabar"`.
Strings can contain any type of UTF-8 whitespace, not just #x0A (newline), #x20
(space), and #x09 (tab).
Booleans are the symbols `true` or `false`; these are case-sensitive and must be
lower-case.
The null value is the symbol `nil`. This is also case-sensitive and must be
lower-case.
### Composite Values
There are two types of composite values in RSConf: objects and arrays.
An object starts with an open brace (`{`, character #x7B) and end with a close
brace (`}`, character #x7D). Within these braces are zero or more key-value
pairs.
Arrays start with an open bracket (`[`, character #x5B) and end with a close
bracket (`]`, character #x5D). Within these brackets are zero or more values
(never key-value pairs).
### Keys and Values
Keys can be quoted or unquoted. For an unquoted key, the key name starts with a
non-whitespace character and continues until whitespace or a colon (character
#x3A) is reached. "Whitespace" here means whitespace as defined in the Encoding
section above. A newline (#x0A) is **not** permitted in an unquoted key between
the key name and a colon; a colon must appear on the same line as the unquoted
key name it terminates. All whitespace before an unquoted key name is ignored.
All whitespace except for the newline (#x0A) after the key name and before the
colon is ignored.
Quoted keys are treated like string scalars, and thus all characters within them
are accepted. All whitespace, as defined in the Encoding section above, that
comes before the opening double-quote is ignored. All whitespace except for
newlines (#x0A) after the closing double-quote is ignored. Quoted keys
**cannot** have a newline character between its ending quote and the colon.
Key names cannot be an empty string (`""`). Key names are always
case-sensitive.
It is recommended that you use unquoted keys whenever possible. Lowercase
skewer-case names (e.g. `key-name`, `this-is-a-key`) that don't need quoting are
highly recommended, but not required. Underscores in key names are allowed, but
highly discouraged.
The value associated with the key comes after the colon character. All
whitespace (as defined in the Encoding section above) after the colon and before
the value is ignored.
Values, whether as part of a key-value pair or as a value within an array, may
optionally be terminated with a comma (character #x2C). This comma **MUST** be
on the same line as the value it terminates; all whitespace as defined in the
Encoding section above, except for a newline (character #x0A), is ignored
between the value and a comma.
As an alternative, multiple key-value pairs and values may exist on the same
line in both objects and arrays, but **MUST** be separated by commas. If no
additional keys come after the final value, then the trailing comma (character
#x2C) is optional.
Empty values, and multiple commas in succession (regardless of whitespace
between them), are not allowed and must signal an error.
### Documents
The top-level is called the "document". A document must consist of a single
object or a single array. When a document consists of an object, then the
top-level braces (`{` and `}`) may optionally be omitted and it is assumed all
key-value pairs are part of the top-level object.
Duplicate keys (more than one key with the same name at the same level) are
allowed, but later keys override earlier keys. It's highly recommended that a
warning be presented in some way when duplicate keys at the same level are
detected, but this is not required.
## Changelog
* v1.3, 12 Mar 2026: Clarified the characters allowed in integers, the radix for
integers, and floats. Clarified that mix-case hexadecimal is allowed.
* v1.2, 31 Dec 2025: Whitespace outside of string values is now more strictly
defined. Specifically, only ASCII spaces, newlines, and tabs are allowed.
* v1.1, 25 Sep 2025: Changed how escapes work so that it matches other
languages.