Quickstart

Polygen randomly generates JSON documents. You provide an input specification, describing the desired structure of your output, and Polygen will generate a document that satisfies that specification. Polygen specifications are written in a superset of JSON, extended with generators and some special forms (described below).

A simple request you can try:

$ curl https://polygen.dev -d '{ age: int:gt(17):lt(55) }'

which generates the following result:

{ "age": 32 }

Principles

Polygen optimises for speed and simplicity. You should expect low latency responses (though we don't provide any guarantees yet). The spec language is made from a small number of building blocks that can be composed to describe arbitrarily complex documents.

API

Our API either returns verbatim JSON or a structured error (also in JSON). Any 4XX or 5XX status code should be considered an error and should be parsed as such. See the errors section for more info.

              
{
  "name": "Ada",
  "age": int:gt(17):lt(55)
}
              
            

              
{
  "name": "Ada",
  "age": 18
}
              
            

Reference

>> Input format

The API accepts input in a custom format which is a superset of JSON. Any valid JSON value is a valid Polygen input. In addition, we support the following additional features:

• Trailing commas are permitted in arrays and objects.
• Quotes around object keys are optional.
• Generators may be specified by writing their name verbatim.
• The special forms or, many and some.

For example, the following document is a valid Polygen input:

{
  message: string/sentences,
  created_at: datetime/rfc3339,
  id: int,
  visibility: or("public", "private"),
}

This defines a JSON object with four fields. The field message will have a value populated by the generator string/sentences. created_at will be populated by the generator datetime/rfc3339, and so on. The field visibility will have either the value "public" or "private".

Here is an example output for this specification:

{
  "created_at":"1862-11-24T19:49:31.778373274+00:00",
  "id":945308904754117,
  "message":"ducimus reprehenderit quae voluptates libero et sit iste.",
  "visibility":"private"
}

>> Special forms

There are three special forms that can be used in the input format.

or

    or("public", "private", 1, true, null, string/ascii)

or takes one or more arguments and randomly selects one of them to use as the output. The arguments can be any valid input element, including literal JSON, generators and special forms.

some

    some(int)

some takes a single argument and produces an array containing one or more elements generated from the argument. The argument can be any valid input element.

many

    many(int)

many is like some, but it can produce an empty array.

>> Generators

>> Guards

Some generators can be suffixed with guards, which constrain the range of values they can produce. Guards are written directly after the generator, separated by a colon. For example, the input int/u8:gt(0):lt(10) generates an integer between 1 and 9.