The following standard defines how to describe complex DSON object schema specifications in DSON.

Preface

It is common to have a need to describe an DSON object structure schema: what properties can it have of which types.

The DSON Object Schema Specification Standard standardizes a way to define such a schema using a DSON document.

For example, the following DSON object:

{
  name = "John",
  age = 18,
  hobbies = [{
    id = standards,
    about = "Loves to write different standards"
  }]
}

Matches the following schema:

{
  types = [{
    name = hobby,
    fields = [{
      name = id,
      type = string,
      required = true
    }, {
      name = about,
      type = string,
      required = false
    }]
  }],

  fields = [{
    name = name,
    type = string,
    required = true
  }, {
    name = age,
    type = num,
    required = false
  }, {
    name = hobbies,
    type = array<hobby>,
    required = false
  }]
}

The standard follows Semantic Versioning 2.0.

Glossary

schema object

The DSON object containing a schema definition.

described object

A DSON object the schema is defined for.

1. Specification

1.1. Types

The standard defines a type system which allows to restrict a described object's properties to certain types.

1.1.1. Basic DSON types

There is a number of built-in types natural to DSON:

  • The string type corresponds to a DSON string.

  • The object type corresponds to a DSON object.

  • The array<T> type corresponds to a DSON array, e.g. array<string> or array<object>.

1.1.2. Additional scalar types

Due to the lack of scalar types in DSON other than strings, the following types are defined:

  • num represents a numeric value. A value of this type must be an optionally signed integer or a floating-point number, e.g. 42 or -17.5.

  • bool represents a boolean value. A value of this type must be a string with either true or false value.

1.1.3. Special types

Special types are defined:

  • The variant<T> type defines a list of possible types delimited by comma, e.g. variant<object, string, my_type>.

  • The enum<V> type defines a list of possible exact scalar values, e.g. enum<42, foo>.

  • The field type represents a DSON object property.

  • The type type represents a user-defined type.

1.1.4. field type

The field object type defines an object describing a DSON object property.

An object of type field may contain the following properties itself:

  • Required name property of type string.

  • Required type property of type string representing a type from the type system.

  • Optional desc property of type string.

  • Optional required property of type bool with a default value of false.

  • Optional default property of the same type as the type property.

1.1.5. User-defined types

A Schema object may contain user-defined object type declarations of type type in its types property.

User-defined types can be referenced by the value of the name property of a type object.

Referencing an undefined type, i.e. the one which is not defined in the schema object’s types property, is errornous.

An object of type type may contain the following properties itself:

  • A required name property of type string.

  • An optional desc property of type string.

  • A required fields property of type array<field>.

1.2. Schema object

A DSON document representing a schema must consist of a single DSON object referenced as the schema object.

The schema object may contain the following DSON properties:

  • Optional name property of type string.

  • Optional desc property of type string.

  • Required ver property of type string, representing current version of the schema.

    Tip
    		 Schema definition authors are encouraged to use Semantic Versioning for their schemas.

  • Optional types property of type array<type>.

  • Required fields property of type array<field>.

Appendix A: Standard defining itself

The standard can be partially defined using itself:

{
  name = "DSON Object Schema Specification Standard",
  desc = "The standard defining itself",
  ver = 0.0.0,

  types = [{
    name = type_def,
    desc = "A user-defined type",
    fields = [{
      name = name,
      type = string,
      desc = "Name of the type"
      required = true
    }, {
      name = desc,
      type = string,
      desc = "Description of the type",
      required = false
    }, {
      name = fields,
      type = array<field_def>,
      desc = "Fields of the type",
      required = true
    }]
  }, {
    name = field_def,
    desc = "An object field",
    fields = [{
      name = name,
      type = string,
      desc = "A field name",
      required = true
    }, {
      name = type,
      type = string,
      desc = "A field type restriction",
      required = true
    }, {
      name = desc,
      type = string,
      desc = "A field description",
      required = false
    }, {
      name = required,
      type = bool,
      desc = "Whether is the field required",
      default = false
    }, {
      name = default,
      type = string,
      desc = "A default value for the field of matching type",
      required = false
    }]
  }],

  fields = [{
    name = name,
    type = string,
    desc = "The schema name"
  }, {
    name = desc,
    type = string,
    desc = "The schema description"
  }, {
    name = ver,
    type = string,
    desc = "The schema version"
  }, {
    name = types,
    type = array<type_def>,
    desc = "Types defined for the schema",
  }, {
    name = fields,
    type = array<field_def>,
    desc = "The top-level object fields",
    required = true
  }]
}