{
	"$schema": "https://json-schema.org/draft/2020-12/schema",
	"$id": "forstio/docs_oos/entity.schema.json",
	"title": "forstio out of source api entity",
	"description": "One file per entity, written by hand instead of derived from doxygen. A primary template and each of its specializations are separate files with their own id; the primary links the specializations, which the tree renders as a sublist underneath it. The generator collects every file under docs_oos/data into one map keyed by id, which is the shape the rst templates consume.",
	"type": "object",
	"required": ["format", "id", "kind", "name", "namespace", "header"],
	"additionalProperties": false,
	"properties": {
		"format": {
			"const": 1
		},
		"id": {
			"type": "string",
			"pattern": "^[a-z0-9_]+(-[a-z0-9_]+)*$",
			"description": "Stable identifier. Becomes the rst file name, the label and the :ref: target, so it replaces the doxygen refid. Convention: namespace and name joined by a dash, with a slug for a specialization, e.g. saw-data_server and saw-data_server-loopback."
		},
		"kind": {
			"enum": ["class", "struct", "alias", "function", "variable", "enum", "concept", "namespace", "macro"]
		},
		"name": {
			"type": "string",
			"description": "Unqualified name without namespace and without template arguments. A specialization carries the same name as its primary."
		},
		"namespace": {
			"type": "string",
			"description": "Where it lives, e.g. saw or saw::rmt. Kept apart from the name so the heading stays readable and the namespace can still be shown."
		},
		"module": {
			"type": "string",
			"description": "Module directory, e.g. remote."
		},
		"header": {
			"type": "string",
			"description": "Declaring header, relative to the repository root."
		},
		"brief_description": {
			"type": "string"
		},
		"detailed_description": {
			"$ref": "#/$defs/paragraphs"
		},
		"type": {
			"$ref": "#/$defs/type_tuple",
			"description": "Only for an alias, variable or function entity: the aliased type, the variable type, or the return type. A class has no type of its own."
		},
		"parameters": {
			"type": "array",
			"description": "Only for a function entity.",
			"items": {"$ref": "#/$defs/parameter"}
		},
		"templates": {
			"type": "array",
			"description": "Template parameters. A partial specialization lists the parameters it introduces, not the ones it binds.",
			"items": {"$ref": "#/$defs/template_parameter"}
		},
		"bases": {
			"type": "array",
			"description": "Base classes, for the few places which use inheritance. Entries are type tuples, so a base which is itself documented links.",
			"items": {"$ref": "#/$defs/type_tuple"}
		},
		"is_special": {
			"type": "boolean",
			"default": false,
			"description": "True on a specialization. The index skips these; they are reachable through their primary."
		},
		"specializes": {
			"type": "string",
			"description": "Only on a specialization: id of the primary."
		},
		"arguments": {
			"type": "array",
			"description": "Only on a specialization: the arguments it binds, in order, as written.",
			"items": {"type": "string"}
		},
		"specializations": {
			"type": "array",
			"description": "Only on a primary. Rendered as the sublist under the entity.",
			"items": {"$ref": "#/$defs/specialization_link"}
		},
		"aliases": {
			"type": "object",
			"description": "Member type aliases keyed by id. These carry weight here, e.g. DataServers or InterfaceT.",
			"additionalProperties": {"$ref": "#/$defs/alias"}
		},
		"attributes": {
			"type": "object",
			"description": "Data members keyed by id.",
			"additionalProperties": {"$ref": "#/$defs/attribute"}
		},
		"functions": {
			"type": "object",
			"description": "Member functions keyed by id. Overloads get distinct ids.",
			"additionalProperties": {"$ref": "#/$defs/function"}
		},
		"examples": {
			"type": "array",
			"description": "Usage examples for the entity as a whole.",
			"items": {"$ref": "#/$defs/example"}
		},
		"notes": {
			"type": "array",
			"description": "Remarks which don't belong to a single member.",
			"items": {"type": "string"}
		}
	},
	"$defs": {
		"example": {
			"type": "object",
			"required": ["code"],
			"additionalProperties": false,
			"properties": {
				"title": {"type": "string"},
				"language": {
					"type": "string",
					"default": "cpp",
					"description": "Rendered as the code block language."
				},
				"description": {"$ref": "#/$defs/paragraphs"},
				"code": {
					"type": "string",
					"description": "Source as a single string with newlines. Error handling may be left out for readability, but then the description has to say so."
				}
			}
		},
		"paragraphs": {
			"type": "array",
			"description": "A list of paragraphs. Each paragraph is a list of fragments: plain strings, or a reference object which renders as a link to another entity.",
			"items": {
				"type": "array",
				"items": {
					"oneOf": [
						{"type": "string"},
						{"$ref": "#/$defs/type_ref"}
					]
				}
			}
		},
		"type_ref": {
			"type": "object",
			"required": ["name", "id"],
			"additionalProperties": false,
			"properties": {
				"name": {"type": "string", "description": "Text to display."},
				"id": {"type": "string", "description": "id of the entity being linked."}
			}
		},
		"type_tuple": {
			"type": "array",
			"description": "A type as a sequence of fragments, so the parts which are entities link and the rest stays text.",
			"items": {
				"oneOf": [
					{"type": "string"},
					{"$ref": "#/$defs/type_ref"}
				]
			}
		},
		"parameter": {
			"type": "object",
			"required": ["name", "type"],
			"additionalProperties": false,
			"properties": {
				"name": {"type": "string"},
				"type": {"$ref": "#/$defs/type_tuple"},
				"default": {"type": "string"},
				"brief_description": {"type": "string"}
			}
		},
		"template_parameter": {
			"type": "object",
			"required": ["name", "kind"],
			"additionalProperties": false,
			"properties": {
				"name": {"type": "string"},
				"kind": {
					"enum": ["type", "non_type", "template"],
					"description": "type for class/typename, non_type for a value parameter such as uint64_t N or string_literal Lit."
				},
				"type": {
					"type": "string",
					"description": "Required for non_type, e.g. uint64_t or string_literal."
				},
				"pack": {"type": "boolean", "default": false},
				"default": {"type": "string", "description": "Default argument as written."},
				"brief_description": {"type": "string"}
			}
		},
		"specialization_link": {
			"type": "object",
			"required": ["name", "id"],
			"additionalProperties": false,
			"properties": {
				"name": {
					"type": "string",
					"description": "Specialized name as it should read in the sublist, e.g. data_server< Schema, Encoding, rmt::Loopback >."
				},
				"id": {"type": "string"},
				"brief_description": {
					"type": "string",
					"description": "One line, so the sublist says what the specialization is for without opening it."
				}
			}
		},
		"alias": {
			"type": "object",
			"required": ["id", "name", "type"],
			"additionalProperties": false,
			"properties": {
				"id": {"type": "string"},
				"name": {"type": "string"},
				"type": {"$ref": "#/$defs/type_tuple"},
				"visibility": {"enum": ["public", "protected", "private"], "default": "public"},
				"brief_description": {"type": "string"},
				"detailed_description": {"$ref": "#/$defs/paragraphs"}
			}
		},
		"attribute": {
			"type": "object",
			"required": ["id", "name", "type"],
			"additionalProperties": false,
			"properties": {
				"id": {"type": "string"},
				"name": {"type": "string"},
				"type": {"$ref": "#/$defs/type_tuple"},
				"visibility": {"enum": ["public", "protected", "private"], "default": "private"},
				"static": {"type": "boolean", "default": false},
				"const": {"type": "boolean", "default": false},
				"constexpr": {"type": "boolean", "default": false},
				"initializer": {"type": "string", "default": ""},
				"brief_description": {"type": "string"},
				"detailed_description": {"$ref": "#/$defs/paragraphs"}
			}
		},
		"function": {
			"type": "object",
			"required": ["id", "name", "type"],
			"additionalProperties": false,
			"properties": {
				"id": {"type": "string"},
				"name": {"type": "string"},
				"type": {
					"$ref": "#/$defs/type_tuple",
					"description": "Return type. Empty for constructors and destructors."
				},
				"templates": {
					"type": "array",
					"description": "Template parameters of the function itself, e.g. the string_literal naming an interface member.",
					"items": {"$ref": "#/$defs/template_parameter"}
				},
				"parameters": {
					"type": "array",
					"items": {"$ref": "#/$defs/parameter"}
				},
				"visibility": {"enum": ["public", "protected", "private"], "default": "public"},
				"static": {"type": "boolean", "default": false},
				"const": {"type": "boolean", "default": false},
				"virtual": {"type": "boolean", "default": false},
				"override": {"type": "boolean", "default": false},
				"brief_description": {"type": "string"},
				"detailed_description": {"$ref": "#/$defs/paragraphs"},
				"examples": {
					"type": "array",
					"description": "Usage examples for this member.",
					"items": {"$ref": "#/$defs/example"}
				}
			}
		}
	}
}