Candid Metadata Tags

@ic-reactor/parser preserves Candid doc comments and maps a small, JSDoc-style validation vocabulary into schema metadata.

This is not a Candid language standard. The standard base is ordinary Candid doc comments (/// and block doc comments). The tag vocabulary below is the IC Reactor contract for schema metadata consumed by downstream tooling, chosen to stay close to familiar JSON Schema and ts-to-zod names.

Comment Mapping

Doc comments immediately before a type, field, service, or method are attached to that node:

/// Account that receives tokens.
type Account = record {
  /// Owner principal.
  owner : principal;
};

/// Ledger service.
service : {
  /// Return an account balance.
  balance : (Account) -> (nat) query;
}

The parser emits:

• metadata.description: non-tag doc lines joined with newlines
• metadata.docs: all doc lines, including tag lines
• metadata.validation: parsed validation tags when present

Validation Tags

IC Reactor currently recognizes these tags:

Tag	Metadata	Typical use
@minimum <value> [message]	validation.minimum	Numeric lower bounds
@maximum <value> [message]	validation.maximum	Numeric upper bounds
@minLength <value> [message]	validation.minLength	Text, blob, or vector lower length
@maxLength <value> [message]	validation.maxLength	Text, blob, or vector upper length
@pattern <regex>	validation.pattern	Text pattern hints
@format <type> [message]	validation.format	Named formats such as email or uuid

Example:

type Profile = record {
  /// Display name.
  /// @minLength 2
  /// @maxLength 32
  name : text;

  /// Contact email.
  /// @format email
  email : text;
};

The parsed schema keeps this metadata on the corresponding nodes, so any downstream tooling — generated forms, documentation, AI context — can read metadata.validation alongside the type information.

Recognized Format Names

The @format vocabulary is aligned with Zod string formats.

Recognized names:

• email
• date-time
• datetime
• date
• time
• duration
• url
• uri
• httpsUrl
• ipv4
• ipv6
• uuid
• guid
• base64
• base64url
• cuid
• cuid2
• ulid
• nanoid
• emoji
• cidrv4
• cidrv6
• mac

Tags can be used with or without an inline message:

/// Contact email.
/// @format email
email : text;

/// Public profile identifier.
/// @format uuid UUID
id : text;

Both forms are preserved in metadata.validation.format; when a message is present it accompanies the format name.

Runtime Validation

These tags are metadata only today. They are meant for generated forms, documentation, AI context, and future validation helpers; nothing in the generated output enforces them.