gargamelle/documentation

Optional HTML documentation for Gargamelle’s emitted schema vocabulary. This is a presentation module, not a general JSON Schema validator.

Types

ExampleError

A rejected example’s zero-based position and ordinary validation errors.

pub type ExampleError {
  ExampleError(
    index: Int,
    errors: List(gargamelle.ValidationError),
  )
}

Constructors

ExampleError(
  index: Int,
  errors: List(gargamelle.ValidationError),
)

Values

escape_html

pub fn escape_html(s: String) -> String

Escape both text and double-quoted HTML attribute values.

render

pub fn render(
  definition: gargamelle.Plan(a, Nil),
  id: String,
) -> String

Render a definition with every shared definition visible in its own section. Supply a unique article ID when embedding multiple contracts on one page.

render_contract

pub fn render_contract(
  contract: gargamelle.Contract(a),
  id: String,
) -> String

Render the structural definition and every semantic requirement description. Rendering runs no conversion or requirement callbacks. Requirement prose is documentation; it does not establish that a callback implements that prose.

render_examples

pub fn render_examples(
  definition: gargamelle.Plan(a, Nil),
  id: String,
  examples: List(gargamelle.Json),
) -> Result(String, List(ExampleError))

Validate admitted input examples before displaying them. This never invokes decoding callbacks or modifies schema acceptance. Examples are JSON inputs, not decoded values; checking again at render time prevents silent drift.

render_schema

pub fn render_schema(
  source: String,
  id: String,
  aliases: List(#(String, String)),
) -> Result(String, String)

Render JSON emitted by Gargamelle. Aliases are optional presentation-only pairs (omitted definition, displayed definition); they must name existing definitions and point directly to a displayed definition. They do not change the schema or decoding. Explain any such compression in the surrounding page. Return an HTML fragment in Ok. Return Error when the schema JSON cannot be decoded or the aliases violate those preconditions. Error messages are human-readable explanations, not stable machine-readable codes.