Source manifest

OverviewCopy Anchor Link

Every work item shows where it came from: a name such as Jira, an item noun such as Issue or Ticket, and a small mark. Oxagen ships a built-in manifest for each tracker. A workspace changes any of them with a file in its steering repo.

A manifest is a TOML file at work/sources/<key>.toml, and it names an SVG file beside it.

Write a manifestCopy Anchor Link

# work/sources/jira.toml
schema = "source/v1"
type = "jira"
name = "Jira at Acme"
item_noun = "Ticket"
avatar = "jira.svg"
avatar_dark = "jira-dark.svg"

Any other key refuses the file, and so does a manifest over 4 KB. An .svg name is lowercase letters and digits with dots, hyphens, or underscores, starts with a letter or digit, and is at most 63 characters before .svg. A name or an item noun with a control character or a direction override refuses the file, so the text reads the same everywhere. Oxagen shows both as text and never reads them as an instruction.

The file name is the key. A key uses lowercase letters and digits, joined by single hyphens or underscores, up to 64 characters. The key tracker is reserved for items whose tracker Oxagen cannot tell. A file named for a type, such as jira.toml, replaces that type's built-in manifest, so its type must be that type. To describe a type under another key, name the file for a key of your own.

PrecedenceCopy Anchor Link

A collector shows the first of these that exists for its type:

1. The manifest its own source key names. A collector file sets it, as in source = "jira-acme".
2. The steering repo's file for the type, work/sources/<type>.toml.
3. The built-in manifest for the type.

A manifest of another type is skipped, so a source key that names one never makes a Jira collector read as GitHub. Oxagen resolves the source each time it reads an item and stores none on the item, so a change to a manifest shows on every item of that source at once.

SVG rulesCopy Anchor Link

Oxagen cleans each SVG into plain data and draws that data as its own elements. An image address or a piece of markup from your repository never reaches the page. One failed rule refuses the whole file.

• Size. At most 32 KB, 500 elements, and 16 levels of nesting. A path's d is at most 16 KB.
• Elements. One svg root with g, path, circle, ellipse, rect, line, polyline, polygon, defs, linearGradient, radialGradient, and stop. A title is allowed, and Oxagen drops its text because the app labels the mark with the source's name.
• Attributes. Only geometry, transform, paint, and gradient attributes. On the root, Oxagen drops width, height, role, and version, because the app sets the size. A rect keeps width and height.
• Paint. A color keyword, a hex color, rgb(), hsl(), none, currentColor, or url(#id) naming a gradient in the same file.
• Root. One svg root in the SVG namespace, with a viewBox of four numbers. Elements outside the namespace, a second root, and an entity refuse the file.
• Values. An attribute value over 512 characters, or one that is malformed for its attribute, refuses the file.
• Ids. A duplicate id refuses the file. Oxagen rewrites each id and each url(#id) to carry the file's hash, so two marks on one page never share an id.

Why a file is refusedCopy Anchor Link

Work setup shows each refused file with its reason. Oxagen keeps using the built-in manifest for that key until the file passes. list_work_sources returns the same list in refused.

Built-in marksCopy Anchor Link

GitHub, GitLab, Linear, and Jira ship with their own marks, in each vendor's color. The marks remain their owners' trademarks and show where an item came from. A tracker with no mark draws a plain tracker icon.