spec_4.txt

The ZeroMQ Property Language (ZPL) defines a minimalistic framing language for specifying property sets, expressed as a hierarchy of name-value property pairs.

* Name: rfc.zeromq.org/spec:4/zpl
* Editor: Pieter Hintjens <ph@imatix.com>
* State: stable

++ License

Copyright (c) 2010 iMatix Corporation and contributors

This Specification is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 3 of the License, or (at your option) any later version.

This Specification is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, see <http://www.gnu.org/licenses>.

++ Change Process

This Specification is a free and open standard[((bibcite fandos))] and is governed by the Digital Standards Organization's Consensus-Oriented Specification System (COSS)[((bibcite coss))].

++ Language

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119[((bibcite rfc2119))].

++ Goals

ZPL is designed to represent a property set, where each property has a name and a value. Properties are hierarchical, i.e. properties can contain other properties. It aims to:

* Be easy to read and edit, using visual clues for semantics.
* Be minimalistic in terms of syntax.
* Be trivial to parse in any programming language.
* Be usable as a continuous stream of name/value updates.
* Be able represent hierarchical data structures.
* Be neutral with respect to data typing.
* Reduce the risk of human error to as close to zero as possible.

The use cases for ZPL include:

* Configuration files edited by hand where readability is key.
* Streamed data exchange.
* Streamed logging.

++ Specification

ZPL is an ASCII text format that uses whitespace - line endings and indentation - for framing and hierarchy. ZPL data consists of a series of properties encoded as name/value pairs, one per line, where the name may be structured, and where the value is an untyped string.

Implementations should treat any of the following sequences as a line-ending: newline (%x0A), carriage-return (%x0D), or carriage-return followed by newline (%x0A %x0D).

Here is a typical example of a ZPL file:

[[code]]
#   ZPL configuration file example
#   This format is designed to be trivial to write and parse
#
context
    iothreads = 1
    verbose = 1      #   Ask for a trace

main
    type = zmq_queue
    frontend
        option
            hwm = 1000
            swap = 25000000
            subscribe = "#2"
        bind = tcp://eth0:5555
    backend
        bind = tcp://eth0:5556
[[/code]]

Notes:

* Whitespace is significant only before property names and inside values.
* Text starting with '#' is discarded as a comment.
* Each non-empty line defines a property consisting of a name and an optional value.
* Values are untyped strings which the application may interpret in any way it wishes.
* An entire value can be enclosed with single or double quotes, which do not form part of the value.
* Any printable character except the closing quote is valid in a quoted string.
* A value that starts with a quote and does not end in a matching quote is treated as unquoted.
* There is no mechanism for escaping quotes or other characters in a quoted string.
* The only special characters in ZPL are: whitespace, '#', '=', and single and double quotes.
* Hierarchy is signaled by indentation, where a child is indented 4 spaces more than its parent.
* The first non-whitespace character in a ZPL file is always either '#' or an alphanumeric character.
* Whitespace following after a value is discarded unless within valid quotes.

Names SHALL match this grammar:

[[code]]
name = *name-char
name-char = ALPHA | DIGIT | "$" | "-" | "_" | "@" | "." | "&" | "+" | "/"
[[/code]]

++ Justification and Design

ZPL exists because alternatives were inadequate:

* XML cannot be read or written as a stream.
* JSON cannot be read or written as a stream and is clumsy to edit due to delimiters between item lists.
* YAML is relatively complex to parse.
* UNIX-style configuration syntax does not support name hierarchies.

The use of significant whitespace may be controversial. It is meant to be easier to create and verify manually than syntax elements such as braces. It eliminates the need for separators. The fixed 4-character indentation is meant to avoid confusion and errors when fragments of ZPL files from different sources are mixed together.

The lack of type awareness and other semantic validation is deliberate. ZPL is not meant to be a formal grammar but a simple-to-parse framing for name/value pairs. It emulates 0MQ insofar as it frames data but does not attempt to inspect or validate that data.

++ References

[[bibliography]]
: rfc2119 : "Key words for use in RFCs to Indicate Requirement Levels" - [http://tools.ietf.org/html/rfc2119 ietf.org]
: json : "Introducing JSON" - [http://json.org/ json.org]
: fandos : "Definition of a Free and Open Standard" - [http://www.digistan.org/open-standard:definition digistan.org]
: coss : "Consensus Oriented Specification System" - [http://www.digistan.org/spec:1/COSS digistan.org]
[[/bibliography]]