[needs]

Needs configuration settings

Guide: Needs.

needs.build_json
Type:
boolean
Default:
false

Also write needs.json next to the pages during ubc build html.

The file goes to the output root, shaped by the other json_* keys below — the same shaping ubc build needs applies, though that command additionally writes source maps by default. Unset is the same as false.

In an output directory ubCode owns (one it created, or an empty one), needs.json at the root is a builder-managed name: turning this key back off removes the copy an earlier build wrote, and a file you place there yourself under that name is removed too. In a directory ubCode does not own, nothing is ever deleted.

needs.card_layouts
Type:
table of tables
Default:
{}

Defines a card layout (design) for needs.

Each entry: Definition of a card layout (design) for needs — the regions a need card has and what each one holds.

Every key is optional. Without extends, an omitted key takes the built-in clean design’s value; with extends, it takes the base design’s.

needs.card_layouts.<name>.collapse
Type:
string

What the meta section does with a need’s :collapse:: honour (the need decides), open (always expanded) or closed (always collapsed). Unset keeps the base design’s value.

Values:

  • "honour": The need’s :collapse: decides: expanded unless it says otherwise.

  • "open": Always expanded, whatever the need’s :collapse: says.

  • "closed": Always collapsed, whatever the need’s :collapse: says.

needs.card_layouts.<name>.content
Type:
boolean

Whether the card shows the need’s content. Unset keeps the base design’s value; false is not supported.

needs.card_layouts.<name>.extends
Type:
string

The design this one starts from: a built-in name (clean, complete, focus, debug) or another design defined here.

Keys this design does not state are taken from the base. Unset (or an empty string) starts from clean.

needs.card_layouts.<name>.footer
Type:
array of (string or table)

The elements of the card’s footer, in order. Each entry is a string — id, title, type, layout_echo, style_echo, field:<name> or image:<field> — or the equivalent object form ({ type = "field", field = "<name>" }), which is also where an element’s options go.

An element with nothing to show is omitted, and a footer whose elements all have nothing to show renders no footer at all. Unset keeps the base design’s value; an empty list removes the base’s footer.

Each entry: One element of a card’s footer or side column: a string shorthand, or its object form.

The two spellings are equivalent: "image:diagram" is exactly { type = "image", field = "diagram" }. The object form is also where an element’s options go (label on a field element, height and width on an image element).

Forms:

  • a string: The string shorthand: id, title, type, layout_echo, style_echo, field:<name> or image:<field>.

  • a table: The object form: a type plus the keys that type takes.

needs.card_layouts.<name>.footer[].field
Type:
string

The need field the element draws — required for field and image elements, not valid on any other kind. Always a field name, never a literal path or URL.

needs.card_layouts.<name>.footer[].height
Type:
string

image elements only: the drawn image’s height — a number with an optional px, em, rem, % or pt unit (a bare number means px), at most 16 characters.

needs.card_layouts.<name>.footer[].label
Type:
string

field elements only: replaces the field name in the rendered <name>: <value> pair. 1-64 characters from A-Za-z0-9, space and _().,/-, starting and ending alphanumeric; _ only between alphanumerics (a word-trailing _ is reference syntax in a Sphinx-Needs build).

needs.card_layouts.<name>.footer[].type
Type:
string

The element’s kind: one of id, title, type, layout_echo, style_echo, field or image. Required.

needs.card_layouts.<name>.footer[].width
Type:
string

image elements only: the drawn image’s width — same grammar as height.

needs.card_layouts.<name>.header
Type:
boolean

Whether the card shows its header line (type, title, id). Unset keeps the base design’s value.

A need hidden with :hide: always shows one regardless: it is the summary of the disclosure the whole card sits in.

needs.card_layouts.<name>.meta
Type:
boolean or table

The card’s meta section: a table of settings, or false for a design with no meta section at all. Unset keeps the base design’s value.

Forms:

  • a boolean: meta = false — the design has no meta section.

  • a table: The meta section’s settings.

needs.card_layouts.<name>.meta.empties
Type:
boolean

Whether fields with an empty value are shown. Unset keeps the base design’s value.

needs.card_layouts.<name>.meta.exclude
Type:
array of strings

Fields never to show, even when include lists them. Unset keeps the base design’s value.

needs.card_layouts.<name>.meta.fields
Type:
string

Which fields the section draws from: stored (the values needs actually carry), effective (those plus configured defaults) or all (effective, plus the internal fields cards normally withhold). Unset keeps the base design’s value.

Values:

  • "stored": Only the values a need actually carries — what was written on it, or set on it by a needextend. Internal fields are not shown.

  • "effective": The stored values plus any a field’s configured default supplies. Internal fields are not shown.

  • "all": Every field the need has a value for, internal fields included.

needs.card_layouts.<name>.meta.include
Type:
array of strings

When given, the section shows exactly these fields, in this order. A listed field is shown even when it is one the card normally withholds, but empties still decides whether one with no value shows a row. Unset keeps the base design’s value; an empty list shows all the fields the tier yields, in alphabetical order.

Type:
boolean

Whether the need’s outgoing links are shown. Unset keeps the base design’s value.

Type:
boolean

Whether the needs linking TO this one are shown. Unset keeps the base design’s value.

needs.card_layouts.<name>.side
Type:
boolean or table

The card’s side column: a table of settings, or false for a design with no side column at all. Unset keeps the base design’s value.

Forms:

  • a boolean: side = false — the design has no side column, even when the design it extends has one.

  • a table: The side column’s settings.

needs.card_layouts.<name>.side.elements
Type:
array of (string or table)

The elements the column holds, in order — the same set (and the same two spellings, string or object) the footer accepts. A column whose elements all have nothing to show renders no column at all. Unset keeps the base design’s value.

Each entry: One element of a card’s footer or side column: a string shorthand, or its object form.

The two spellings are equivalent: "image:diagram" is exactly { type = "image", field = "diagram" }. The object form is also where an element’s options go (label on a field element, height and width on an image element).

Each entry takes the same keys as each entry of needs.card_layouts.<name>.footer.

needs.card_layouts.<name>.side.position
Type:
string

Which side of the card the column sits on: left or right. Unset keeps the base design’s value.

Values:

  • "left": The column sits to the left of the card’s body.

  • "right": The column sits to the right of the card’s body.

needs.card_layouts.<name>.side.span
Type:
string

How far down the card the column runs: full (the whole card) or partial (beside the header and meta section only). Unset keeps the base design’s value.

Values:

  • "full": The column runs beside the whole card.

  • "partial": The column runs beside the header and meta section only; the content and footer take the card’s full width below it.

needs.completion_option
Type:
string
Default:
"completion"

The need field needgantt reads each task’s PROGRESS from, as a percentage.

The field must be declared under [needs.fields] with an integer or number type; a needgantt naming an undeclared or non-numeric field warns and draws no progress. A directive’s own :completion_option: overrides this. Unset is the same as completion.

Unlike Sphinx-Needs, ubCode does not add the field to every need type on your behalf — point this at a field you declared.

needs.default_layout
Type:
string
Default:
""

The card design every need with no :layout: of its own is drawn with.

Any name a :layout: accepts: a built-in design, one of the two sphinx-needs compatibility names, or one of your own under card_layouts. A need’s own :layout: always wins, and so does a value a [needs.fields.layout] default or predicates row puts on the need — this key only catches needs that end up with no value at all. Unset — or set to "" — is the same as clean, the design that draws today’s card. A name no design answers to is reported and treated as unset.

needs.diagram_template
Type:
string

The Jinja template each flow() node in a needuml is drawn from, and each node of a needflow drawn by a PlantUML executable.

It is rendered against the need’s own fields, plus render_context, and must produce the node’s label text. Unset draws Sphinx-Needs’ own default node: the type title, the wrapped title in bold, and the id.

The Mermaid flowchart ubCode draws for a needflow without a PlantUML executable does not read this key: it draws those same three parts in Mermaid’s own label syntax.

needs.duration_option
Type:
string
Default:
"duration"

The need field needgantt reads each task’s LENGTH from.

The field must be declared under [needs.fields] with an integer or number type; a needgantt naming an undeclared or non-numeric field warns and draws every task one day long. A directive’s own :duration_option: overrides this. Unset is the same as duration.

Unlike Sphinx-Needs, ubCode does not add the field to every need type on your behalf — point this at a field you declared.

needs.external_needs
Type:
array of tables
Default:
[]

External sources to load needs from.

Each entry: External source to load needs from.

Forms:

  • a table with json_path: JSON source from a local file path

  • a table with json_url: JSON source from a remote URL

needs.external_needs[].base_url
Type:
string

The base URL for references to the external source

needs.external_needs[].css_class
Type:
string

Add a CSS class to URL references

needs.external_needs[].id_prefix
Type:
string

Prefix all IDs from the external source with this string, added as written

needs.external_needs[].skip_in_ubcode
Type:
boolean
Default:
false

Skip this source when loading needs in ubcode

needs.external_needs[].target_url
Type:
string

A Jinja template for the URL of references to the external source, relative to base_url; the need is available as need, as in {{ need.id }}

needs.external_needs[].version
Type:
string

Override current_version from loaded JSON

needs.external_needs[].json_path
Type:
string

Local path to a JSON file.

needs.external_needs[].json_url
Type:
string

Remote URL to a JSON file.

Type:
array of tables
Default:
[]

Links between needs.

Each entry: Defines a link between needs.

Type:
boolean
Default:
false

Do not warn if a link connects to an unknown need ID.

Type:
string
Default:
"#000000"

The default color to use in diagrams.

Type:
boolean
Default:
false

Copy to common links field.

Type:
value

The target needs a need holds when it leaves this link type unset and no predicates entry matches: a list of need IDs, or a dynamic function such as "[[copy('links')]]". When set, a default for this link type under [needs.global_options] is ignored and reported. A link type with derive takes no default.

Type:
table

Computes this link type’s target needs instead of letting authors write them: a table naming a kind (links, content_links or union) and that kind’s roles. A link type with derive cannot be set on a directive or by needextend. A rule that cannot be read is reported, and the link type stays empty. For some need types only, write derive in the need type’s own entry instead ([needs.types.<type>.links.<name>]).

Forms:

  • kind = "links": Link every need passing the where filter, or matching this need by join (both given: the matches passing the filter).

  • kind = "content_links": Link the needs the need’s content references with :need:.

  • kind = "union": Hold the links of the need’s own link types fields names, in that order, each link once (by its target, part and condition). A dead link or a link condition is reported at the link type it comes from (on a need from a needs.json, at the union).

Type:
boolean

Make need parts candidates too, linked as <need>.<part>. Default false; not with join, whose candidates are needs only.

Type:
boolean

Let the need (and its own parts) be linked to itself when it passes the filter (or matches the join). Default false.

Type:
table

Match needs by value: field names the field read on every need, equals the field read on this need, both text fields (a string is split on commas, an array read by item, each value stripped). A need matches when the two share a value; each match counts once, in need-id order, and this need only with include_self.

Type:
string

The field read on this need: a string or an array of strings.

Type:
string

The field read on every need: a string or an array of strings.

Type:
string

Values:

  • "links"

  • "content_links"

  • "union"

Type:
string

  • With kind = "links": A filter over every need; the needs that pass it are linked (with join, the matches that pass it). It must not be empty.

  • With kind = "content_links": Keep only the referenced needs that pass this filter.

Type:
string

The id of the need whose content is read. Unset reads this need’s own content.

Type:
array of strings

The need’s own link types whose links the union holds, in this order, each named once: link types (links and derived ones among them), not parent_needs or <link>_back.

Type:
table of tables

Rules keyed by need type (the directive name, as type holds it), each value a rule as derive takes: for a type with no entry of its own (a [test_reports] type), and for a rule the types inheriting from a type must not take. Otherwise write derive in the need type’s own entry ([needs.types.<type>.links.<name>]). A type’s rule overrides derive; a need of a type with neither holds the link type’s default, else no links. The link type cannot be set on a directive or by needextend, on any need type.

Each entry: The rule of the need type the key names: a kind and that kind’s roles.

Each entry takes the same keys as needs.extra_links[].derive.

Type:
string

The incoming link title.

Type:
string

The name of the link type.

Type:
string

The outgoing link title.

Type:
boolean

Whether condition bracket syntax is parsed in this link’s values. When false, brackets are treated as literal ID text. Defaults to true when not set.

Type:
boolean

Whether dynamic functions are parsed in this link. Falls back to global parse_dynamic_functions when not set.

Type:
boolean

Whether variants are parsed in this link.

Type:
array of arrays

List of (need filter, target needs) pairs: a need that leaves this link type unset takes the target needs of the first filter it matches. When set, predicates for this link type under [needs.global_options] are ignored and reported. A link type with derive takes no predicates.

Type:
table

Schema constraints for validating the link array.

Type:
table

Schema constraints that at least one item must match.

Type:
integer

Maximum string length of each link ID.

Type:
integer

Minimum string length of each link ID.

Type:
string

A regex pattern to validate each link ID against.

Type:
string
Default:
"string"

Type for link items. Injected automatically if not provided.

Values:

  • "string"

Type:
table
Default:
{ type = "string" }

Schema constraints that apply to all items in the link ID array. Defaults to {"type": "string"} to ensure schema completeness.

Type:
integer

Maximum string length of each link ID.

Type:
integer

Minimum string length of each link ID.

Type:
string

A regex pattern to validate each link ID against.

Type:
string
Default:
"string"

Type for link items. Injected automatically if not provided.

Values:

  • "string"

Type:
integer

Maximum number of items that must match the ‘contains’ schema.

Type:
integer

Maximum number of outgoing links allowed.

Type:
integer

Minimum number of items that must match the ‘contains’ schema.

Type:
integer

Minimum number of outgoing links required.

Type:
string
Default:
"array"

Type for extra links, must be “array”. Injected automatically if not provided.

Values:

  • "array"

Type:
string
Default:
""

The line style of this link type’s edges in needflow diagrams: comma-separated PlantUML line tokens and/or a colour (dashed, dotted, bold, #ffcc00). Empty draws the diagram engine’s default line.

Type:
string
Default:
"->"

Raw PlantUML arrow syntax that Sphinx-Needs’ PlantUML engine writes after the line style (->, after style_start = "-", draws -->). Ignored by ubCode’s own diagrams.

Type:
string
Default:
"dotted"

The line style of an edge that starts or ends at a need part, in the same form as style. Leave it set: Sphinx-Needs’ PlantUML engine writes […] for every part edge, so an empty value draws -[]->, which PlantUML rejects.

Type:
string
Default:
"-"

Raw PlantUML arrow syntax that Sphinx-Needs’ PlantUML engine writes before the line style (-, with style_end = "->", draws -->). Ignored by ubCode’s own diagrams.

Type:
array of strings

The need types the links may point to, by directive name; a type inheriting from a listed type is accepted. A link to a need of another type is reported. Unset: any type. A link type with derive or derive_by_type takes none.

needs.extra_options
Type:
array of (table or string)
Default:
[]

Extra options for needs.

Each entry: Definition for extra options, either as a map or string reference

Forms:

  • a table with name: Extra option for needs

needs.extra_options[].derive
Type:
table

Computes this field’s value instead of letting authors write it: a table naming a kind and that kind’s roles, as on a [needs.fields.<name>] entry. A field with derive cannot be set on a directive or by needextend. A rule that cannot be read is reported, and the field keeps its empty value. For some need types only, write derive in the need type’s own entry instead ([needs.types.<type>.fields.<name>]).

Forms:

  • kind = "copy": Copy one field: of this need, of the need from names, of the target needs of over, or of the needs matching this one by join.

  • kind = "sum": The sum of field over the candidates.

  • kind = "count": The number of candidates.

  • kind = "min": The least value of field over the candidates (an ordered enum or a number).

  • kind = "max": The greatest value of field over the candidates (an ordered enum or a number).

  • kind = "any": Whether some candidate holds: a boolean field or a test. False with no candidates.

  • kind = "all": Whether every candidate holds: a boolean field or a test. True with no candidates.

  • kind = "collect": The distinct values of field over the candidates, as a list.

  • kind = "hash": A SHA-256 of the need’s own fields, computed after every other derived field.

  • kind = "fingerprint": A SHA-256 of the whole need: id, type, title, status, tags, content, every field the project declares and every link type (links among them), none of them derived, each where it differs from its default; never parent_needs or a field ubCode adds. Computed after every other derived field.

needs.extra_options[].derive.after
Type:
string

"derived" runs the rule after every other derived field of the need.

Values:

  • "derived"

needs.extra_options[].derive.field
Type:
string

  • With kind = "copy": The field copied: a field, a link type, or <link>_back. Read on this need unless from, over or join says otherwise.

  • With kind = "sum", kind = "min", kind = "max", kind = "collect": The field read on each candidate.

  • With kind = "count": Count only the candidates that set this field.

  • With kind = "any", kind = "all": A boolean field read on each candidate.

needs.extra_options[].derive.from
Type:
string

The id of the need the field is read from.

needs.extra_options[].derive.include_self
Type:
boolean

  • With kind = "copy": With join: let this need be one of the matches. Default false.

  • With kind = "min", kind = "max": Count this need’s own value too. Needs transitive = true.

needs.extra_options[].derive.join
Type:
table

Match needs by value: field names the field read on every need, equals the field read on this need, both text fields (a string is split on commas, an array read by item, each value stripped). A need matches when the two share a value; each match counts once, in need-id order, and this need only with include_self.

Takes the same keys as needs.extra_links[].derive.join.

needs.extra_options[].derive.kind
Type:
string

Values:

  • "copy"

  • "sum"

  • "count"

  • "min"

  • "max"

  • "any"

  • "all"

  • "collect"

  • "hash"

  • "fingerprint"

needs.extra_options[].derive.over
Type:
string

A link type: its target needs are the candidates, in the order written. <link>_back reads the needs that link to this one instead.

needs.extra_options[].derive.select
Type:
string

Which value a lookup over several target needs takes: first (the lowest need id, the default), unique (the same, reported when several target needs set the field) or list (every value, into an array field).

Values:

  • "first"

  • "unique"

  • "list"

needs.extra_options[].derive.where
Type:
string

A filter narrowing the candidates, evaluated on each candidate.

needs.extra_options[].derive.transitive
Type:
boolean

Close over the link type: every need reachable through it, not only its direct target needs. Needs an ordered enum or a number field.

needs.extra_options[].derive.test
Type:
string

A filter asserted of each candidate, instead of a boolean field.

needs.extra_options[].derive.fields
Type:
array of strings

The need’s own fields hashed, in this order: fields and link types, not <link>_back.

needs.extra_options[].derive.exclude
Type:
array of strings

Names to leave out of the fingerprint, each one it would include, listed once. An empty list leaves nothing out.

needs.extra_options[].derive_by_type
Type:
table of tables

Rules keyed by need type (the directive name, as type holds it), each value a rule as derive takes: for a type with no entry of its own (a [test_reports] type), and for a rule the types inheriting from a type must not take. Otherwise write derive in the need type’s own entry ([needs.types.<type>.fields.<name>]). A type’s rule overrides derive; a need of a type with neither holds null when the field is nullable, else its empty value. The field cannot be set on a directive or by needextend, on any need type.

Each entry: The rule of the need type the key names: a kind and that kind’s roles.

Each entry takes the same keys as needs.extra_options[].derive.

needs.extra_options[].description
Type:
string
Default:
""

The description of the option.

needs.extra_options[].name
Type:
string

The name of the option.

needs.extra_options[].schema
Type:
table

Schema for the option value.

Forms:

  • a table with items: Array type schema with array-specific validation rules

  • a table: Single value type schema (string, boolean, integer, or number)

needs.extra_options[].schema.contains
Type:
table

Schema that at least one item in the array must match

Forms:

  • type = "string": String type schema with string-specific validation rules

  • type = "boolean": Boolean type schema with boolean-specific validation rules

  • type = "integer": Integer type schema with integer-specific validation rules

  • type = "number": Number type schema with number-specific validation rules

needs.extra_options[].schema.contains.const
Type:
string or boolean or integer or float

  • With type = "string": A constant value that the string must equal

  • With type = "boolean": A constant value that the boolean must equal

  • With type = "integer": A constant value that the integer must equal

  • With type = "number": A constant value that the number must equal

needs.extra_options[].schema.contains.enum
Type:
array of strings or array of booleans or array of integers or array of floats

  • With type = "string": An array of valid string values

  • With type = "boolean": An array of valid boolean values

  • With type = "integer": An array of valid integer values

  • With type = "number": An array of valid number values

needs.extra_options[].schema.contains.format
Type:
string

The format that the string must conform to

Values:

  • "date-time": RFC 3339 date-time format (e.g., 2023-10-22T14:30:00Z)

  • "date": RFC 3339 full-date format (e.g., 2023-10-22)

  • "time": RFC 3339 full-time format (e.g., 14:30:00Z)

  • "duration": RFC 3339 duration format (e.g., P1DT12H)

  • "email": RFC 5322 email address format (e.g., user@example.com)

  • "idn-email": Internationalized email address format (RFC 6531)

  • "hostname": RFC 1123 hostname format (e.g., example.com)

  • "idn-hostname": Internationalized hostname format (RFC 5890)

  • "ipv4": IPv4 address format (e.g., 192.168.1.1)

  • "ipv6": IPv6 address format (e.g., 2001:db8::1

  • "uri": RFC 3986 URI format (e.g., https://example.com/path)

  • "uri-reference": RFC 3986 URI reference format (URI or relative reference)

  • "iri": RFC 3987 IRI format (internationalized URI)

  • "iri-reference": RFC 3987 IRI reference format (IRI or relative reference)

  • "uuid": RFC 4122 UUID format (e.g., 550e8400-e29b-41d4-a716-446655440000)

  • "uri-template": RFC 6570 URI template format (e.g., /users/{id})

  • "json-pointer": RFC 6901 JSON pointer format (e.g., /path/to/field)

  • "relative-json-pointer": RFC 6901 relative JSON pointer format (e.g., 1/name)

  • "regex": ECMAScript regular expression format

needs.extra_options[].schema.contains.maxLength
Type:
integer

The maximum length (inclusive) of the string

needs.extra_options[].schema.contains.minLength
Type:
integer

The minimum length (inclusive) of the string

needs.extra_options[].schema.contains.pattern
Type:
string

A regular expression pattern that the string must match

needs.extra_options[].schema.contains.type
Type:
string

  • With type = "string": The type identifier for string values

  • With type = "boolean": The type identifier for boolean values

  • With type = "integer": The type identifier for integer values

  • With type = "number": The type identifier for number values

Values:

  • "string": The “string” type tag value

  • "boolean": The “boolean” type tag value

  • "integer": The “integer” type tag value

  • "number": The “number” type tag value

needs.extra_options[].schema.contains.exclusiveMaximum
Type:
integer or float

  • With type = "integer": The maximum value (exclusive) that the integer can have

  • With type = "number": The maximum value (exclusive) that the number can have

needs.extra_options[].schema.contains.exclusiveMinimum
Type:
integer or float

  • With type = "integer": The minimum value (exclusive) that the integer can have

  • With type = "number": The minimum value (exclusive) that the number can have

needs.extra_options[].schema.contains.maximum
Type:
integer or float

  • With type = "integer": The maximum value (inclusive) that the integer can have

  • With type = "number": The maximum value (inclusive) that the number can have

needs.extra_options[].schema.contains.minimum
Type:
integer or float

  • With type = "integer": The minimum value (inclusive) that the integer can have

  • With type = "number": The minimum value (inclusive) that the number can have

needs.extra_options[].schema.contains.multipleOf
Type:
integer or float

  • With type = "integer": The integer must be a multiple of this value

  • With type = "number": The number must be a multiple of this value

needs.extra_options[].schema.items
Type:
table

If the type is “array”, the type of the items in the array

Forms:

  • type = "string": String type schema with string-specific validation rules

  • type = "boolean": Boolean type schema with boolean-specific validation rules

  • type = "integer": Integer type schema with integer-specific validation rules

  • type = "number": Number type schema with number-specific validation rules

Takes the same keys as needs.extra_options[].schema.contains.

needs.extra_options[].schema.maxContains
Type:
integer

Maximum number of items that can match the ‘contains’ schema

needs.extra_options[].schema.maxItems
Type:
integer

The maximum number of items (inclusive) that the array can contain

needs.extra_options[].schema.minContains
Type:
integer

Minimum number of items that must match the ‘contains’ schema

needs.extra_options[].schema.minItems
Type:
integer

The minimum number of items (inclusive) that the array can contain

needs.extra_options[].schema.type
Type:
string

The type identifier for array values

Values:

  • "array": The “array” type tag value

needs.extra_options[].schema.uniqueItems
Type:
boolean

Whether all items in the array must be unique

needs.fields
Type:
table of tables
Default:
{}

Defines a field for needs.

Each entry: Definition of a field for needs.

needs.fields.<name>.default
Type:
value

Default value for the field. When set, a default for this field under [needs.global_options] is ignored and reported.

needs.fields.<name>.derive
Type:
table

Computes the field instead of letting authors set it: a table naming a kind (copy, sum, count, min, max, any, all, collect, hash or fingerprint) and that kind’s roles. A field with derive cannot be set on a directive or by needextend, and takes no default or predicates. A rule that cannot be read is reported, and the field keeps its empty value. For some need types only, write derive in the need type’s own entry instead ([needs.types.<type>.fields.<name>]).

Forms:

  • kind = "copy": Copy one field: of this need, of the need from names, of the target needs of over, or of the needs matching this one by join.

  • kind = "sum": The sum of field over the candidates.

  • kind = "count": The number of candidates.

  • kind = "min": The least value of field over the candidates (an ordered enum or a number).

  • kind = "max": The greatest value of field over the candidates (an ordered enum or a number).

  • kind = "any": Whether some candidate holds: a boolean field or a test. False with no candidates.

  • kind = "all": Whether every candidate holds: a boolean field or a test. True with no candidates.

  • kind = "collect": The distinct values of field over the candidates, as a list.

  • kind = "hash": A SHA-256 of the need’s own fields, computed after every other derived field.

  • kind = "fingerprint": A SHA-256 of the whole need: id, type, title, status, tags, content, every field the project declares and every link type (links among them), none of them derived, each where it differs from its default; never parent_needs or a field ubCode adds. Computed after every other derived field.

Takes the same keys as needs.extra_options[].derive.

needs.fields.<name>.derive_by_type
Type:
table of tables

Rules keyed by need type (the directive name, as type holds it), each value a rule as derive takes: for a type with no entry of its own (a [test_reports] type), and for a rule the types inheriting from a type must not take. Otherwise write derive in the need type’s own entry ([needs.types.<type>.fields.<name>]). A type’s rule overrides derive; a need of a type with neither holds the field’s default, else null when nullable, else its empty value. The field cannot be set on a directive or by needextend, on any need type.

Each entry: The rule of the need type the key names: a kind and that kind’s roles.

Each entry takes the same keys as needs.extra_options[].derive.

needs.fields.<name>.description
Type:
string

A description of the field.

needs.fields.<name>.nullable
Type:
boolean

Whether the field allows unset values.

needs.fields.<name>.parse_dynamic_functions
Type:
boolean

Whether dynamic functions are parsed in this field. Falls back to global parse_dynamic_functions when not set.

needs.fields.<name>.parse_variants
Type:
boolean

Whether variants are parsed in this field

needs.fields.<name>.predicates
Type:
array of arrays
Default:
[]

List of (need filter, value) pairs for predicate default values. When set, predicates for this field under [needs.global_options] are ignored and reported.

needs.fields.<name>.schema
Type:
table

A JSON schema definition for the field.

Forms:

  • a table with items: Array type schema with array-specific validation rules

  • a table: Single value type schema (string, boolean, integer, or number)

Takes the same keys as needs.extra_options[].schema.

needs.filter_data
Type:
table of strings
Default:
{}

Additional context for filter expressions

needs.flow_configs
Type:
table of strings
Default:
{}

Named blocks of PlantUML configuration lines a needuml, needarch or needflow can pull in with its :config: option.

Each entry’s value is inserted verbatim at the top of the generated diagram, so it is the place for skinparams and other project-wide diagram styling. A :config: naming an entry that does not exist is reported and ignored. Unset is the same as no entries.

A needflow only inserts these lines when it is drawn by a PlantUML executable ([build.plantuml] needflow); the Mermaid flowchart ubCode draws otherwise reads only the two direction entry NAMES (toptobottom / lefttoright). A needsequence never inserts them: it reports its :config: as unsupported on both arms.

needs.flow_direction
Type:
string
Default:
"down"

The default layout direction for needflow diagrams.

One of down, up, right or left — where the graph grows — or the equivalent engine tokens TB/TD, BT, LR and RL. A needflow that sets its own :direction: uses that instead. Unset (or an empty string) is the same as down.

needs.flow_engine
Type:
string
Default:
""

Which engine draws the project’s needflow diagrams.

Sphinx-Needs’ own needs_flow_engine, read here so that one ubproject.toml shared by both tools need not say the same thing twice. plantuml asks for the diagrams to be drawn by the PlantUML executable [build.plantuml] names, and graphviz asks for them not to be (ubCode has no Graphviz pathway, so it draws them the way it draws them without one). Any other value is reported and ignored.

This is only the DEFAULT: [build.plantuml] needflow (or a builder’s own [build.html.plantuml] / [build.pdf.plantuml]) wins over it, and a diagram’s own :engine: wins over both. Drawing with PlantUML also needs [build.plantuml] enabled, since that is what names the executable. Unset (or an empty string) leaves the choice to [build.plantuml] needflow, which is off by default.

needs.flow_legends
Type:
table of tables
Default:
{}

The project’s named legend configurations ([needs.flow_legends.<name>]), selected by a needflow’s :show_legend: or by flow_show_legend.

Each entry: One named legend configuration ([needs.flow_legends.<name>]).

A needflow selects one by name with :show_legend: <name>; a project selects the one unnamed requests get with needs.flow_show_legend.

needs.flow_legends.<name>.parts
Type:
array of strings

The sections the legend lists, in the order they are drawn: types (each drawn need type with its colour) and links (each drawn link type with its display name).

Order is significant — ["links", "types"] draws the link table first. Unset is the same as ["types"].

Values:

  • "types"

  • "links"

needs.flow_legends.<name>.placement
Type:
string

Where the legend is drawn: internal (inside the diagram) or external (a table beside it). Unset takes the diagram engine’s default placement, which for the Mermaid flowcharts ubCode draws is external.

internal is a preference, not a guarantee: an engine that cannot draw a legend inside the diagram draws the external one instead, with the same rows. Mermaid is such an engine — its flowchart syntax has no legend construct — so ubCode always draws the external table.

needs.flow_show_legend
Type:
string
Default:
""

Which named legend a needflow uses when its :show_legend: names none.

The value is a key of flow_legends. This selects WHICH legend a diagram gets, never WHETHER it gets one: only a :show_legend: on the directive itself draws a legend. Unset (or an empty string) leaves the choice to the diagram engine, which for Mermaid is a table beside the diagram listing the drawn need types.

Type:
boolean or string
Default:
"none"

The default edge labelling for needflow diagrams.

outgoing and incoming label each edge with the link type’s corresponding display name, type labels it with the link type’s own name, and none leaves edges unlabelled. true means outgoing and false means none. A needflow that sets its own :show_link_names: uses that instead. Unset (or an empty string) is the same as none.

Forms:

  • a boolean: true labels edges with the outgoing name; false leaves them unlabelled.

  • a string: One of none, outgoing, incoming or type.

needs.global_options
Type:
table of tables
Default:
{}

Default values given to specified fields of needs

needs.global_options.<name>.default
Type:
value

This value is used, if the field has not been specifically set, and no predicate matches. Ignored, and reported, when the field’s or link type’s own declaration sets a default too.

needs.global_options.<name>.predicates
Type:
array of arrays

A list of (filter predicate, value) to match against the need. If the field has not been specifically set, the value of the first predicate that matches is used. Ignored, and reported, when the field’s or link type’s own declaration sets predicates too.

needs.id_from_title
Type:
boolean
Default:
false

Base auto-generated IDs on the title.

needs.id_length
Type:
integer
Default:
5

The length of the auto-generated ID.

needs.id_regex
Type:
string
Default:
"^[A-Z0-9_]{5,}"

Validate IDs with a regex.

needs.id_required
Type:
boolean
Default:
false

If True, an ID is required.

needs.import_allow_assets
Type:
boolean
Default:
false

Whether imported need content may reference images, figures and diagram files by default.

Imported content comes from outside the project, so asset references in it are refused unless the project opts in: a refused image / figure or file-form diagram renders a placeholder and reports why. Unset is the same as false. Override per source under needs.import_sources.

Allowing this grants an import source the same authority over your source tree that an image you wrote yourself has: a relative reference resolves against the directory holding the source’s own JSON, and an absolute /x resolves against [project] srcdir, so the source can reference any file published under it. Set assets_root on the source to narrow that to one subtree — recommended for any third-party source. A reference that resolves outside whichever base applies is refused.

needs.import_keys
Type:
table of strings
Default:
{}

Mapping of keys that can be used as needimport arguments and replaced by the values.

needs.import_preview_max
Type:
integer
Default:
50

How many needs each needimport or src-trace directive shows in the editor’s rendered preview.

The preview shows at most this many needs per site, so a page bringing in thousands stays responsive while typing; a truncated site shows a notice saying how many of how many are displayed. ubc build html is unaffected and always renders every need. Unset is the same as 50; 0 shows none.

needs.import_sources
Type:
array of tables
Default:
[]

Per-source asset policy for needimport sources.

The policy belongs to the source rather than to the directive, so two needimport directives on different pages that read the same JSON resolve its assets identically. An entry matches by the same json_path / json_url spelling needs.external_needs uses; a source with no entry takes needs.import_allow_assets.

Each entry: Asset policy for one needimport source.

Forms:

  • a table with json_path: JSON source from a local file path

  • a table with json_url: JSON source from a remote URL

needs.import_sources[].allow_assets
Type:
boolean

Whether this source’s imported content may reference images, figures and diagram files.

Overrides needs.import_allow_assets for this source. Unset takes that project default.

needs.import_sources[].assets_root
Type:
string

Where this source’s assets live, as a path relative to project.srcdir.

A reference in the imported content resolves against this directory: an absolute /x becomes <srcdir>/<assets_root>/x, and a relative x the same. Setting it NARROWS what the source can reach to this one subtree. When unset, a relative reference resolves against the directory holding the source’s own JSON file (which must be inside srcdir) and an absolute /x against srcdir itself — i.e. the source can then reference any file published under srcdir, exactly as an image you wrote yourself can. Must not lead outside srcdir.

Recommended for any third-party source, and required for a source read over the network — a remote source has no local directory to resolve against, so without this its content cannot reference assets at all. The same applies to a local source whose JSON file sits outside srcdir.

needs.import_sources[].json_path
Type:
string

Local path to a JSON file.

needs.import_sources[].json_url
Type:
string

Remote URL to a JSON file.

needs.json_exclude_fields
Type:
array of strings

Need fields to leave out of needs.json.

A listed name is dropped from every need object and from the file’s needs_schema. Names no need or schema uses are ignored, so listing a field the project does not define is harmless. Set an empty list to write every field. Unset drops the same rendering and bookkeeping core fields Sphinx-Needs drops by default.

Type:
boolean
Default:
true

Keep [condition] suffixes on outgoing link values in needs.json.

When unset or true, a conditional link is written in full (REQ_001[status == "open"]); when false, only the target is written (REQ_001). Backlink fields never carry conditions and are unaffected.

needs.json_remove_defaults
Type:
boolean
Default:
false

Leave out need fields whose value equals that field’s default.

Shrinks needs.json considerably on projects where most needs take the defaults; a reader must apply the defaults from needs_schema itself. Unset is the same as false.

Type:
table of tables
Default:
{}

Defines a link between needs.

Each entry: Defines a link between needs (dict-based, key is the link name).

Type:
boolean
Default:
false

Do not warn if a link connects to an unknown need ID.

needs.links.<name>.color
Type:
string
Default:
"#000000"

The default color to use in diagrams.

needs.links.<name>.copy
Type:
boolean
Default:
false

Copy to common links field.

needs.links.<name>.default
Type:
value

The target needs a need holds when it leaves this link type unset and no predicates entry matches: a list of need IDs, or a dynamic function such as "[[copy('links')]]". When set, a default for this link type under [needs.global_options] is ignored and reported. A link type with derive takes no default.

needs.links.<name>.derive
Type:
table

Computes this link type’s target needs instead of letting authors write them: a table naming a kind (links, content_links or union) and that kind’s roles. A link type with derive cannot be set on a directive or by needextend. A rule that cannot be read is reported, and the link type stays empty. For some need types only, write derive in the need type’s own entry instead ([needs.types.<type>.links.<name>]).

Forms:

  • kind = "links": Link every need passing the where filter, or matching this need by join (both given: the matches passing the filter).

  • kind = "content_links": Link the needs the need’s content references with :need:.

  • kind = "union": Hold the links of the need’s own link types fields names, in that order, each link once (by its target, part and condition). A dead link or a link condition is reported at the link type it comes from (on a need from a needs.json, at the union).

Takes the same keys as needs.extra_links[].derive.

needs.links.<name>.derive_by_type
Type:
table of tables

Rules keyed by need type (the directive name, as type holds it), each value a rule as derive takes: for a type with no entry of its own (a [test_reports] type), and for a rule the types inheriting from a type must not take. Otherwise write derive in the need type’s own entry ([needs.types.<type>.links.<name>]). A type’s rule overrides derive; a need of a type with neither holds the link type’s default, else no links. The link type cannot be set on a directive or by needextend, on any need type.

Takes the same keys as needs.extra_links[].derive_by_type.

needs.links.<name>.description
Type:
string

A description of the link type.

needs.links.<name>.incoming
Type:
string

The incoming link title.

needs.links.<name>.outgoing
Type:
string

The outgoing link title.

needs.links.<name>.parse_conditions
Type:
boolean

Whether condition bracket syntax is parsed in this link’s values. When false, brackets are treated as literal ID text. Defaults to true when not set.

needs.links.<name>.parse_dynamic_functions
Type:
boolean

Whether dynamic functions are parsed in this link. Falls back to global parse_dynamic_functions when not set.

needs.links.<name>.parse_variants
Type:
boolean

Whether variants are parsed in this link.

needs.links.<name>.predicates
Type:
array of arrays

List of (need filter, target needs) pairs: a need that leaves this link type unset takes the target needs of the first filter it matches. When set, predicates for this link type under [needs.global_options] are ignored and reported. A link type with derive takes no predicates.

needs.links.<name>.schema
Type:
table

Schema constraints for validating the link array.

Takes the same keys as needs.extra_links[].schema.

needs.links.<name>.style
Type:
string
Default:
""

The line style of this link type’s edges in needflow diagrams: comma-separated PlantUML line tokens and/or a colour (dashed, dotted, bold, #ffcc00). Empty draws the diagram engine’s default line.

needs.links.<name>.style_end
Type:
string
Default:
"->"

Raw PlantUML arrow syntax that Sphinx-Needs’ PlantUML engine writes after the line style (->, after style_start = "-", draws -->). Ignored by ubCode’s own diagrams.

needs.links.<name>.style_part
Type:
string
Default:
"dotted"

The line style of an edge that starts or ends at a need part, in the same form as style. Leave it set: Sphinx-Needs’ PlantUML engine writes […] for every part edge, so an empty value draws -[]->, which PlantUML rejects.

needs.links.<name>.style_start
Type:
string
Default:
"-"

Raw PlantUML arrow syntax that Sphinx-Needs’ PlantUML engine writes before the line style (-, with style_end = "->", draws -->). Ignored by ubCode’s own diagrams.

needs.links.<name>.target_types
Type:
array of strings

The need types the links may point to, by directive name; a type inheriting from a listed type is accepted. A link to a need of another type is reported. Unset: any type. A link type with derive or derive_by_type takes none.

needs.parse_dynamic_functions
Type:
boolean
Default:
true

Whether dynamic functions are parsed by default.

Applies to extra fields and links unless overridden per-field/per-link. Core fields are not affected by this global setting.

needs.part_prefix
Type:
string
Default:
"→ "

The text put in front of a need part’s id and content in a needtable that sets :show_parts:.

It marks a part’s row as belonging to the need above it. Unset is the same as "→ " — a right arrow and a non-breaking space, so the marker cannot wrap away from what it labels. Set it to "" for no prefix at all. It applies in the editor’s rendered preview and in ubc build html alike, and nothing but a :show_parts: table reads it.

needs.remote
Type:
table
Default:
{ cache_days = 1, offline = false, timeout = 10.0 }

Settings for fetching remote (http(s)://) needs sources — both external_needs entries with a json_url and needimport directives whose argument is a URL.

needs.remote.cache_days
Type:
integer
Default:
1

How long, in days, a remote source’s already-loaded needs are reused before ubcode re-checks the source:

  • > 0 — re-check after this many days;

  • 0 — always re-check;

  • negative — never re-check (the loaded needs are reused indefinitely).

A re-check sends the ETag / Last-Modified of the last response, so an unchanged source costs one small request and the needs are kept.

needs.remote.offline
Type:
boolean
Default:
false

When true, never fetch remote sources: each one keeps the needs it was last loaded with, and is reported as skipped. Useful for network-restricted CI, or for working offline against an index that was built while online.

needs.remote.timeout
Type:
float
Default:
10.0

Timeout, in seconds, for each remote needs.json request.

needs.render_context
Type:
table of (scalar or array of scalars or table of (scalar or array of values or table of values))
Default:
{}

Values added to the template context of every needuml and needarch.

A directive’s own :extra: shadows a name given here, and — unlike :extra: — these values reach templates rendered through uml() at every level of recursion. The four helper names (need, flow, filter, ref) cannot be shadowed. Values may be strings, numbers, booleans, arrays of those, or nested tables. Unset is the same as no values. A TOML date-time is not a value here; quote it as a string.

Each entry: A value in the variant data tree: a scalar, an array of scalars, or a nested table.

Under variants.data and needs.variant_data an array’s elements must share one type.

Forms:

  • a scalar: A single scalar value.

  • an array of scalars: An array of scalar values.

    Under variants.data and needs.variant_data the elements must all be of one type.

  • a table of (scalar or array of scalars or table of values): A nested map of variant values.

needs.report_template
Type:
string
Default:
""

The Jinja template file every .. needreport:: renders from.

The template is given the report’s types, links, options, usage and report_directive data and must produce reStructuredText; a section the directive did not ask for is empty rather than missing. A relative path is taken from the directory holding this configuration file. A directive’s own :template: option wins over this key. Unset — or set to "" — renders ubCode’s built-in report instead.

Give the file an extension the project does not build as a document (.need, .txt), or it is indexed as a page of its own as well.

needs.reproducible_json
Type:
boolean
Default:
false

Accepted for Sphinx-Needs compatibility; has no effect.

ubCode’s needs.json never contains a build timestamp, so it is already byte-identical across builds of unchanged sources whatever this is set to.

needs.schema_definitions_from_json
Type:
string
Default:
""

Path to a JSON file containing schema definitions.

needs.statuses
Type:
array of tables
Default:
[]

If given, only the defined statuses are allowed.

Each entry: Allowed need status

needs.statuses[].description
Type:
string
Default:
""

The description of the status.

needs.statuses[].name
Type:
string

The name of the status.

Type:
table of tables
Default:
{}

Rules that render matching need field values as hyperlinks.

Each entry: A rule that renders matching values of the need fields it names as hyperlinks.

All four keys are required: a rule missing one — or whose regex or templates do not compile — is reported and ignored, and the fields it names keep rendering as plain text.

Type:
string
Default:
""

The link’s visible text, as a template over the same named groups — for example "Ticket {{value}}".

A rendered empty label draws no link: the value renders as plain text.

Type:
string
Default:
""

The link target, as a template over the pattern’s named groups — for example "https://tracker.example.com/{{value}}".

Must render to an https://, http:// or mailto: URL, or to a relative path; anything else is refused and the value renders as plain text.

needs.string_links.<name>.options
Type:
array of strings
Default:
[]

The need fields this rule applies to.

A listed field’s value is split on , and ; and each item is matched on its own, so a multi-value field becomes several links. Where more than one rule lists the same field, only the FIRST rule declared is tried.

needs.string_links.<name>.regex
Type:
string
Default:
""

The pattern a value must match for this rule to draw a link.

Searched for anywhere in the value unless anchored with ^/$, and a match replaces the WHOLE value with the link. Its named capture groups ((?P<name>...)) are the variables the two templates render with; unnamed groups are not available to them. Look-ahead, look-behind and backreferences are not supported.

needs.table_page_size
Type:
integer
Default:
10

How many rows an interactive needtable shows per page.

A needtable that sets its own :page_size: uses that instead, and a reader can choose another size from the table’s own control. Must be a positive integer; unset is the same as 10. It has no effect on a :style: table table, which shows every row it rendered.

needs.table_page_sizes
Type:
array of integers
Default:
[10, 25, 50, 0]

The page sizes an interactive needtable’s control offers.

A non-empty list of non-negative integers, where 0 means “All”. The page size actually in use is added to the list when it is not already there, so the control can always show it. Unset is the same as [10, 25, 50, 0].

needs.table_style
Type:
string
Default:
"datatables"

The style a needtable renders in when it sets no :style: of its own.

datatables is the interactive table: it sorts, filters, pages, hides columns and exports in the browser. table is the static one — a scroll frame with a sticky header and no client-side behaviour. A needtable that sets its own :style: uses that instead. Unset (or an empty string) is the same as datatables.

needs.tags
Type:
array of tables
Default:
[]

If given, only the defined tags are allowed.

Each entry: Allowed need tag

needs.tags[].description
Type:
string
Default:
""

The description of the tag.

needs.tags[].name
Type:
string

The name of the tag.

needs.title_from_content
Type:
boolean
Default:
false

Base auto-generated titles on the content.

needs.title_optional
Type:
boolean
Default:
false

If True, a title is optional.

needs.types
Type:
array of tables or table of tables

The need types: an array of [[needs.types]] entries, each naming its directive, or one [needs.types.<directive>] table per type. Both shapes mean the same, and the types keep the order they are given in. An entry that cannot be used is reported and left out; unset, the four built-in types req, spec, impl and test. An entry naming a built-in type with neither title nor prefix narrows that type: it takes the built-in’s title and prefix, and its color and style where it gives none, and its own fields, links and inherits apply. Entries that give no title and no prefix keep all four built-in types; once an entry gives either, the types given replace them.

Forms:

  • an array of tables: One [[needs.types]] entry per need type, each naming its directive.

  • a table of tables: One [needs.types.<directive>] table per need type.

Each entry: Defines a need type.

Each entry: A need type, keyed by its directive name.

needs.types[].color
Type:
string
Default:
"#000000"

The color to use in diagrams, and as the need-card accent when you have chosen one. A hex color (#RGB, #RRGGBB or #RRGGBBAA) outlines the card’s type badge and paints its leading edge, unless an explicit *_border style frames all four edges. The default #000000 means no accent rather than black (use e.g. #010101 for a near-black one), and the built-in types do not accent cards while they carry their shipped colors. Diagrams always use the color.

needs.types[].directive
Type:
string

The directive name.

needs.types[].fields
Type:
table of tables

The type’s declarations of fields, by field name: each narrows the field for the needs of the type.

Each entry: A need type’s declaration of a field ([needs.types.<type>.fields.<field>]), narrowing the field’s own declaration for the needs of the type.

needs.types[].fields.<name>.default
Type:
value

The type’s default value, valid against its narrowed schema.

needs.types[].fields.<name>.derive
Type:
table

A rule computing the field on the needs of this type and of each type inheriting from it that gives no rule of its own, as derive takes one. It overrides the field’s derive for those types; a derive_by_type entry the field gives for the same type wins over it, and is reported.

Forms:

  • kind = "copy": Copy one field: of this need, of the need from names, of the target needs of over, or of the needs matching this one by join.

  • kind = "sum": The sum of field over the candidates.

  • kind = "count": The number of candidates.

  • kind = "min": The least value of field over the candidates (an ordered enum or a number).

  • kind = "max": The greatest value of field over the candidates (an ordered enum or a number).

  • kind = "any": Whether some candidate holds: a boolean field or a test. False with no candidates.

  • kind = "all": Whether every candidate holds: a boolean field or a test. True with no candidates.

  • kind = "collect": The distinct values of field over the candidates, as a list.

  • kind = "hash": A SHA-256 of the need’s own fields, computed after every other derived field.

  • kind = "fingerprint": A SHA-256 of the whole need: id, type, title, status, tags, content, every field the project declares and every link type (links among them), none of them derived, each where it differs from its default; never parent_needs or a field ubCode adds. Computed after every other derived field.

Takes the same keys as needs.extra_options[].derive.

needs.types[].fields.<name>.description
Type:
string

The type’s description of the field.

needs.types[].fields.<name>.nullable
Type:
boolean

false where the field is nullable: then a need of the type without a value takes the type’s default, and without one is not created. Never true where the field is not nullable.

needs.types[].fields.<name>.predicates
Type:
array of arrays

[match expression, value] pairs, in place of the field’s: the first that matches a need of the type gives its value. An empty list: none.

needs.types[].fields.<name>.schema
Type:
table

The type’s schema of the field: only the keywords it changes, the others are kept. Each keyword may only be stricter than the field’s (an enum a subset, a minimum higher); the type is the field’s.

needs.types[].inherits
Type:
string

The directive name of the need type this one starts from: a field or link type it does not declare itself, it declares as its parent does.

Type:
table of tables

The type’s declarations of link types, by link type name: each narrows the link type for the needs of the type.

Each entry: A need type’s declaration of a link type ([needs.types.<type>.links.<link>]), narrowing the link type’s own declaration for the needs of the type.

Type:
boolean

The link type’s own on every need type: given here, it is reported and ignored.

needs.types[].links.<name>.color
Type:
string

The link type’s own on every need type: given here, it is reported and ignored.

needs.types[].links.<name>.copy
Type:
boolean

The link type’s own on every need type: given here, it is reported and ignored.

needs.types[].links.<name>.default
Type:
value

The type’s default links.

needs.types[].links.<name>.derive
Type:
table

A rule computing the links of the needs of this type and of each type inheriting from it that gives no rule of its own, as derive takes one. It overrides the link type’s derive for those types; a derive_by_type entry the link type gives for the same type wins over it, and is reported.

Forms:

  • kind = "links": Link every need passing the where filter, or matching this need by join (both given: the matches passing the filter).

  • kind = "content_links": Link the needs the need’s content references with :need:.

  • kind = "union": Hold the links of the need’s own link types fields names, in that order, each link once (by its target, part and condition). A dead link or a link condition is reported at the link type it comes from (on a need from a needs.json, at the union).

Takes the same keys as needs.extra_links[].derive.

needs.types[].links.<name>.description
Type:
string

The type’s description of the link type: accepted, and not shown yet.

needs.types[].links.<name>.incoming
Type:
string

The link type’s own on every need type: given here, it is reported and ignored.

needs.types[].links.<name>.outgoing
Type:
string

The link type’s own on every need type: given here, it is reported and ignored.

needs.types[].links.<name>.predicates
Type:
array of arrays

[match expression, links] pairs, in place of the link type’s. An empty list: none.

needs.types[].links.<name>.schema
Type:
table

The type’s schema of the link list (maxItems, minItems, …): only the keywords it changes, each only stricter than the link type’s.

needs.types[].links.<name>.style
Type:
string

The link type’s own on every need type: given here, it is reported and ignored.

needs.types[].links.<name>.style_end
Type:
string

The link type’s own on every need type: given here, it is reported and ignored.

needs.types[].links.<name>.style_part
Type:
string

The link type’s own on every need type: given here, it is reported and ignored.

needs.types[].links.<name>.style_start
Type:
string

The link type’s own on every need type: given here, it is reported and ignored.

needs.types[].links.<name>.target_types
Type:
array of strings

The need types the links of the type’s needs may point to, by directive name; a type inheriting from a listed type is accepted. It may only narrow what the parent type and the link type accept: a wider list is reported, and the entry ignored. A derived link type takes none. Unset: the target types it inherits, or any type.

needs.types[].prefix
Type:
string

The prefix to use for auto-generated need IDs.

needs.types[].style
Type:
string
Default:
"node"

The default style to use in diagrams.

needs.types[].title
Type:
string

A human readable title.

needs.types.<name>.color
Type:
string
Default:
"#000000"

The color to use in diagrams, and as the need-card accent when you have chosen one. A hex color (#RGB, #RRGGBB or #RRGGBBAA) outlines the card’s type badge and paints its leading edge, unless an explicit *_border style frames all four edges. The default #000000 means no accent rather than black (use e.g. #010101 for a near-black one), and the built-in types do not accent cards while they carry their shipped colors. Diagrams always use the color.

needs.types.<name>.directive
Type:
string

Optional: the table’s key names the directive. A different value is reported and ignored.

needs.types.<name>.fields
Type:
table of tables

The type’s declarations of fields, by field name: each narrows the field for the needs of the type.

Takes the same keys as needs.types[].fields.

needs.types.<name>.inherits
Type:
string

The directive name of the need type this one starts from: a field or link type it does not declare itself, it declares as its parent does.

Type:
table of tables

The type’s declarations of link types, by link type name: each narrows the link type for the needs of the type.

Takes the same keys as needs.types[].links.

needs.types.<name>.prefix
Type:
string

The prefix to use for auto-generated need IDs.

needs.types.<name>.style
Type:
string
Default:
"node"

The default style to use in diagrams.

needs.types.<name>.title
Type:
string

A human readable title.

needs.variant_data
Type:
table of (scalar or array of scalars or table of (scalar or array of values or table of values))

Nested variant data accessible as var.* in filter expressions.

Provides a hierarchical key-value store for build-variant-aware filtering (e.g., var.cpu == "arm" or "feature_a" in var.build.features). A configuration that extends another, and a -c override, merge their values over the inherited ones, key by key.

Read only when [variants] sets neither data nor data_file.

Each entry: A value in the variant data tree: a scalar, an array of scalars, or a nested table.

Under variants.data and needs.variant_data an array’s elements must share one type.

Forms:

  • a scalar: A single scalar value.

  • an array of scalars: An array of scalar values.

    Under variants.data and needs.variant_data the elements must all be of one type.

  • a table of (scalar or array of scalars or table of values): A nested map of variant values.

needs.variant_data_file
Type:
string

Path to a JSON file containing variant data.

If both this and variant_data are set, the file is loaded first and inline values are deep-merged on top (inline wins).

Read only when [variants] sets neither data nor data_file.

needs.variant_options
Type:
array of strings
Default:
[]

Set of need fields that may contain variant functions.

needs.variants
Type:
table of strings
Default:
{}

Named variant definitions, mapping names to filter expressions.

When a variant function uses a simple (non-bracketed) expression like <<name: value>>, the name is looked up in this mapping to get the actual filter expression that is evaluated against the need’s data.

needs.views_max_items
Type:
integer
Default:
100

The default :max_items: cap for the need view directives (needlist, needtable, needflow, needsequence).

A view that sets no :max_items: renders at most this many items and shows a notice saying how many of how many are displayed; a view that sets its own :max_items: uses that value instead. Unset is the same as 100; 0 means no cap, from either source. The cap applies after the filter and the sort, in both the editor’s rendered preview and ubc build html.