Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.dataharbor.co/llms.txt

Use this file to discover all available pages before exploring further.

​
Output Formatting

JSON in, any format out. Zero client code. Virtual API responses are JSON by default. Output formatting lets you convert responses to Markdown, CSV, or YAML — configured in your Virtual API Configuration, requested via URL extension, or negotiated through the HTTP Accept header. Especially useful for AI agents that present data to humans, or for feeding governed data directly into spreadsheets and configuration tools.
Output formatting runs after input normalization and the ordered controls pipeline. It only changes how the final governed payload is rendered. See Data Pipeline for the full request flow.

​
Quick start

Add default_output_format to any Virtual API Configuration: 
version: "0.3"
default_output_format: markdown
objects:
  customers:
    controls:
      - type: redact
        fields: [ssn]
      - type: tokenize
        fields: [email]
Every response from this Virtual API is now Markdown instead of JSON.

​
Supported output formats

FormatBest forResponse Content-Type
jsonSystem-to-system integrations and default runtime behaviorapplication/json
markdownAI agents, human-readable responses, quick inspectiontext/markdown; charset=utf-8
csvSpreadsheets, BI tools, exportstext/csv; charset=utf-8
yamlConfig workflows and human-readable structured outputtext/yaml; charset=utf-8

​
Requesting a format

Use default_output_format to set a default, or request a format per call with a URL extension or Accept header.
Set default_output_format in the Virtual API Configuration when one format should be returned by default.
version: "0.3"
default_output_format: markdown
objects:
  customers:
    controls:
      - type: allow
        fields: [name, status]
default_output_format: json is also valid when you want to make the contract explicit without changing behavior.
input_format is a separate setting used during input normalization. It affects how upstream data is parsed, not how the response is rendered.

​
Precedence

Format selection follows a four-tier precedence (highest to lowest):
PrioritySourceExample
1URL extension.md, .csv, .yaml, .json
2Accept headerAccept: text/markdown
3Spec defaultdefault_output_format: markdown
4Runtime defaultJSON
The first match wins.
default_output_formatURL extensionAccept headerResult
markdown.jsontext/csvJSON — URL extension wins
json(none)text/markdownMarkdown — Accept header wins over spec
markdown(none)(none)Markdown — spec default applies
(omitted)(none)text/csvCSV — Accept header applies
(omitted).mdtext/csvMarkdown — URL extension wins
(omitted)(none)(none)JSON — default runtime behavior

​
How each format renders

​
Markdown

Markdown output is structure-driven.
JSON shapeMarkdown representation
Array of flat objectsTable
Single flat objectKey-value list
Nested objectHeadings plus nested content
Array of scalarsBullet list
Scalar valuePlain text
Example: 
[
  { "name": "Alice", "role": "Admin" },
  { "name": "Bob", "role": "Viewer" }
]

| name | role |
|---|---|
| Alice | Admin |
| Bob | Viewer |
See Markdown Input if your upstream source itself is Markdown.

​
CSV

CSV output follows RFC 4180.
JSON shapeCSV representation
Array of flat objectsHeader row plus one row per object
Single flat objectHeader row plus a single row
Nested objects or arraysSerialized as JSON strings in the cell
Null valuesEmpty cell
Scalar valuePlain text
Values containing commas, quotes, or newlines are automatically quoted. Objects with different key sets are handled by using the union of all keys in the header row.

​
YAML

YAML output uses standard YAML 1.2 formatting.
JSON shapeYAML representation
Objectkey: value pairs
Array of objects- key: value block sequence
Array of scalars- item list
Strings with special charactersQuoted with escape sequences
Numbers and booleansUnquoted
Nullnull

​
Response headers

The response Content-Type reflects the selected output format, and Vary: Accept is always included so caches differentiate negotiated responses correctly.

​
Advanced HTTP negotiation

Many AI agents already send Accept headers that prefer Markdown. For example, Claude Code typically sends Accept: text/markdown, text/html, */*, which means DataHarbor can return Markdown without any spec or URL changes.This behavior also carries through MCP delivery when the agent’s Accept header is forwarded to the lease endpoint.
The Accept header supports quality values (q) to express preference.
Accept: text/markdown, text/csv;q=0.5, application/json;q=0.2
DataHarbor picks the supported format with the highest q-value.
When the Accept header explicitly excludes all supported formats and contains no wildcard fallback, DataHarbor returns 406 Not Acceptable.When Accept is */* or missing, DataHarbor falls through to the spec default or JSON behavior instead. Responses always include Vary: Accept for cache correctness.

​
Next steps

Connect Sources

Start with how upstream formats enter DataHarbor

Input Normalization

See how upstream JSON, CSV, YAML, and Markdown are parsed

Markdown Input

Learn how Markdown sources normalize before controls run

REST API Delivery

Request formatted responses over fetch and relay endpoints