Describe a JSON Schema as documentation, for readers. More...

Classes
class	sourcemeta::blaze::DocumentationError

Functions
SOURCEMETA_BLAZE_DOCUMENTATION_EXPORT auto	sourcemeta::blaze::to_documentation (const sourcemeta::core::JSON &schema, const sourcemeta::core::SchemaWalker &walker, const sourcemeta::core::SchemaResolver &resolver, const std::string_view default_dialect="") -> sourcemeta::core::JSON
SOURCEMETA_BLAZE_DOCUMENTATION_EXPORT auto	sourcemeta::blaze::to_html (const sourcemeta::core::JSON &documentation, std::string &output, const bool pretty=false) -> void

Variables
constexpr std::string_view	sourcemeta::blaze::DOCUMENTATION_FORMAT

Detailed Description

Describe a JSON Schema as documentation, for readers.

This functionality is included as follows:

#include <sourcemeta/blaze/documentation.h>

A schema is converted once into the table format, a description of data that does not depend on any schema language, and a renderer reads that format instead of the schema. The format states what a reader needs: which properties there are, what may go in each, and which are required. Every rule it states holds for the data the schema accepts, and a schema it cannot describe exactly is refused.

Class Documentation

◆ sourcemeta::blaze::DocumentationError

class sourcemeta::blaze::DocumentationError

A schema that cannot be described in the table format exactly, with the place in the schema that cannot be described.

Inheritance diagram for sourcemeta::blaze::DocumentationError:

Public Member Functions
	DocumentationError (const char *message, sourcemeta::core::Pointer location, std::string subject="")
auto	what () const noexcept -> const char *override
auto	subject () const noexcept -> std::string_view
auto	location () const noexcept -> const sourcemeta::core::Pointer &
	Where in the schema the trouble is.

Constructor & Destructor Documentation

◆ DocumentationError()

sourcemeta::blaze::DocumentationError::DocumentationError	(	const char *	message,
		sourcemeta::core::Pointer	location,
		std::string	subject = "" )

inline

The message is a fixed sentence, so it cannot be built out of whatever the schema happened to hold. What the sentence is about, such as the keyword at fault, is the subject.

Member Function Documentation

◆ subject()

auto sourcemeta::blaze::DocumentationError::subject ( ) const->std::string_view

inlinenodiscardnoexcept

What the message is about, such as the keyword that cannot be described. Empty when the message speaks for itself.

Function Documentation

◆ to_documentation()

SOURCEMETA_BLAZE_DOCUMENTATION_EXPORT auto sourcemeta::blaze::to_documentation	(	const sourcemeta::core::JSON &	schema,
		const sourcemeta::core::SchemaWalker &	walker,
		const sourcemeta::core::SchemaResolver &	resolver,
		const std::string_view	default_dialect = "" )->sourcemeta::core::JSON

nodiscard

Describe a JSON Schema in the table format. For example:

#include <sourcemeta/blaze/documentation.h>
 
#include <sourcemeta/core/jsonschema.h>
#include <sourcemeta/core/json.h>
 
#include <cassert>
 
const sourcemeta::core::JSON schema =
    sourcemeta::core::parse_json(R"JSON({
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "string"
})JSON");
 
const auto documentation{sourcemeta::blaze::to_documentation(
    schema, sourcemeta::core::schema_walker,
    sourcemeta::core::schema_resolver)};
 
assert(documentation.at("root").at("kind").to_string() == "string");

Throws sourcemeta::blaze::DocumentationError when the schema cannot be described exactly, saying what and where.

◆ to_html()

SOURCEMETA_BLAZE_DOCUMENTATION_EXPORT auto sourcemeta::blaze::to_html	(	const sourcemeta::core::JSON &	documentation,
		std::string &	output,
		const bool	pretty = false )->void

Render a table format document as HTML. The renderer reads the format alone, so it draws a page for a schema of any language that was converted into it. For example:

#include <sourcemeta/blaze/documentation.h>
 
#include <sourcemeta/core/json.h>
 
#include <cassert>
 
const sourcemeta::core::JSON documentation =
    sourcemeta::core::parse_json(R"JSON({
  "$schema":
  "tag:sourcemeta.com,2026:table-format/2",
  "title": "Order",
  "language": "https://json-schema.org/draft/2020-12/schema",
  "root": { "kind": "string" }
})JSON");
 
std::string page;
sourcemeta::blaze::to_html(documentation, page);
assert(!page.empty());

The HTML is appended to the given string. It carries no stylesheet: wrap it in an element of your own and style it through its class names. A pretty page puts every block on a line of its own, indented by how deep it is.

Variable Documentation

◆ DOCUMENTATION_FORMAT

std::string_view sourcemeta::blaze::DOCUMENTATION_FORMAT

constexpr

Initial value:

{

"tag:sourcemeta.com,2026:table-format/2"}

The address of the table format, which a document states as its $schema.

Classes

Functions

Variables