Data Definition Language Schema (draft, v0.2)

1 Introduction

This draft specifies the Data Definition Language Schema (DDLS), a declarative way to describe constraints on values written in the Data Definition Language (DDL). It is intended for readers of DDL who need to describe or validate structured data.

A DDLS schema is itself written as a DDL value. A DDLS reader interprets that value as a schema; a validator then checks a separate DDL value against a named schema. Read the DDL semantical translation first for the DDL value model. This page describes DDLS values and validation, not a replacement for the DDL lexical or syntactical rules.

For orientation, the reader accepts a top-level DDL map with kind: "Schema", a schema name, and a definition map. The schema translation and the other type descriptions explain how DDLS values are read; the validation section describes acceptance.

2 Notation

This specification describes DDL values as defined by the DDL semantical translation. Names such as kind and name denote entries in a DDL map; quoted words such as "Map" denote DDL string values. A DDLS value is the interpretation of a DDL schema description, not the DDL value being validated.

DDLS definitions have these kinds: Any, Boolean, Choice, List, Map, Number, SchemaReference, String, and Void. The scalar kinds are Boolean, Number, String, and Void; List and Map are aggregate kinds. A Schema names a definition; a MapEntry describes one entry within a map definition. Neither is itself a definition kind.

3 Semantics

The following sections describe how a DDL map is interpreted as a DDLS schema or definition. If a required field is missing, has the wrong kind, or a nested definition cannot be read, translation fails. The draft names these error categories; they describe language outcomes, not a promise that the current C API returns a structured error value.

DDLS error categoriesScroll horizontally if needed.
Error	Meaning
`InvalidDefinitionError`	A schema description cannot be interpreted as a valid definition.
`SchemaNotFoundError`	A referenced or starting schema is unavailable.
`SchemaAlreadySpecifiedError`	A schema name is specified more than once.
`CyclicDefinitionError`	A schema-reference cycle is reachable from the starting schema.
`ValidationError`	A DDL value fails to satisfy a usable schema.

3.1 Any type

A DDL map with the single entry kind: "Any" describes the DDLS Any definition. It accepts any DDL value during validation.

3.2 Boolean type

A DDL map with the single entry kind: "Boolean" describes the DDLS Boolean definition. It accepts DDL boolean values.

3.3 Choice type

A DDL map with kind: "Choice" and a choices entry describes a DDLS choice definition. The choices value must be a non-empty DDL list. Read each list element, in order, as a DDLS definition; the resulting list is the choice's alternatives.

If the list is empty, or if an element cannot be read as a DDLS definition, report InvalidDefinitionError during schema translation.

3.4 List type

A DDL map with kind: "List" and an elements entry describes a DDLS list definition. The elements value must be a DDL map describing a DDLS definition; it specifies the type of every element in the DDL list being validated. If that nested description cannot be read as a DDLS definition, report InvalidDefinitionError.

3.5 Map type

A DDL map with kind: "Map" and an entries entry describes a DDLS map definition. The entries value must be a DDL list of map-entry descriptions. Read each list element as a MapEntry, retaining its order. If an element is not a valid MapEntry, report InvalidDefinitionError. Two entries with the same name do not form a valid map definition.

Map entry

Each map-entry description is a DDL map containing kind: "MapEntry", a string name, and a type map that describes a DDLS definition. The entry may also contain optional. This field is a DDL string, not a DDL boolean: only "true" and "false" are allowed. If absent, it defaults to false. Entry fields are matched by name, regardless of their order in the DDL map.

Map entry translationScroll horizontally if needed.
Optional field	Result
Absent or `"false"`	A required entry with the given `name` and `type`.
`"true"`	An optional entry with the given `name` and `type`.
Any other value	The entry description is invalid.

The type map must itself be a valid DDLS definition. An invalid nested definition makes the map-entry description invalid.

3.6 Number type

A DDL map with the single entry kind: "Number" describes the DDLS Number definition. It accepts DDL number values.

3.7 Schema type

A DDL map with kind: "Schema", a string name, and a definition map describes a named DDLS schema. The definition map must describe one of the DDLS definition kinds in this section. If the name or definition cannot be read, or the definition does not describe a DDLS value, report InvalidDefinitionError during schema translation. A malformed schema description is not a validation failure of a DDL value.

3.8 Schema reference type

A DDL map with kind: "SchemaReference" and a string name describes a DDLS schema reference. The name identifies the schema to use when this definition is validated; the reference is not itself the referenced schema's definition.

3.9 String type

A DDL map with the single entry kind: "String" describes the DDLS String definition. It accepts DDL string values.

3.10 Void type

A DDL map with the single entry kind: "Void" describes the DDLS Void definition. It accepts DDL void values.

4 Validation

A validation context contains named schemas. Each schema has a name and a definition. Validation begins with one schema name and a DDL value to check. The elements field in a List definition describes each DDL list element; a Map definition has an entries list of named MapEntry definitions. Each map entry has a type and an optional flag.

4.1 DDL value validation

Validation has one successful outcome or an error. A successful outcome means that the DDL value satisfies the starting schema. An error means either that the value does not satisfy the schema or that the schema cannot be used. The error categories distinguish these cases.

Find the starting schema by name in the validation context. If none exists, report SchemaNotFoundError. If the context contains two schemas with the same name, report SchemaAlreadySpecifiedError. Otherwise validate the DDL value against that schema's definition as described below.

Example (accepted): Read this DDL value as a DDLS schema and register it under the name MySchema:

{ kind: "Schema", name: "MySchema", definition: { kind: "Any" } }

With MySchema selected, each of the following separate DDL values is accepted by Any:

true
[1, true, "w"]

Example (invalid schema): Replacing the definition with { kind: "Choice", choices: [] } makes the schema description invalid during reading; it is not a rejected DDL value. This is an InvalidDefinitionError in the draft's language-level categories.

4.2 DDLS value validation

Check the DDLS definition against the DDL value as follows. When a check fails, report a ValidationError unless a more specific schema error applies.

Validation by definition kindScroll horizontally if needed.
DDLS definition	When the DDL value satisfies it
`Any`	Any DDL value satisfies it.
`Boolean`, `Number`, `String`, `Void`	The DDL value has the corresponding kind.
`List`	It is a DDL list and its elements satisfy the list rule.
`Map`	It is a DDL map and its entries satisfy the map rule.
`Choice`	At least one alternative satisfies the DDL value.
`SchemaReference`	The referenced schema's definition satisfies the DDL value; see schema reference resolution.

For a Choice, alternatives are considered in their listed order. An ordinary mismatch allows the next alternative to be tried; the first matching alternative accepts the value. If none matches, report a ValidationError. A structural schema error is not an alternative mismatch and stops validation, even if the erroneous alternative would not be tried after an earlier match. An empty choices list is rejected during schema translation, before validation.

4.3 DDL list value validation

A List definition applies only to a DDL list. Each list element must satisfy the definition in elements. Check the elements in order and stop at the first failure; an empty DDL list satisfies this rule.

4.4 DDL map value validation

A Map definition applies only to a DDL map. Its entries list must not describe the same name twice; a duplicate name makes the schema definition invalid. The DDL map must not contain duplicate names either.

Every DDL map entry must have a matching name in the schema's entries list. Unknown entries fail validation.
Every schema entry whose optional flag is false must be present in the DDL map. An optional entry may be absent.
Every present entry, including an optional one, must satisfy its type definition. Stop at the first failure.

The optional flag defaults to false; see the MapEntry translation for its DDL representation.

4.5 Schema reference resolution

A SchemaReference names a schema in the validation context. Register the intended schemas before validating a value; this permits forward references between their definitions. Then check every definition reachable from the starting schema, including all choice alternatives, list element definitions, and both required and optional map entry types. Unrelated schemas that cannot be reached from the starting schema are not part of this check. If any referenced schema name is unavailable, report SchemaNotFoundError. If a schema-reference cycle is reachable, report CyclicDefinitionError. Shared references reached along different acyclic paths are not cycles. When these checks succeed, validate each reference against its named schema's definition.

4.6 Acceptance and rejection

A DDL value is accepted if validation succeeds. A ValidationError rejects the value. An unavailable, duplicate, invalid, or cyclic schema is an error in the validation context or schema description; it does not produce an acceptance verdict.

Implementation note: These errors are language-level categories, not C API return types. The current validator signals failures with a semantic-error status and diagnostics rather than returning DDLS error values.