## XField Usage Rules XField is structured data field, suitable for displaying API parameters, return values, context data, and any structured data with metadata in a clean, organized format. Supports nested structures for complex data types. ### Attributes - `data-name` (optional): The name of the field/parameter - `data-type` (optional): The data type of the field (e.g., "string", "number", "boolean", "symbol", "object", "array", "function") - `data-default` (optional): Default value for the field - `data-required` (optional): Whether the field is required ("true" or "false") - `data-deprecated` (optional): Whether the field is deprecated ("true" or "false") - `data-desc` (optional): Simple description of the field. Do not use any Markdown syntax (see `` for the full list). ### Children - For simple types (string, number, boolean): children can be empty or contain exactly one `` element - For complex types (object, array), children contain nested `` elements and optionally one `` element ### Usage Rules - **Opening/Closing Tags Format**: `` for all types - **Maximum Nesting Depth**: 5 levels (to avoid overly complex structures) - **Description Mutually Exclusive**: Use either `data-desc` attribute OR `` element, not both - **Single Description Rule**: Only one `` element per `` is allowed - **Grouping Requirement**: Wrap the outermost `` elements with ``, even if there's only one `` element - **Recursive Structure**: Use recursive `` structures to fully express complex object type hierarchies, decomposing all nested properties into more fundamental types - **Fixed Value Fields**: For fields that accept a limited set of predefined values (including enums, constants, or fixed strings), use `` with the base data type (e.g., "string", "number") in the `data-type` attribute, and list all possible values in the description. - **Function-Type Fields**: For fields with `data-type="function"`, nest `` elements for parameters (`data-name="parameters"`) and return value (`data-name="returnValue"`) **whenever their types are available**. ### Good Examples - Example 1: Simple field with all attributes ```md ### Returns ``` - Example 2: Field with markdown description ```md ### Context Your **API key** for authentication. Generate one from the `Settings > API Keys` section. Keep it secure and never expose it in client-side code. ``` - Example 3: Nested object structure ```md ### Properties Contains all **authentication** and **authorization** data for the current user session. This object is automatically populated after successful login. Primary email address used for **login** and **notifications**. Must be a valid email format. Array of **permission strings** that determine what actions the user can perform. Common values: `"read"`, `"write"`, `"admin"`, `"delete"`. ``` - Example 4: Multiple fields for Parameters ```md ### Parameters Response format: `json` or `xml` ``` - Example 5: Enum values with base type and description ```md ### Status Priority level for the task. **Valid values**: `1` (low), `2` (medium), `3` (high), `4` (urgent) ``` - Example 6: Function type field with nested parameters and return value ```md ### API Methods ``` ### Bad Examples - Example 1: Using self-closing tag (violates "Opening/Closing Tags Format" rule) ```md ``` - Example 2: Using both `data-desc` and `` (violates "Description Mutually Exclusive" rule) ```md Your **API key** for authentication. Keep it secure and never expose it. ``` - Example 3: Using multiple `` elements (violates "Single Description Rule") ```md Configuration object for the application. Contains all runtime settings and preferences. ``` - Example 4: Nesting other child elements (violates "Children" rule) ```md
User information
 ``` - Example 5: Missing x-field-group wrapper (violates "Grouping Requirement" rule) ```md ``` - Example 6: Exceeding maximum nesting depth (violates "Maximum Nesting Depth" rule) ```md ```