describe.h File Reference

An a11::actions::ActionSchema in JSON, which is how one travels. More...

#include <string>
#include <string_view>
#include <vector>
#include <absl/status/statusor.h>
#include <nlohmann/json_fwd.hpp>
#include "a11/actions/schema.h"

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	a11::actions::SchemaQuery
	Which schemas to write, and how much of each. More...

Namespaces
namespace	a11
namespace	a11::actions

Enumerations
enum class	a11::actions::PortView { a11::actions::kCallable , a11::actions::kAll }
	Which ports a written schema includes. More...

Functions
absl::StatusOr< SchemaQuery >	a11::actions::ParseSchemaQuery (std::string_view encoded)
	Parses a SchemaQuery from the request port's JSON.
absl::StatusOr< SchemaQuery >	a11::actions::ParseSchemaQueryString (std::string_view query)
	Parses a SchemaQuery from a URL query string.
bool	a11::actions::SchemaQueryAccepts (const SchemaQuery &query, std::string_view name)
	Whether name matches query's name filters.
nlohmann::json	a11::actions::SchemaToJson (const ActionSchema &schema, bool runnable, PortView ports=PortView::kCallable)
	One schema as an actions entry.
nlohmann::json	a11::actions::RegistryToJson (const ActionRegistry &registry, const SchemaQuery &query)
	A whole document: every schema in registry that query accepts.
absl::StatusOr< std::string >	a11::actions::RegistryToJsonText (const ActionRegistry &registry, const SchemaQuery &query)
	RegistryToJson as text, or why it could not be encoded.
absl::StatusOr< std::string >	a11::actions::SchemaToJsonText (const ActionSchema &schema, bool runnable, PortView ports=PortView::kCallable)
	One schema as a whole document, for a route that answers with one.
absl::StatusOr< ActionSchema >	a11::actions::SchemaFromJson (const nlohmann::json &entry)
	The schema an actions entry was written from.
absl::StatusOr< ActionSchema >	a11::actions::SchemaFromJsonText (std::string_view encoded)
	SchemaFromJson, parsing encoded first.
absl::StatusOr< std::vector< nlohmann::json > >	a11::actions::SchemasInDocument (const nlohmann::json &document)
	The actions entries of document, or why there are none to read.

Variables
constexpr std::string_view	a11::actions::kSchemaDocumentFormat = "a11.actions/v1"
	The format field of the schema document.

Detailed Description

An a11::actions::ActionSchema in JSON, which is how one travels.

There is one concept here, in two representations. An ActionSchema is the live object: it holds a typeinfo, which is an opaque language handle this layer never dereferences, and autofills, which are receiver-owned default values. Neither can cross a wire: one is a pointer, and ActionRegistry::Copy clears the other. Schemas sent to another process use the textual form defined here.

The document is a11.actions/v1: a format tag and an actions array. Each entry is one schema, with typeinfo replaced by the port's json_schema – the port's json_schema, and autofills replaced by an autofilled flag. Autofill values remain local while their presence is included in the schema.

One field in an entry is not part of the schema, and cannot be: runnable, which says whether the side answering holds a handler. The same schema is runnable here and schema-only there, and that difference is what Flow reads to choose run over call. It is the registry's annotation on a schema rather than a property of one.

Why one document. Tool bridges, Flow tooling, editor integrations, and model adapters consume this shared superset of ActionInfo, with the same port keys and omit-when-default conventions.

The legacy user_facing narration flag is absent. Narration uses the reserved log port, which every action has and no schema declares. Readers accept and discard the legacy flag.

What is omitted when it is the default. required and unary are written only when true, and a port's json_schema only when it says more than {"type": "object"} – which is what an adapter shows a model for a port carrying no schema at all, so writing it out states nothing. Every reader here fills in a11::actions::ActionPortSchema's own defaults, so what is absent and what is spelled out mean the same thing.

Warning

Those defaults are this document's, not A11's everywhere. a11::flow::catalogue::PortInfo defaults unary to true and its codec omits the field when true – the opposite convention, for a different format. A port entry moved between the two documents without going through a struct turns every streaming port into a unary one, or the reverse.