JSON Schema support take2 superseeds #37

[planetis-m]

Formal rules for constructing a schema:

Top-level Schema Structure

1. Schema Definition:

   • A schema is defined using the defineSchema macro followed by a schema name.
   • The schema name should be a valid Nim identifier.

2. Definitions:

   • The definitions keyword is used to define reusable subschemas.
   • definitions are allowed only at the top level of a schema.
   • Each definition is identified by a unique name.
   • Definitions can be referenced elsewhere in the schema using the ref attribute.

Properties

3. Properties:
   • The properties keyword is used to define the properties of an object.
   • Properties are required by default.
   • The allowExtra = true attribute can be used with properties to allow additional properties.
   • Each property is defined using a key-value pair, where the key is the property name and the value is the property definition.

Property Definition

4. Property Definition:

   • A property definition can be a simple type definition, a reference or a nested schema.
   • Simple type definitions include int, float, number, string, and bool.
   • A definition may include attributes such as minimum, maxItems, format, and others specific to the property type.
   • A property can be marked as nullable using the nullable = true attribute.
   • A property can be marked as optional using the optional = true attribute.

5. Enum:

   • The enum keyword is used to specify a list of allowed values.
   • Currently, enum is specified to work only with strings.

6. References:

   • The ref keyword is used to reference a subschema defined in definitions.
   • References can only point to subschemas declared within the same schema's definitions.

Nested Structures, Arrays and Tuples

7. Nested Properties:

   • Properties can be nested, allowing the definition of complex objects.

8. Arrays:

   • Arrays are defined using the keyword items.
   • The items keyword is followed by the type, reference, or schema definition for the array elements.

9. Tuples:

   • prefixItems is an array where each item is a schema that corresponds to each index of the document's array.

Schema Composition

10. Schema Composition:

• The DSL includes a few keywords for combining schemas together.
• The keywords used to combine schemas are:
  • allOf: (AND) Must be valid against all of the subschemas
  • anyOf: (OR) Must be valid against any of the subschemas
  • oneOf: (XOR) Must be valid against exactly one of the subschemas
  • not: (NOT) Must not be valid against the given schema

Special Validation Features

11. Number Validation:

    • Numbers support the following attributes for validation:
      • minimum: Specifies the minimum value allowed for the number.
      • maximum: Specifies the maximum value allowed for the number.
      • exclusiveMinimum: If set to true, the number must be strictly greater than the specified minimum.
      • exclusiveMaximum: If set to true, the number must be strictly less than the specified maximum.

12. String Validation:

    • Strings support the following attributes for validation:
      • format: Specifies a format for the string value. Supported formats include "email", "date", "time", "date-time", "uri", "hostname", "ipv4", "ipv6", etc.
      • minLength: Specifies the minimum length allowed for the string.
      • maxLength: Specifies the maximum length allowed for the string.
      • pattern: Specifies a regular expression pattern that the string must match.

13. **Array Validation:

    • Arrays support the following attributes for validation:
      • minItems: Specifies the minimum number of items required in the array.
      • maxItems: Specifies the maximum number of items allowed in the array.
      • uniqueItems: If set to true, the array must contain only unique items.

Example Schema Definition

defineSchema ExampleSchema:
  properties:
    prop1(`type` = string)
    prop2(`enum` = ["value1", "value2"])
    prop3(`ref` = subschema)
    prop4:
      items(`type` = number)
    prop5(`type` = float, nullable = true, optional = true)
  definitions:
    subschema:
      oneOf:
        properties:
          prop6(`type` = string, format = "email")
          prop7(`type` = bool)
        prefixItems(`type` = int, `type` = bool)