# 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:

```text
/// 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:

```text
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](https://zod.dev/json-schema?id=string-formats#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:

```text
/// 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.