#Request file anatomy

##Separators and comments

• Begin each request with a line that starts with ###. Everything up to the next separator belongs to the same request.
• Lines prefixed with #, //, or -- are treated as comments. Metadata directives live inside these comment blocks.
• A standalone comment whose content starts with @name is treated as a directive.
• At file or request scope, an unknown directive is ignored with a warning. A known directive used in the wrong place is handled the same way.
• Between @workflow and the next request, an unknown directive is a parse error. This catches mistakes such as @stpe that would otherwise remove a workflow step. Directives attached to requests are still request-scoped, even when a workflow runs those requests.
• After @mock and before the response, only @match and @expect are allowed. Any other directive-shaped comment is a parse error.
• To write a comment that starts like a directive, add another comment marker, for example ## @if ....
• A directive problem that does not invalidate the file becomes a warning rather than an error. Parsing continues and valid parts are retained where possible: an unrecognized option on @ssh, @k8s, @sse, or @websocket is dropped while the rest of the directive still applies, whereas a directive the parser cannot make sense of at all (an @capture with no usable scope, say) is dropped entirely and reported. Warnings never change the exit code.
• An option may appear only once in a directive. Resterm reports duplicates instead of silently keeping the last value. Repeated @match json and @match json-rules declarations are merged as described in Splitting a long matcher.
• Write options as key=value with no spaces around =. In most directives a key on its own is a switch set to true, so persist = false would otherwise turn persist on. key = value, key =value, key= value, and a field with no key such as =value are errors, and none of them sets the key. An empty value such as strict_hostkey= is still allowed at the end of the line or before another key=value option. A global or file @ssh or @k8s profile written this way is not available to requests. An @ssh profile is reported as not found, and a @k8s profile reports the error to every request that uses it.
• Alternate spellings count as the same option. For example, you cannot use both known_hosts and known-hosts on one @ssh directive. Empty values are ignored for regular options, but not for switches. strict_hostkey= enables the switch, so it conflicts with strict-hostkey=false.
• @compare requires non-empty values for its baseline and group options. This is stricter than general alias conflict handling: # @ssh host=h known-hosts=a known_hosts= is valid, but # @compare dev stage base=dev baseline= reports an empty baseline.
• Directives that require a value report value missing when left empty. This applies to @name, @operation, @grpc-descriptor, @grpc-authority, and @grpc-metadata. Some directives deliberately accept an empty value. @graphql enables GraphQL, @query and @variables read the lines below them, and @grpc-reflection defaults to on.
• A request directive that replaces one value may appear only once. This includes @auth, @name, @timeout, @when, @for-each, @trace, @profile, @compare, and the single-value gRPC and GraphQL directives. Resterm keeps the first valid declaration and reports later duplicates. An invalid declaration does not count, so a valid one may follow it. A GraphQL directive ignored while GraphQL is off does not count either, but it does produce a warning.
• Directives such as @tag, @capture, @assert, @apply, @var, @setting, and @body add to earlier declarations. @graphql, @sse, and @websocket may repeat because off resets their state. For GraphQL, the reset also clears @operation, @variables, and @query, so they may be declared again after @graphql off. Duplicate directive checks apply only within a request. File directives may repeat because some of them define named profiles.
• Files can be saved with parse errors. The status line shows the number of errors, for example Saved requests.http (1 parse error). Requests cannot run until those errors are fixed.
• In the TUI, live editor diagnostics underline offending text and show ERR <n> / WARN <n> counts beside the status message. Press K in editor normal mode for details on the current line, or g . / :diagnostics for the complete list. When editor diagnostics are disabled, the existing WARN line <n> segment reports warnings from the last matching parse. Parse warnings also appear in the Explain pane for each run.
• When editor diagnostics are disabled, editing hides the WARN line <n> segment until the document is parsed again on save, explicit reload, or request execution.
• resterm run lists warnings under WARN in text output, in the Warnings: section of a single-request result, and under warnings in JSON.

##Multiline directives

Some directives can span multiple comment lines. Resterm keeps reading while the directive's expression, matcher, or template is incomplete:

# @assert licensing.assertResponse(
#   response,
#   expected,
#   options
# )

• RestermScript expressions continue while an opening (, [, or { remains unmatched outside a string or comment. This applies to @assert, @when, @skip-if, @capture, @apply, @patch, @for-each, @if, @elif, @switch, and @case.
• @match continues while a quoted or bracketed option value remains open. See Splitting a long matcher.
• Text captures continue while a {{ marker remains open. See Captures.
• Continuation lines may use any supported comment marker and do not repeat the directive name. Directives such as @name, @tag, and @step remain on one line.
• Only the expression can keep a directive open. Names, messages, options, and loop variables do not. Separators such as =>, run=, as, and in only count outside strings, comments, and nested groups.
• Options and loop variables after the closing delimiter remain part of the directive.
• A new directive, a non-comment line, a request separator, or the end of the file stops collection. Resterm reports an unmatched delimiter at the opening line and drops the incomplete directive.
• Errors inside continued expressions keep their original line and column. Reports and stack frames show the expression on one line.

##Metadata directives

##Body content

• Inline: everything after the blank line separating headers and body.
• External file: < ./payloads/create-user.json loads the file relative to the request file. To also search the workspace root / current working directory, set RESTERM_ENABLE_FALLBACK=1 (opt-in).
• Inline includes: lines in the body starting with @ path/to/file are replaced with the file contents (useful for multi-part templates).
• XML/SOAP: inline XML is sent exactly as written after template expansion. XML tags such as <soap:Envelope> are body text, not file references.
• Forced inline body: add # @body inline (or # @body raw) when a literal body line intentionally looks like a file reference, such as < this is just a string. This only affects parsing. Template expansion and inline includes still work as usual.
• GraphQL: handled separately (see GraphQL).