Understanding Nexus Script

Nexus Script is a language for describing structured information and the relationships that give that information meaning. You can define something once, refer to it elsewhere, compose a new definition from existing definitions, and select the definitions appropriate to a particular situation.

Those relationships are part of the model. They let you describe a family of related products, application settings, build recipes, schemas, or installation choices without maintaining an independent copy of every variation.

This guide assumes programming experience, but no prior knowledge of Nexus Script. It develops a small stationery catalog so you can learn the language without first learning a build system or framework.

What you author

A definition is a named piece of information with a kind, properties, and possibly nested definitions. In Product Notebook, Product identifies the kind of thing and Notebook identifies this particular definition.

A property gives a definition a named value: for example, a title or price. A value can also refer to something already declared. A child definition belongs inside another definition: a product might belong to a catalog.

Definitions can have several kinds of relationships:

Relationship	Meaning in a catalog
Containment	The catalog contains a Notebook product
Reference	The catalog's featured product refers to that Notebook
Composition	Notebook draws shared properties from StandardProduct
Target selection	The selected sales region chooses the applicable Notebook declaration

Each relationship answers a different question. Containing a definition, referring to it, and composing from it are not interchangeable operations.

What compilation produces

The authored model is what you write, including contributors, references, and target clauses. The effective model is the result after the applicable definitions have been selected and their composition and internal references have been resolved. “Effective” simply means the value or structure that a consumer actually receives after those rules have been applied.

For example, you may write a shared price once and override it for Notebook. The effective Notebook has its final price. A reference to Notebook still identifies that product. The model can therefore contain links as well as a hierarchy of parents and children. This is why the documentation sometimes calls it a graph: named things connected by relationships.

External values supplied by an application can remain deferred until the application reads them. The external values chapter explains that additional step after the basic model is established.

Language, dialect, and consumer

These three responsibilities are worth separating from the beginning:

Part	Responsibility
Nexus Script language	Parse declarations and construct their relationships, composition, and selected model
Dialect	Describe which kinds, properties, values, and relationships are valid for a particular use
Consumer	Interpret the model: display products, generate files, build software, install a release, or perform other domain work

Product has no built-in selling behavior. Likewise, a Nexus Forge CopyFile definition does not copy anything merely because Nexus Script compiled it. Nexus Forge interprets that definition and performs the operation. A dialect can validate its shape; the consumer provides its behavior.

A document can be compiled without a dialect. That is useful for learning, exploration, and models whose application supplies its own checks. A dialect adds explicit domain rules without replacing the language's relationship model.

Learning sequence

Follow these chapters in order on your first visit. Each complete source example has a filename; fragments are identified as fragments.

1. Your first document: declare a catalog and inspect its output.
2. Structure, values, and identity: understand what each part represents.
3. References: connect existing information.
4. Composition and inheritance: construct related definitions from shared contributors.
5. Targets: select the model for a particular situation.
6. Documents and assembly: share definitions and assemble output across files.
7. External values: obtain values from a consuming application.
8. Dialects: use and author explicit validation rules.
9. Models and generated artifacts: consume JSON, SQLite, templates, and Live models.
10. Manifests and tabular data: produce several related artifacts.
11. Practical applications: connect the language to Nexus Build, Nexus Forge, and Setup.

For lookup, use the language reference, CLI reference, and diagnostics guide. Developers adding Nexus Script to an application can continue with Embedding Nexus Script.