citum-server

citum-server exposes Citum citation rendering through JSON-RPC. Use it when a client should talk to a long-running process instead of linking citum-engine directly.

The same dispatcher is available over two transports:

stdin/stdout: newline-delimited JSON-RPC, enabled in every build
HTTP: POST /rpc, enabled by the default http feature

The document-level RPC method is format_document. The single-citation and bibliography methods are convenience methods for smaller workflows.

Run It

From the workspace root:

cargo run -p citum-server

That starts stdio mode. It reads one JSON object per line from stdin and writes one JSON object per line to stdout.

For HTTP mode:

cargo run -p citum-server -- --http --port 9000

The examples below assume they are run from the Citum repository root so the relative style path styles/embedded/apa-7th.yaml resolves. Outside the repository, replace that value with an absolute path to a Citum YAML style.

JSON-RPC Envelope

Every request has this shape:

{
  "id": 1,
  "method": "render_citation",
  "params": {}
}

Successful responses echo the request ID and include result:

{
  "id": 1,
  "result": "..."
}

Errors echo the request ID when available and include error:

{
  "id": 1,
  "error": "missing required field: style_path"
}

refs in render_citation and render_bibliography is an inline JSON map of reference objects. refs in format_document accepts a tagged input object — see the refs input section below. Reference data uses native Citum schema. Dates are EDTF strings such as "1988", not CSL-JSON date-parts objects.

Method Summary

Method	Required params	Optional params	Result
`render_citation`	`style_path`, `refs`, `citation`	`output_format`, `inject_ast_indices`	rendered citation string
`render_bibliography`	`style_path`, `refs`	`output_format`, `inject_ast_indices`	`{format, content, entries}`
`validate_style`	`style_path`	none	`{valid, warnings}`
`format_document`	`style`, `refs`, `citations`	`output_format`, `locale`, `document_options`	`{formatted_citations, bibliography, warnings}`

Supported output_format values are plain (default), html, djot, latex, and typst.

render_citation, render_bibliography, and validate_style use style_path, a string path to a local Citum YAML style. format_document uses the richer style object:

{ "kind": "path", "value": "styles/embedded/apa-7th.yaml" }

Other style.kind values are id, uri, and yaml.

Stdio Example: `render_citation`

The stdio transport expects each request on a single line:

printf '%s\n' '{"id":1,"method":"render_citation","params":{"style_path":"styles/embedded/apa-7th.yaml","refs":{"hawking1988":{"id":"hawking1988","class":"monograph","type":"book","title":"A Brief History of Time","author":[{"family":"Hawking","given":"Stephen"}],"issued":"1988"}},"citation":{"id":"cite-1","items":[{"id":"hawking1988"}]}}}' \
  | cargo run -q -p citum-server

The response is a JSON object whose result is the rendered citation string.

HTTP Example: `render_bibliography`

Start the server in another terminal:

cargo run -q -p citum-server -- --http --port 9000

Then send a request:

curl -s http://localhost:9000/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 2,
    "method": "render_bibliography",
    "params": {
      "style_path": "styles/embedded/apa-7th.yaml",
      "output_format": "html",
      "refs": {
        "hawking1988": {
          "id": "hawking1988",
          "class": "monograph",
          "type": "book",
          "title": "A Brief History of Time",
          "author": [{ "family": "Hawking", "given": "Stephen" }],
          "issued": "1988"
        }
      }
    }
  }'

The response result contains:

format: the selected output format
content: the rendered bibliography
entries: optional plain-text entry strings when the renderer supplies them

Full Document Example: `format_document`

Use format_document when the client has the whole document citation order. This is the preferred editor and word-processor integration method because it lets the engine render document-sensitive citation state and bibliography output in one call.

HTTP `format_document`

Use this form when the server is running with --http:

curl -s http://localhost:9000/rpc \
  -H 'Content-Type: application/json' \
  -d '{
    "id": 3,
    "method": "format_document",
    "params": {
      "style": { "kind": "path", "value": "styles/embedded/apa-7th.yaml" },
      "output_format": "html",
      "refs": {
        "smith2010": {
          "id": "smith2010",
          "class": "monograph",
          "type": "book",
          "title": "Nationalism: Theory, Ideology, History",
          "author": [{ "family": "Smith", "given": "Anthony D." }],
          "issued": "2010",
          "publisher": { "name": "Polity" }
        }
      },
      "citations": [
        {
          "id": "cite-1",
          "items": [
            {
              "id": "smith2010",
              "locator": { "label": "page", "value": "10" }
            }
          ]
        }
      ],
      "document_options": {
        "show_semantics": true
      }
    }
  }'

Stdio JSON-RPC `format_document`

Use this form when the server is running in its default stdin/stdout mode. The request must be one JSON object on one line:

printf '%s\n' '{"id":3,"method":"format_document","params":{"style":{"kind":"path","value":"styles/embedded/apa-7th.yaml"},"output_format":"html","refs":{"smith2010":{"id":"smith2010","class":"monograph","type":"book","title":"Nationalism: Theory, Ideology, History","author":[{"family":"Smith","given":"Anthony D."}],"issued":"2010","publisher":{"name":"Polity"}}},"citations":[{"id":"cite-1","items":[{"id":"smith2010","locator":{"label":"page","value":"10"}}]}],"document_options":{"show_semantics":true}}}' \
  | cargo run -q -p citum-server

The response result has the same top-level shape over HTTP and stdio:

{
  "id": 3,
  "result": {
    "formatted_citations": [
      {
        "id": "cite-1",
        "text": "(<span class=\"citum-citation\" data-ref=\"smith2010\">Smith, <span class=\"citum-issued\">2010</span>, <span class=\"citum-variable\">p. 10</span></span>)",
        "ref_ids": ["smith2010"]
      }
    ],
    "bibliography": {
      "format": "html",
      "content": "<div class=\"citum-bibliography\">...</div>",
      "entries": [
        {
          "id": "smith2010",
          "text": "<div class=\"citum-bibliography\">...</div>",
          "metadata": {
            "author": "Smith",
            "year": "2010",
            "title": "Nationalism: Theory, Ideology, History"
          }
        }
      ]
    },
    "warnings": []
  }
}

Clients should read bibliography output from result.bibliography, not from result.formatted_citations.

`refs` Input for `format_document`

The refs field in format_document accepts a tagged input object, mirroring the style field. These are alternative shapes, not one combined JSON value:

{ "kind": "path",  "value": "/abs/path/to/refs.yaml" }

{ "kind": "yaml",  "value": "hawking1988:\n  id: hawking1988\n  ..." }

{ "kind": "json",  "value": { "hawking1988": { ... } } }

A bare JSON object (no kind key) is also accepted as {"kind": "json"} for backward compatibility.

path and yaml have the server read and parse the bibliography file; json passes inline reference data directly. Use path when the server and client share a filesystem (e.g., when called via pipe from a LuaLaTeX document).

Loading Local Files

Style and bibliography files on the same filesystem can be referenced by path in both style and refs:

printf '%s\n' '{
  "id": 4,
  "method": "format_document",
  "params": {
    "style":        { "kind": "path", "value": "styles/embedded/apa-7th.yaml" },
    "refs":         { "kind": "path", "value": "examples/document-refs-native.json" },
    "output_format": "html",
    "citations":    [{ "id": "cite-1", "items": [{ "id": "kuhn1962" }] }]
  }
}' | cargo run -q -p citum-server

For HTTP clients that prefer inline data, assemble the request with jq:

jq -n \
  --arg style_path "styles/embedded/apa-7th.yaml" \
  --slurpfile refs examples/document-refs-native.json \
  --slurpfile citations examples/document-citations.json \
  '{
    id: 4,
    method: "format_document",
    params: {
      style: { kind: "path", value: $style_path },
      refs:  { kind: "json", value: $refs[0] },
      citations: $citations[0],
      output_format: "html"
    }
  }' | curl -s http://localhost:9000/rpc \
    -H 'Content-Type: application/json' \
    -d @-

Discovery

HTTP mode exposes read-only discovery endpoints:

curl http://localhost:9000/rpc/methods

GET /rpc/methods returns supported methods, required fields, and optional fields.

curl http://localhost:9000/rpc/schema

GET /rpc/schema returns JSON Schemas for method parameters when the binary is built with the schema feature. Sending GET /rpc returns 405 Method Not Allowed with a JSON hint explaining that /rpc expects POST.

Features

Feature	Default	Description
`async`	on through `http`	Enables the Tokio runtime dependency used by HTTP transport
`http`	on	Enables the axum HTTP server and implies `async`
`schema`	off	Enables `/rpc/schema` and implies `http` plus schema type support
`schema-types`	off	Enables schema derivations without the HTTP schema endpoint

Build a stdio-only binary with:

cargo build -p citum-server --no-default-features
cargo install citum-server --no-default-features

Performance

A simulation script benchmarks a server-backed word-processor workflow:

cargo build --release -p citum-server
node scripts/benchmark-rpc-workflow.js

Dependencies

citum-server depends on citum-engine, citum-schema, and citum_store for rendering and the standard resolver chain. It does not depend on citum-migrate.

citum-server 0.57.0