Template Inputs

Oicana supports two types of inputs. A JSON input takes structured data while binary data can be passed into templates through a blob input.

Inputs are defined in the template manifest. Integrations can list all inputs of a template to, for example, validate input values or offer an editor.

JSON inputs

The type property of the input definition must be json. The only other required property is key.

Part of typst.toml

[[tool.oicana.inputs]]
type = "json"
key = "data"

Blob inputs

Blob inputs can be used for binary data like images. Additional metadata can be used to further specify the type of binary data in the input.

Part of typst.toml

[[tool.oicana.inputs]]
type = "blob"
key = "logo"

As a common use case for blob inputs, images have special support in the oicana Typst package.

Default and Development values

Inputs can define two different fallback values, default and development.

When compiling a template in development mode, input values have the priority

1. Explicit input value
2. development value
3. default value

If you compile in production mode, the development value is ignored:

1. Explicit input value
2. default value

While developing an Oicana template in a Typst editor, it will be compiled in development mode. It makes sense to define development values for all required inputs of your template to have a functioning preview.

Considering a template with the files development-data.json, default-data.json, development-logo.png, and default-logo.png. It could define the following inputs:

Part of typst.toml

[[tool.oicana.inputs]]
type = "json"
key = "data"
development = "development-data.json"
default = "default-data.json"

[[tool.oicana.inputs]]
type = "blob"
key = "logo"
development = { file = "development-logo.png", meta = { image_format = "png", foo = 5, bar = ["development", "two"] } }
default = { file = "default-logo.png", meta = { image_format = "png", foo = 5, bar = ["default", "two"] } }

The default.meta objects for blob fallback values are optional.

In the preview of an editor, the content of development-data.json and development-logo.png would be used. If compiled in production mode through an Oicana integration, the default fallbacks would be used if the input values are not set programmatically.

Required inputs

By default, all inputs are required. If a required input has no value after resolving fallbacks (considering the compilation mode), Oicana will produce a compile error.

You can mark an input as optional by setting required = false:

Part of typst.toml

[[tool.oicana.inputs]]
type = "json"
key = "extra-data"
required = false

Optional inputs without a value are not included in the input dictionary returned by the Typst package’s setup function. You can check for their presence with input.keys().contains("extra-data").

This is useful for inputs that templates can handle gracefully when absent, while still getting a clear error for inputs that must always be provided.

Validation configuration

By default, all JSON inputs with a schema are validated before compilation. You can control this on two levels.

Per-template default

The validate_json_inputs_by_default property in [tool.oicana] controls whether validation for JSON inputs with schemas is enabled. It defaults to true. Setting it to false means the template starts with validation disabled, though integrations can still toggle it at runtime per template instance.

Part of typst.toml

[tool.oicana]
manifest_version = 1
validate_json_inputs_by_default = false

Per-input

Each JSON input has an optional validate property that defaults to true. Setting it to false prevents Oicana from compiling a schema validator for that input, even if a schema is defined. This is useful when a schema is only needed for test fuzzing and not for runtime validation.

Part of typst.toml

[[tool.oicana.inputs]]
type = "json"
key = "data"
schema = "data.schema.json"
validate = false

Note that validate = false on an input is different from validate_json_inputs_by_default = false on the template. The per-input flag prevents validation entirely, while the template-level flag still allows integrations to change the validation behavior at runtime.

Using inputs in Typst

To access input values in your template, use the setup function from the oicana Typst package:

#import "@preview/oicana:0.1.1": setup

#let read-project-file(path) = return read(path, encoding: none);
#let (input, oicana-image, oicana-config) = setup(read-project-file);

• input is a dictionary of resolved input values, keyed by the input’s key
• oicana-image is a helper function that takes a blob input key and returns a Typst image element
• oicana-config contains compilation metadata like production: true/false

For blob inputs that are images, you can use the oicana-image helper instead of accessing the raw bytes:

#oicana-image("logo", alt: "Company logo")

For JSON inputs, access the parsed data directly:

#let name = input.invoice.buyer.name