Skip to main content

NexGen

View Markdown
info

For setup instructions, see the NexGen GitHub project.

NexGen generates the request and response types, runtime validators, and Nexus Service definition for a Nexus Service from one schema file. The handler and the caller each generate code from that file, in C#, Go, Java, Python, or TypeScript, so both sides use the same types even when they're written in different languages. Without a shared schema, each team hand-writes its own copy of the types, the copies drift apart, and the mismatch shows up as a failed call.

What NexGen generates​

You write the contract as a JSON or YAML definition file. Types use JSON Schema 2020-12, and a file that declares Services also lists each Operation's input and output types. Run nexgen against the file for each language you need.

For each type, NexGen generates a typed model (a record, struct, class, interface, or dataclass, depending on the language) with doc comments copied from the schema, and a runtime validator. For each Service, it generates a Service definition: the handler implements it, and the caller uses it to start Operations.

For a complete contract, see the approval contract in the Java Microservice Development Walkthrough, or the Definition files section of the nexgen README for the file format.

Data validation​

The generated code validates each value when it's deserialized from a payload and again when it's serialized into one, so invalid data is rejected before it reaches your Workflow or Activity. A failure produces one error that lists every violation, with the field and the constraint it broke.

When an Operation's input fails validation, the Worker rejects it with a non-retryable BAD_REQUEST Nexus handler error before your Operation code runs. This requires the minimum SDK versions listed in SDK requirements in the nexgen README.

Validation behaves the same in every language. To keep it that way, nexgen refuses at generation time any schema feature it can't validate the same way in all five languages. See Supported JSON Schema features for the supported subset.

Three edge cases still differ by language: negative zero, very large fractional integers, and nanosecond timestamp precision in C# and Python. See Known cross-language divergences in the nexgen README for what each language does.