Dialects

A dialect describes the valid vocabulary and structure of a model. For our catalog, it can require titles, limit currencies, and ensure that prices are integer text. The same composition, references, and targets remain available.

Use an existing dialect

A document associates its dialect explicitly in the header:

Catalog.nxscript

dialect "Catalog.Language.nxscript";

Catalog Shop {
    Title: "Corner Stationery";
    Currency: USD;
    Product Notebook { Title: "Pocket notebook"; PriceCents: 450; }
    Featured: @Notebook;
}

Save the language definition below beside that file, then run:

NexusScript /input=Catalog.nxscript /validate /output=Catalog.json

The CLI compiles the document and applies its dialect before emitting the artifact. Without /validate, the CLI still loads a declared dialect, but does not apply its subject validation rules. Nexus Build, Nexus Forge, and Setup apply their own dialect validation as part of loading their input.

A filename such as Catalog.Schema.nxscript does not choose a dialect. The explicit dialect declaration supplies that relationship.

Define the catalog language

A language definition is itself ordinary Nexus Script. Save:

Catalog.Language.nxscript

Language Catalog {
    UnknownDefinitions: Reject;
    Definitions: [
        Definition Catalog {
            Root: True;
            UnknownProperties: Reject;
            UnknownChildren: Reject;
            Properties: [
                Property Title {
                    Required: True;
                    Value Value { Scalar: Text; }
                },
                Property Currency {
                    Value Value { Scalar: Text; AllowedValues: [USD, EUR]; }
                },
                Property Featured {
                    Value Value {
                        SourceForms: [Reference];
                        EffectiveCategories: [Definition];
                        Reference Reference {
                            Targets: [Definition];
                            DefinitionKinds: [Product];
                        }
                    }
                }
            ];
            Children: [Child Products { Kinds: [Product]; Minimum: 1; }];
        },
        Definition Product {
            Root: False;
            Parents: [Catalog];
            UnknownProperties: Reject;
            UnknownChildren: Reject;
            Properties: [
                Property Title {
                    Required: True;
                    Value Value { Scalar: Text; }
                },
                Property PriceCents {
                    Required: True;
                    Value Value { Scalar: Integer; }
                }
            ];
        }
    ];
}

Definition Catalog describes declarations whose kind is Catalog; it does not require the subject's name to be Catalog. Our subject is named Shop. Likewise, the Product rule applies to Notebook, Pencil, and other Product names.

In Value Value, the first word is the kind and the second is the child name expected by the validation consumer. The same convention is required for Array Array and Reference Reference. These particular names are part of the validator's model contract, not a rule that Nexus Script kinds and names must generally match.

The root Catalog rule accepts Title, Currency, and Featured, requires a title, and requires at least one Product child. The Product rule requires Title and PriceCents. Featured must be written as a reference resolving to a Product.

Try replacing 450 with cheap, removing Title, or setting Currency to GBP. Each violates a different rule. The diagnostic identifies the source location and the failed constraint. Restore the valid value before continuing.

Source form versus effective category

A value written as @Notebook has source form Reference and effective category Definition. A value written as @Price may have source form Reference and effective category Text. Rules can constrain either or both.

Use Scalar: Integer to require integer text, not to add arithmetic or a new runtime integer type to the core language. AllowedValues compares effective text against an explicit list, case-insensitively. Those comparisons differ from case-sensitive target selection.

External text may require deferred checks when a Live consumer reads it. Structural checks still apply during validation.

Arrays and containment

An array property rule can require names, entry shapes, allowed kinds, and cardinality. This is a fragment inside a Definition's Properties array:

Property Tags {
    Value Value {
        EffectiveCategories: [Array];
        Array Array {
            Minimum: 1;
            Names: Forbidden;
            EntryEffectiveCategories: [Text];
            AllowedValues: [stationery, gifts, office];
        }
    }
}

Parents limits where a definition kind may occur. Children limits what a parent accepts and counts. These rules are independent; if both are specified, both apply. One does not automatically declare the reciprocal rule.

Reuse and validate language definitions

Because a dialect is Nexus Script, it can compose rule definitions and include files containing independently named Language roots. Included rule entries contribute to the validation language. Duplicate rule names are errors, and explicit unknown-kind policies must agree.

An application can validate a language definition against the foundational Language.nxscript supplied with Nexus. That foundational file describes the language-definition vocabulary; it does not introduce a different parser.

The dialect rules reference lists the full rule vocabulary. The embedding guide shows the validator API.

Continue with Models and generated artifacts.