{ "$schema": "http://json-schema.org/draft-07/schema#", "$id": "https://docs.octo.ad/schema/topic-types.json", "title": "OCTOPUS docs topic types", "description": "Front matter of every docs.octo.ad page validates against types[]. Each entry is the JSON Schema generated from the docs content model (DITA 2.0 topic types mapped to schema.org) composed with the build-side checks: required metadata, facet values from the controlled lists, and item schemas for arrays.", "facets": { "audience": [ "operator", "team lead", "admin", "developer", "tenant admin" ], "surface": [ "the Desk", "Slack", "meetings", "email", "phone and MCP" ], "ladderRung": [ "rule", "replay", "local judge", "frontier model", "person" ], "productArea": [ "company memory", "the decision record", "the decision ladder", "the Desk", "ingestion", "agents at work", "a copy for every team", "integrations" ], "tenancyScope": [ "platform", "team copy" ] }, "types": { "concept": { "allOf": [ { "$schema": "http://json-schema.org/draft-07/schema#", "description": "DITA 2.0 base topic. Used only when no typed topic fits. Every published topic is self-contained, carries a stable id equal to its URL slug, a shortdesc and an audience. Page graph: WebSite, WebPage, BreadcrumbList, dateModified, isPartOf to the WebSite; main entity TechArticle.", "$comment": "schema.org: https://schema.org/TechArticle", "type": "object", "properties": { "prolog": { "description": "Container for topic metadata. Has no schema.org counterpart itself; each child maps to a property of the main entity.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "object", "properties": { "critdates": { "description": "Container for the critical dates of a topic. No schema.org counterpart itself; created and revised map to dates.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "object", "properties": { "created": { "description": "Date the topic was first published, ISO 8601.", "$comment": "schema.org: https://schema.org/datePublished", "type": "string" }, "revised": { "description": "Date the topic last changed, ISO 8601. Required on every publish.", "$comment": "schema.org: https://schema.org/dateModified", "type": "string" } } }, "author": { "description": "Who wrote the topic; default the docs team as an Organization.", "$comment": "schema.org: https://schema.org/author", "type": "string" }, "ladderRung": { "description": "PROPOSAL facet: the rung of the decision ladder the topic concerns, a value from the Ladder rung facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "keywords": { "description": "Keywords. Facet values are mirrored here, never carried here alone.", "$comment": "schema.org: https://schema.org/keywords", "type": "array" }, "surface": { "description": "PROPOSAL facet: the surface the topic concerns, a value from the Surface facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "audience": { "description": "Who the topic is for. A value from the Audience facet. Publish is refused when empty.", "$comment": "schema.org: https://schema.org/audience", "type": "string" }, "stableId": { "description": "Stable id of the topic, equal to its URL slug and to the JSON-LD @id. Never changes after first publish.", "$comment": "schema.org: https://schema.org/identifier", "type": "string" }, "canonicalUrl": { "description": "Canonical URL of the topic; also mainEntityOfPage and the HTML canonical link.", "$comment": "schema.org: https://schema.org/url", "type": "string" }, "prodinfo": { "description": "Product the topic is about, emitted as about a SoftwareApplication.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "productArea": { "description": "PROPOSAL facet: the product area, a value from the Product area facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "tenancyScope": { "description": "PROPOSAL facet: platform or team copy, a value from the Tenancy scope facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" } } }, "body": { "description": "Generic topic body, used only by the base topic type.", "$comment": "schema.org: https://schema.org/articleBody", "type": "string" }, "breadcrumb": { "description": "Breadcrumb trail of the page, emitted as a BreadcrumbList on every page.", "$comment": "schema.org: https://schema.org/breadcrumb", "type": "array" }, "shortdesc": { "description": "One or two sentences saying what the topic is for. Publish is refused when empty. Maps to description.", "$comment": "schema.org: https://schema.org/description", "type": "string" }, "title": { "description": "The topic title. Maps to headline on TechArticle and name on HowTo.", "$comment": "schema.org: https://schema.org/headline https://schema.org/name", "type": "string" }, "keyref": { "description": "Key reference resolved at publish; the key text is denormalised into the output. No schema.org target.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "string" }, "isPartOf": { "description": "The site the page belongs to; points to the WebSite @id. Chunks point to their topic.", "$comment": "schema.org: https://schema.org/isPartOf", "type": "string" }, "conref": { "description": "Content reference expanded at publish so every published topic is self-contained. No schema.org target; transclusion is not derivation.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "string" }, "relatedLinks": { "description": "Related topics. Reuse is a link, not transclusion, wherever an agent reads the topic.", "$comment": "schema.org: https://schema.org/relatedLink", "type": "array" } }, "required": [ "shortdesc", "title" ] }, { "type": "object", "required": [ "title", "shortdesc", "prolog" ], "properties": { "title": { "type": "string", "minLength": 1 }, "shortdesc": { "type": "string", "minLength": 1 }, "prolog": { "type": "object", "required": [ "audience", "stableId", "canonicalUrl", "critdates" ], "properties": { "audience": { "type": "string", "minLength": 1, "enum": [ "operator", "team lead", "admin", "developer", "tenant admin" ] }, "stableId": { "type": "string", "minLength": 1 }, "canonicalUrl": { "type": "string", "minLength": 1 }, "critdates": { "type": "object", "required": [ "revised" ], "properties": { "revised": { "type": "string", "minLength": 10 } } }, "keywords": { "type": "array", "items": { "type": "string" } }, "surface": { "type": "string", "enum": [ "the Desk", "Slack", "meetings", "email", "phone and MCP" ] }, "ladderRung": { "type": "string", "enum": [ "rule", "replay", "local judge", "frontier model", "person" ] }, "productArea": { "type": "string", "enum": [ "company memory", "the decision record", "the decision ladder", "the Desk", "ingestion", "agents at work", "a copy for every team", "integrations" ] }, "tenancyScope": { "type": "string", "enum": [ "platform", "team copy" ] } } } } }, { "description": "DITA 2.0 concept topic: explains what something is or why it matters. Main entity TechArticle.", "$comment": "schema.org: https://schema.org/TechArticle", "type": "object", "properties": { "conbody": { "description": "Concept body text.", "$comment": "schema.org: https://schema.org/articleBody", "type": "string" } } } ] }, "task": { "allOf": [ { "$schema": "http://json-schema.org/draft-07/schema#", "description": "DITA 2.0 base topic. Used only when no typed topic fits. Every published topic is self-contained, carries a stable id equal to its URL slug, a shortdesc and an audience. Page graph: WebSite, WebPage, BreadcrumbList, dateModified, isPartOf to the WebSite; main entity TechArticle.", "$comment": "schema.org: https://schema.org/TechArticle", "type": "object", "properties": { "prolog": { "description": "Container for topic metadata. Has no schema.org counterpart itself; each child maps to a property of the main entity.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "object", "properties": { "critdates": { "description": "Container for the critical dates of a topic. No schema.org counterpart itself; created and revised map to dates.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "object", "properties": { "created": { "description": "Date the topic was first published, ISO 8601.", "$comment": "schema.org: https://schema.org/datePublished", "type": "string" }, "revised": { "description": "Date the topic last changed, ISO 8601. Required on every publish.", "$comment": "schema.org: https://schema.org/dateModified", "type": "string" } } }, "author": { "description": "Who wrote the topic; default the docs team as an Organization.", "$comment": "schema.org: https://schema.org/author", "type": "string" }, "ladderRung": { "description": "PROPOSAL facet: the rung of the decision ladder the topic concerns, a value from the Ladder rung facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "keywords": { "description": "Keywords. Facet values are mirrored here, never carried here alone.", "$comment": "schema.org: https://schema.org/keywords", "type": "array" }, "surface": { "description": "PROPOSAL facet: the surface the topic concerns, a value from the Surface facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "audience": { "description": "Who the topic is for. A value from the Audience facet. Publish is refused when empty.", "$comment": "schema.org: https://schema.org/audience", "type": "string" }, "stableId": { "description": "Stable id of the topic, equal to its URL slug and to the JSON-LD @id. Never changes after first publish.", "$comment": "schema.org: https://schema.org/identifier", "type": "string" }, "canonicalUrl": { "description": "Canonical URL of the topic; also mainEntityOfPage and the HTML canonical link.", "$comment": "schema.org: https://schema.org/url", "type": "string" }, "prodinfo": { "description": "Product the topic is about, emitted as about a SoftwareApplication.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "productArea": { "description": "PROPOSAL facet: the product area, a value from the Product area facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "tenancyScope": { "description": "PROPOSAL facet: platform or team copy, a value from the Tenancy scope facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" } } }, "body": { "description": "Generic topic body, used only by the base topic type.", "$comment": "schema.org: https://schema.org/articleBody", "type": "string" }, "breadcrumb": { "description": "Breadcrumb trail of the page, emitted as a BreadcrumbList on every page.", "$comment": "schema.org: https://schema.org/breadcrumb", "type": "array" }, "shortdesc": { "description": "One or two sentences saying what the topic is for. Publish is refused when empty. Maps to description.", "$comment": "schema.org: https://schema.org/description", "type": "string" }, "title": { "description": "The topic title. Maps to headline on TechArticle and name on HowTo.", "$comment": "schema.org: https://schema.org/headline https://schema.org/name", "type": "string" }, "keyref": { "description": "Key reference resolved at publish; the key text is denormalised into the output. No schema.org target.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "string" }, "isPartOf": { "description": "The site the page belongs to; points to the WebSite @id. Chunks point to their topic.", "$comment": "schema.org: https://schema.org/isPartOf", "type": "string" }, "conref": { "description": "Content reference expanded at publish so every published topic is self-contained. No schema.org target; transclusion is not derivation.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "string" }, "relatedLinks": { "description": "Related topics. Reuse is a link, not transclusion, wherever an agent reads the topic.", "$comment": "schema.org: https://schema.org/relatedLink", "type": "array" } }, "required": [ "shortdesc", "title" ] }, { "type": "object", "required": [ "title", "shortdesc", "prolog" ], "properties": { "title": { "type": "string", "minLength": 1 }, "shortdesc": { "type": "string", "minLength": 1 }, "prolog": { "type": "object", "required": [ "audience", "stableId", "canonicalUrl", "critdates" ], "properties": { "audience": { "type": "string", "minLength": 1, "enum": [ "operator", "team lead", "admin", "developer", "tenant admin" ] }, "stableId": { "type": "string", "minLength": 1 }, "canonicalUrl": { "type": "string", "minLength": 1 }, "critdates": { "type": "object", "required": [ "revised" ], "properties": { "revised": { "type": "string", "minLength": 10 } } }, "keywords": { "type": "array", "items": { "type": "string" } }, "surface": { "type": "string", "enum": [ "the Desk", "Slack", "meetings", "email", "phone and MCP" ] }, "ladderRung": { "type": "string", "enum": [ "rule", "replay", "local judge", "frontier model", "person" ] }, "productArea": { "type": "string", "enum": [ "company memory", "the decision record", "the decision ladder", "the Desk", "ingestion", "agents at work", "a copy for every team", "integrations" ] }, "tenancyScope": { "type": "string", "enum": [ "platform", "team copy" ] } } } } }, { "description": "DITA 2.0 task topic: one goal-oriented procedure. Dual typed HowTo plus TechArticle; HowTo only where the page is an honest procedure. Tutorials are tasks with a facet, not a separate type.", "$comment": "schema.org: https://schema.org/HowTo https://schema.org/TechArticle", "type": "object", "properties": { "taskbody": { "description": "Task body: prereq, context, steps, result, postreq.", "$comment": "schema.org: https://schema.org/articleBody", "type": "object", "properties": { "steps": { "description": "Ordered steps. In DITA 2.0 nested steps sit inside a step; there is no substeps element.", "$comment": "schema.org: https://schema.org/step", "type": "array", "properties": { "step": { "description": "One step of a task.", "$comment": "schema.org: https://schema.org/HowToStep", "type": "object", "properties": { "info": { "description": "Extra information for a step.", "$comment": "schema.org: https://schema.org/HowToTip", "type": "string" }, "stepresult": { "description": "What the reader sees after a step. Lossy: no schema.org property, carried as step text.", "$comment": "schema.org: https://schema.org/text", "type": "string" }, "cmd": { "description": "The action the reader takes in a step.", "$comment": "schema.org: https://schema.org/HowToDirection", "type": "string" }, "steps": { "$ref": "#/properties/taskbody/properties/steps" } } } } }, "context": { "description": "Why and when to do the task.", "$comment": "schema.org: https://schema.org/articleBody", "type": "string" }, "prereq": { "description": "What must be true or installed before the task.", "$comment": "schema.org: https://schema.org/dependencies", "type": "string" }, "postreq": { "description": "What to do after the task. Lossy: no schema.org property, carried as text.", "$comment": "schema.org: https://schema.org/text", "type": "string" }, "result": { "description": "What the reader has when the task is done.", "$comment": "schema.org: https://schema.org/yield", "type": "string" } } } } }, { "type": "object", "required": [ "taskbody" ], "properties": { "taskbody": { "type": "object", "required": [ "steps" ], "properties": { "steps": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "cmd" ], "properties": { "cmd": { "type": "string", "minLength": 1 } } } } } } } } ] }, "reference": { "allOf": [ { "$schema": "http://json-schema.org/draft-07/schema#", "description": "DITA 2.0 base topic. Used only when no typed topic fits. Every published topic is self-contained, carries a stable id equal to its URL slug, a shortdesc and an audience. Page graph: WebSite, WebPage, BreadcrumbList, dateModified, isPartOf to the WebSite; main entity TechArticle.", "$comment": "schema.org: https://schema.org/TechArticle", "type": "object", "properties": { "prolog": { "description": "Container for topic metadata. Has no schema.org counterpart itself; each child maps to a property of the main entity.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "object", "properties": { "critdates": { "description": "Container for the critical dates of a topic. No schema.org counterpart itself; created and revised map to dates.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "object", "properties": { "created": { "description": "Date the topic was first published, ISO 8601.", "$comment": "schema.org: https://schema.org/datePublished", "type": "string" }, "revised": { "description": "Date the topic last changed, ISO 8601. Required on every publish.", "$comment": "schema.org: https://schema.org/dateModified", "type": "string" } } }, "author": { "description": "Who wrote the topic; default the docs team as an Organization.", "$comment": "schema.org: https://schema.org/author", "type": "string" }, "ladderRung": { "description": "PROPOSAL facet: the rung of the decision ladder the topic concerns, a value from the Ladder rung facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "keywords": { "description": "Keywords. Facet values are mirrored here, never carried here alone.", "$comment": "schema.org: https://schema.org/keywords", "type": "array" }, "surface": { "description": "PROPOSAL facet: the surface the topic concerns, a value from the Surface facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "audience": { "description": "Who the topic is for. A value from the Audience facet. Publish is refused when empty.", "$comment": "schema.org: https://schema.org/audience", "type": "string" }, "stableId": { "description": "Stable id of the topic, equal to its URL slug and to the JSON-LD @id. Never changes after first publish.", "$comment": "schema.org: https://schema.org/identifier", "type": "string" }, "canonicalUrl": { "description": "Canonical URL of the topic; also mainEntityOfPage and the HTML canonical link.", "$comment": "schema.org: https://schema.org/url", "type": "string" }, "prodinfo": { "description": "Product the topic is about, emitted as about a SoftwareApplication.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "productArea": { "description": "PROPOSAL facet: the product area, a value from the Product area facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "tenancyScope": { "description": "PROPOSAL facet: platform or team copy, a value from the Tenancy scope facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" } } }, "body": { "description": "Generic topic body, used only by the base topic type.", "$comment": "schema.org: https://schema.org/articleBody", "type": "string" }, "breadcrumb": { "description": "Breadcrumb trail of the page, emitted as a BreadcrumbList on every page.", "$comment": "schema.org: https://schema.org/breadcrumb", "type": "array" }, "shortdesc": { "description": "One or two sentences saying what the topic is for. Publish is refused when empty. Maps to description.", "$comment": "schema.org: https://schema.org/description", "type": "string" }, "title": { "description": "The topic title. Maps to headline on TechArticle and name on HowTo.", "$comment": "schema.org: https://schema.org/headline https://schema.org/name", "type": "string" }, "keyref": { "description": "Key reference resolved at publish; the key text is denormalised into the output. No schema.org target.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "string" }, "isPartOf": { "description": "The site the page belongs to; points to the WebSite @id. Chunks point to their topic.", "$comment": "schema.org: https://schema.org/isPartOf", "type": "string" }, "conref": { "description": "Content reference expanded at publish so every published topic is self-contained. No schema.org target; transclusion is not derivation.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "string" }, "relatedLinks": { "description": "Related topics. Reuse is a link, not transclusion, wherever an agent reads the topic.", "$comment": "schema.org: https://schema.org/relatedLink", "type": "array" } }, "required": [ "shortdesc", "title" ] }, { "type": "object", "required": [ "title", "shortdesc", "prolog" ], "properties": { "title": { "type": "string", "minLength": 1 }, "shortdesc": { "type": "string", "minLength": 1 }, "prolog": { "type": "object", "required": [ "audience", "stableId", "canonicalUrl", "critdates" ], "properties": { "audience": { "type": "string", "minLength": 1, "enum": [ "operator", "team lead", "admin", "developer", "tenant admin" ] }, "stableId": { "type": "string", "minLength": 1 }, "canonicalUrl": { "type": "string", "minLength": 1 }, "critdates": { "type": "object", "required": [ "revised" ], "properties": { "revised": { "type": "string", "minLength": 10 } } }, "keywords": { "type": "array", "items": { "type": "string" } }, "surface": { "type": "string", "enum": [ "the Desk", "Slack", "meetings", "email", "phone and MCP" ] }, "ladderRung": { "type": "string", "enum": [ "rule", "replay", "local judge", "frontier model", "person" ] }, "productArea": { "type": "string", "enum": [ "company memory", "the decision record", "the decision ladder", "the Desk", "ingestion", "agents at work", "a copy for every team", "integrations" ] }, "tenancyScope": { "type": "string", "enum": [ "platform", "team copy" ] } } } } }, { "description": "DITA 2.0 reference topic: lookup facts such as tool lists, settings and glossaries of fields. Main entity TechArticle; APIReference for pages generated from an API description.", "$comment": "schema.org: https://schema.org/TechArticle", "type": "object", "properties": { "refbody": { "description": "Reference body.", "$comment": "schema.org: https://schema.org/articleBody", "type": "object", "properties": { "section": { "description": "A titled section of a reference or concept, with its own chunk anchor.", "$comment": "schema.org: https://schema.org/hasPart", "type": "object" }, "properties": { "description": "Property table of a reference topic: name, value, description per row.", "$comment": "schema.org: https://schema.org/additionalProperty", "type": "array" } } } } } ] }, "troubleshooting": { "allOf": [ { "$schema": "http://json-schema.org/draft-07/schema#", "description": "DITA 2.0 base topic. Used only when no typed topic fits. Every published topic is self-contained, carries a stable id equal to its URL slug, a shortdesc and an audience. Page graph: WebSite, WebPage, BreadcrumbList, dateModified, isPartOf to the WebSite; main entity TechArticle.", "$comment": "schema.org: https://schema.org/TechArticle", "type": "object", "properties": { "prolog": { "description": "Container for topic metadata. Has no schema.org counterpart itself; each child maps to a property of the main entity.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "object", "properties": { "critdates": { "description": "Container for the critical dates of a topic. No schema.org counterpart itself; created and revised map to dates.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "object", "properties": { "created": { "description": "Date the topic was first published, ISO 8601.", "$comment": "schema.org: https://schema.org/datePublished", "type": "string" }, "revised": { "description": "Date the topic last changed, ISO 8601. Required on every publish.", "$comment": "schema.org: https://schema.org/dateModified", "type": "string" } } }, "author": { "description": "Who wrote the topic; default the docs team as an Organization.", "$comment": "schema.org: https://schema.org/author", "type": "string" }, "ladderRung": { "description": "PROPOSAL facet: the rung of the decision ladder the topic concerns, a value from the Ladder rung facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "keywords": { "description": "Keywords. Facet values are mirrored here, never carried here alone.", "$comment": "schema.org: https://schema.org/keywords", "type": "array" }, "surface": { "description": "PROPOSAL facet: the surface the topic concerns, a value from the Surface facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "audience": { "description": "Who the topic is for. A value from the Audience facet. Publish is refused when empty.", "$comment": "schema.org: https://schema.org/audience", "type": "string" }, "stableId": { "description": "Stable id of the topic, equal to its URL slug and to the JSON-LD @id. Never changes after first publish.", "$comment": "schema.org: https://schema.org/identifier", "type": "string" }, "canonicalUrl": { "description": "Canonical URL of the topic; also mainEntityOfPage and the HTML canonical link.", "$comment": "schema.org: https://schema.org/url", "type": "string" }, "prodinfo": { "description": "Product the topic is about, emitted as about a SoftwareApplication.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "productArea": { "description": "PROPOSAL facet: the product area, a value from the Product area facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "tenancyScope": { "description": "PROPOSAL facet: platform or team copy, a value from the Tenancy scope facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" } } }, "body": { "description": "Generic topic body, used only by the base topic type.", "$comment": "schema.org: https://schema.org/articleBody", "type": "string" }, "breadcrumb": { "description": "Breadcrumb trail of the page, emitted as a BreadcrumbList on every page.", "$comment": "schema.org: https://schema.org/breadcrumb", "type": "array" }, "shortdesc": { "description": "One or two sentences saying what the topic is for. Publish is refused when empty. Maps to description.", "$comment": "schema.org: https://schema.org/description", "type": "string" }, "title": { "description": "The topic title. Maps to headline on TechArticle and name on HowTo.", "$comment": "schema.org: https://schema.org/headline https://schema.org/name", "type": "string" }, "keyref": { "description": "Key reference resolved at publish; the key text is denormalised into the output. No schema.org target.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "string" }, "isPartOf": { "description": "The site the page belongs to; points to the WebSite @id. Chunks point to their topic.", "$comment": "schema.org: https://schema.org/isPartOf", "type": "string" }, "conref": { "description": "Content reference expanded at publish so every published topic is self-contained. No schema.org target; transclusion is not derivation.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "string" }, "relatedLinks": { "description": "Related topics. Reuse is a link, not transclusion, wherever an agent reads the topic.", "$comment": "schema.org: https://schema.org/relatedLink", "type": "array" } }, "required": [ "shortdesc", "title" ] }, { "type": "object", "required": [ "title", "shortdesc", "prolog" ], "properties": { "title": { "type": "string", "minLength": 1 }, "shortdesc": { "type": "string", "minLength": 1 }, "prolog": { "type": "object", "required": [ "audience", "stableId", "canonicalUrl", "critdates" ], "properties": { "audience": { "type": "string", "minLength": 1, "enum": [ "operator", "team lead", "admin", "developer", "tenant admin" ] }, "stableId": { "type": "string", "minLength": 1 }, "canonicalUrl": { "type": "string", "minLength": 1 }, "critdates": { "type": "object", "required": [ "revised" ], "properties": { "revised": { "type": "string", "minLength": 10 } } }, "keywords": { "type": "array", "items": { "type": "string" } }, "surface": { "type": "string", "enum": [ "the Desk", "Slack", "meetings", "email", "phone and MCP" ] }, "ladderRung": { "type": "string", "enum": [ "rule", "replay", "local judge", "frontier model", "person" ] }, "productArea": { "type": "string", "enum": [ "company memory", "the decision record", "the decision ladder", "the Desk", "ingestion", "agents at work", "a copy for every team", "integrations" ] }, "tenancyScope": { "type": "string", "enum": [ "platform", "team copy" ] } } } } }, { "description": "DITA 2.0 troubleshooting topic: condition, diagnostics (general and steps), then cause and remedy in any combination. Main entity TechArticle; optional HowTo for remedy steps; QAPage only for true question and answer content.", "$comment": "schema.org: https://schema.org/TechArticle", "type": "object", "properties": { "troublebody": { "description": "Troubleshooting body: condition, diagnostics, troubleSolution.", "$comment": "schema.org: https://schema.org/articleBody", "type": "object", "properties": { "diagnostics": { "description": "DITA 2.0 diagnostics: general and or step-wise checks to find the cause.", "$comment": "schema.org: https://schema.org/articleBody", "type": "object", "properties": { "diagnosticsSteps": { "description": "Diagnostic steps.", "$comment": "schema.org: https://schema.org/step", "type": "array", "properties": { "step": { "description": "One step of a task.", "$comment": "schema.org: https://schema.org/HowToStep", "type": "object", "properties": { "info": { "description": "Extra information for a step.", "$comment": "schema.org: https://schema.org/HowToTip", "type": "string" }, "stepresult": { "description": "What the reader sees after a step. Lossy: no schema.org property, carried as step text.", "$comment": "schema.org: https://schema.org/text", "type": "string" }, "cmd": { "description": "The action the reader takes in a step.", "$comment": "schema.org: https://schema.org/HowToDirection", "type": "string" }, "steps": { "description": "Ordered steps. In DITA 2.0 nested steps sit inside a step; there is no substeps element.", "$comment": "schema.org: https://schema.org/step", "type": "array", "properties": { "step": { "$ref": "#/properties/troublebody/properties/diagnostics/properties/diagnosticsSteps/properties/step" } } } } } } }, "diagnosticsGeneral": { "description": "General diagnostic information.", "$comment": "schema.org: https://schema.org/articleBody", "type": "string" } } }, "condition": { "description": "The problem the reader sees.", "$comment": "schema.org: https://schema.org/abstract", "type": "string" }, "troubleSolution": { "description": "A cause and remedy pair or other combination.", "$comment": "schema.org: https://schema.org/hasPart", "type": "object", "properties": { "remedy": { "description": "How to fix the condition; its steps may be emitted as an optional HowTo.", "$comment": "schema.org: https://schema.org/HowTo", "type": "object", "properties": { "steps": { "$ref": "#/properties/troublebody/properties/diagnostics/properties/diagnosticsSteps/properties/step/properties/steps" } } }, "cause": { "description": "Why the condition happens. No schema.org property; unbound.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "string" } } } } } } }, { "type": "object", "required": [ "troublebody" ], "properties": { "troublebody": { "type": "object", "required": [ "condition" ], "properties": { "condition": { "type": "string", "minLength": 1 } } } } } ] }, "map": { "allOf": [ { "$schema": "http://json-schema.org/draft-07/schema#", "description": "DITA 2.0 base topic. Used only when no typed topic fits. Every published topic is self-contained, carries a stable id equal to its URL slug, a shortdesc and an audience. Page graph: WebSite, WebPage, BreadcrumbList, dateModified, isPartOf to the WebSite; main entity TechArticle.", "$comment": "schema.org: https://schema.org/TechArticle", "type": "object", "properties": { "prolog": { "description": "Container for topic metadata. Has no schema.org counterpart itself; each child maps to a property of the main entity.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "object", "properties": { "critdates": { "description": "Container for the critical dates of a topic. No schema.org counterpart itself; created and revised map to dates.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "object", "properties": { "created": { "description": "Date the topic was first published, ISO 8601.", "$comment": "schema.org: https://schema.org/datePublished", "type": "string" }, "revised": { "description": "Date the topic last changed, ISO 8601. Required on every publish.", "$comment": "schema.org: https://schema.org/dateModified", "type": "string" } } }, "author": { "description": "Who wrote the topic; default the docs team as an Organization.", "$comment": "schema.org: https://schema.org/author", "type": "string" }, "ladderRung": { "description": "PROPOSAL facet: the rung of the decision ladder the topic concerns, a value from the Ladder rung facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "keywords": { "description": "Keywords. Facet values are mirrored here, never carried here alone.", "$comment": "schema.org: https://schema.org/keywords", "type": "array" }, "surface": { "description": "PROPOSAL facet: the surface the topic concerns, a value from the Surface facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "audience": { "description": "Who the topic is for. A value from the Audience facet. Publish is refused when empty.", "$comment": "schema.org: https://schema.org/audience", "type": "string" }, "stableId": { "description": "Stable id of the topic, equal to its URL slug and to the JSON-LD @id. Never changes after first publish.", "$comment": "schema.org: https://schema.org/identifier", "type": "string" }, "canonicalUrl": { "description": "Canonical URL of the topic; also mainEntityOfPage and the HTML canonical link.", "$comment": "schema.org: https://schema.org/url", "type": "string" }, "prodinfo": { "description": "Product the topic is about, emitted as about a SoftwareApplication.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "productArea": { "description": "PROPOSAL facet: the product area, a value from the Product area facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "tenancyScope": { "description": "PROPOSAL facet: platform or team copy, a value from the Tenancy scope facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" } } }, "body": { "description": "Generic topic body, used only by the base topic type.", "$comment": "schema.org: https://schema.org/articleBody", "type": "string" }, "breadcrumb": { "description": "Breadcrumb trail of the page, emitted as a BreadcrumbList on every page.", "$comment": "schema.org: https://schema.org/breadcrumb", "type": "array" }, "shortdesc": { "description": "One or two sentences saying what the topic is for. Publish is refused when empty. Maps to description.", "$comment": "schema.org: https://schema.org/description", "type": "string" }, "title": { "description": "The topic title. Maps to headline on TechArticle and name on HowTo.", "$comment": "schema.org: https://schema.org/headline https://schema.org/name", "type": "string" }, "keyref": { "description": "Key reference resolved at publish; the key text is denormalised into the output. No schema.org target.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "string" }, "isPartOf": { "description": "The site the page belongs to; points to the WebSite @id. Chunks point to their topic.", "$comment": "schema.org: https://schema.org/isPartOf", "type": "string" }, "conref": { "description": "Content reference expanded at publish so every published topic is self-contained. No schema.org target; transclusion is not derivation.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "string" }, "relatedLinks": { "description": "Related topics. Reuse is a link, not transclusion, wherever an agent reads the topic.", "$comment": "schema.org: https://schema.org/relatedLink", "type": "array" } }, "required": [ "shortdesc", "title" ] }, { "type": "object", "required": [ "title", "shortdesc", "prolog" ], "properties": { "title": { "type": "string", "minLength": 1 }, "shortdesc": { "type": "string", "minLength": 1 }, "prolog": { "type": "object", "required": [ "audience", "stableId", "canonicalUrl", "critdates" ], "properties": { "audience": { "type": "string", "minLength": 1, "enum": [ "operator", "team lead", "admin", "developer", "tenant admin" ] }, "stableId": { "type": "string", "minLength": 1 }, "canonicalUrl": { "type": "string", "minLength": 1 }, "critdates": { "type": "object", "required": [ "revised" ], "properties": { "revised": { "type": "string", "minLength": 10 } } }, "keywords": { "type": "array", "items": { "type": "string" } }, "surface": { "type": "string", "enum": [ "the Desk", "Slack", "meetings", "email", "phone and MCP" ] }, "ladderRung": { "type": "string", "enum": [ "rule", "replay", "local judge", "frontier model", "person" ] }, "productArea": { "type": "string", "enum": [ "company memory", "the decision record", "the decision ladder", "the Desk", "ingestion", "agents at work", "a copy for every team", "integrations" ] }, "tenancyScope": { "type": "string", "enum": [ "platform", "team copy" ] } } } } }, { "$schema": "http://json-schema.org/draft-07/schema#", "description": "DITA map: the site and its navigation tree. Emitted once as the WebSite node every page isPartOf.", "$comment": "schema.org: https://schema.org/WebSite", "type": "object", "properties": { "title": { "description": "The topic title. Maps to headline on TechArticle and name on HowTo.", "$comment": "schema.org: https://schema.org/headline https://schema.org/name", "type": "string" }, "topicrefs": { "description": "Top-level entries of the navigation tree.", "$comment": "schema.org: https://schema.org/hasPart", "type": "array", "items": { "$ref": "#/definitions/topicref" } } }, "required": [ "title" ], "definitions": { "topicref": { "type": "object", "properties": { "navtitle": { "type": "string" }, "href": { "type": "string" }, "childTopicrefs": { "type": "array", "items": { "$ref": "#/definitions/topicref" } } } } } } ] }, "decision-record": { "allOf": [ { "$schema": "http://json-schema.org/draft-07/schema#", "description": "DITA 2.0 base topic. Used only when no typed topic fits. Every published topic is self-contained, carries a stable id equal to its URL slug, a shortdesc and an audience. Page graph: WebSite, WebPage, BreadcrumbList, dateModified, isPartOf to the WebSite; main entity TechArticle.", "$comment": "schema.org: https://schema.org/TechArticle", "type": "object", "properties": { "prolog": { "description": "Container for topic metadata. Has no schema.org counterpart itself; each child maps to a property of the main entity.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "object", "properties": { "critdates": { "description": "Container for the critical dates of a topic. No schema.org counterpart itself; created and revised map to dates.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "object", "properties": { "created": { "description": "Date the topic was first published, ISO 8601.", "$comment": "schema.org: https://schema.org/datePublished", "type": "string" }, "revised": { "description": "Date the topic last changed, ISO 8601. Required on every publish.", "$comment": "schema.org: https://schema.org/dateModified", "type": "string" } } }, "author": { "description": "Who wrote the topic; default the docs team as an Organization.", "$comment": "schema.org: https://schema.org/author", "type": "string" }, "ladderRung": { "description": "PROPOSAL facet: the rung of the decision ladder the topic concerns, a value from the Ladder rung facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "keywords": { "description": "Keywords. Facet values are mirrored here, never carried here alone.", "$comment": "schema.org: https://schema.org/keywords", "type": "array" }, "surface": { "description": "PROPOSAL facet: the surface the topic concerns, a value from the Surface facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "audience": { "description": "Who the topic is for. A value from the Audience facet. Publish is refused when empty.", "$comment": "schema.org: https://schema.org/audience", "type": "string" }, "stableId": { "description": "Stable id of the topic, equal to its URL slug and to the JSON-LD @id. Never changes after first publish.", "$comment": "schema.org: https://schema.org/identifier", "type": "string" }, "canonicalUrl": { "description": "Canonical URL of the topic; also mainEntityOfPage and the HTML canonical link.", "$comment": "schema.org: https://schema.org/url", "type": "string" }, "prodinfo": { "description": "Product the topic is about, emitted as about a SoftwareApplication.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "productArea": { "description": "PROPOSAL facet: the product area, a value from the Product area facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "tenancyScope": { "description": "PROPOSAL facet: platform or team copy, a value from the Tenancy scope facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" } } }, "body": { "description": "Generic topic body, used only by the base topic type.", "$comment": "schema.org: https://schema.org/articleBody", "type": "string" }, "breadcrumb": { "description": "Breadcrumb trail of the page, emitted as a BreadcrumbList on every page.", "$comment": "schema.org: https://schema.org/breadcrumb", "type": "array" }, "shortdesc": { "description": "One or two sentences saying what the topic is for. Publish is refused when empty. Maps to description.", "$comment": "schema.org: https://schema.org/description", "type": "string" }, "title": { "description": "The topic title. Maps to headline on TechArticle and name on HowTo.", "$comment": "schema.org: https://schema.org/headline https://schema.org/name", "type": "string" }, "keyref": { "description": "Key reference resolved at publish; the key text is denormalised into the output. No schema.org target.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "string" }, "isPartOf": { "description": "The site the page belongs to; points to the WebSite @id. Chunks point to their topic.", "$comment": "schema.org: https://schema.org/isPartOf", "type": "string" }, "conref": { "description": "Content reference expanded at publish so every published topic is self-contained. No schema.org target; transclusion is not derivation.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "string" }, "relatedLinks": { "description": "Related topics. Reuse is a link, not transclusion, wherever an agent reads the topic.", "$comment": "schema.org: https://schema.org/relatedLink", "type": "array" } }, "required": [ "shortdesc", "title" ] }, { "type": "object", "required": [ "title", "shortdesc", "prolog" ], "properties": { "title": { "type": "string", "minLength": 1 }, "shortdesc": { "type": "string", "minLength": 1 }, "prolog": { "type": "object", "required": [ "audience", "stableId", "canonicalUrl", "critdates" ], "properties": { "audience": { "type": "string", "minLength": 1, "enum": [ "operator", "team lead", "admin", "developer", "tenant admin" ] }, "stableId": { "type": "string", "minLength": 1 }, "canonicalUrl": { "type": "string", "minLength": 1 }, "critdates": { "type": "object", "required": [ "revised" ], "properties": { "revised": { "type": "string", "minLength": 10 } } }, "keywords": { "type": "array", "items": { "type": "string" } }, "surface": { "type": "string", "enum": [ "the Desk", "Slack", "meetings", "email", "phone and MCP" ] }, "ladderRung": { "type": "string", "enum": [ "rule", "replay", "local judge", "frontier model", "person" ] }, "productArea": { "type": "string", "enum": [ "company memory", "the decision record", "the decision ladder", "the Desk", "ingestion", "agents at work", "a copy for every team", "integrations" ] }, "tenancyScope": { "type": "string", "enum": [ "platform", "team copy" ] } } } } }, { "description": "DITA 2.0 concept topic: explains what something is or why it matters. Main entity TechArticle.", "$comment": "schema.org: https://schema.org/TechArticle", "type": "object", "properties": { "conbody": { "description": "Concept body text.", "$comment": "schema.org: https://schema.org/articleBody", "type": "string" } } }, { "description": "PROPOSAL: decision record topic, a specialisation of concept for one recorded decision: context, decision, status, consequences. Main entity TechArticle. No schema.org decision type exists, so the mapping is lossy.", "$comment": "schema.org: https://schema.org/TechArticle", "type": "object", "properties": { "decisionContext": { "description": "PROPOSAL: the situation the decision answered. Lossy, carried as article body.", "$comment": "schema.org: https://schema.org/articleBody", "type": "string" }, "decisionOutcome": { "description": "PROPOSAL: what was decided. Lossy, carried as text.", "$comment": "schema.org: https://schema.org/text", "type": "string" }, "decisionStatus": { "description": "PROPOSAL: status of the decision.", "$comment": "schema.org: https://schema.org/creativeWorkStatus", "type": "string" }, "consequences": { "description": "PROPOSAL: what follows from the decision. Lossy, no schema.org property; unbound.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "string" } } } ] }, "release-note": { "allOf": [ { "$schema": "http://json-schema.org/draft-07/schema#", "description": "DITA 2.0 base topic. Used only when no typed topic fits. Every published topic is self-contained, carries a stable id equal to its URL slug, a shortdesc and an audience. Page graph: WebSite, WebPage, BreadcrumbList, dateModified, isPartOf to the WebSite; main entity TechArticle.", "$comment": "schema.org: https://schema.org/TechArticle", "type": "object", "properties": { "prolog": { "description": "Container for topic metadata. Has no schema.org counterpart itself; each child maps to a property of the main entity.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "object", "properties": { "critdates": { "description": "Container for the critical dates of a topic. No schema.org counterpart itself; created and revised map to dates.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "object", "properties": { "created": { "description": "Date the topic was first published, ISO 8601.", "$comment": "schema.org: https://schema.org/datePublished", "type": "string" }, "revised": { "description": "Date the topic last changed, ISO 8601. Required on every publish.", "$comment": "schema.org: https://schema.org/dateModified", "type": "string" } } }, "author": { "description": "Who wrote the topic; default the docs team as an Organization.", "$comment": "schema.org: https://schema.org/author", "type": "string" }, "ladderRung": { "description": "PROPOSAL facet: the rung of the decision ladder the topic concerns, a value from the Ladder rung facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "keywords": { "description": "Keywords. Facet values are mirrored here, never carried here alone.", "$comment": "schema.org: https://schema.org/keywords", "type": "array" }, "surface": { "description": "PROPOSAL facet: the surface the topic concerns, a value from the Surface facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "audience": { "description": "Who the topic is for. A value from the Audience facet. Publish is refused when empty.", "$comment": "schema.org: https://schema.org/audience", "type": "string" }, "stableId": { "description": "Stable id of the topic, equal to its URL slug and to the JSON-LD @id. Never changes after first publish.", "$comment": "schema.org: https://schema.org/identifier", "type": "string" }, "canonicalUrl": { "description": "Canonical URL of the topic; also mainEntityOfPage and the HTML canonical link.", "$comment": "schema.org: https://schema.org/url", "type": "string" }, "prodinfo": { "description": "Product the topic is about, emitted as about a SoftwareApplication.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "productArea": { "description": "PROPOSAL facet: the product area, a value from the Product area facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" }, "tenancyScope": { "description": "PROPOSAL facet: platform or team copy, a value from the Tenancy scope facet, emitted as about a DefinedTerm.", "$comment": "schema.org: https://schema.org/about", "type": "string" } } }, "body": { "description": "Generic topic body, used only by the base topic type.", "$comment": "schema.org: https://schema.org/articleBody", "type": "string" }, "breadcrumb": { "description": "Breadcrumb trail of the page, emitted as a BreadcrumbList on every page.", "$comment": "schema.org: https://schema.org/breadcrumb", "type": "array" }, "shortdesc": { "description": "One or two sentences saying what the topic is for. Publish is refused when empty. Maps to description.", "$comment": "schema.org: https://schema.org/description", "type": "string" }, "title": { "description": "The topic title. Maps to headline on TechArticle and name on HowTo.", "$comment": "schema.org: https://schema.org/headline https://schema.org/name", "type": "string" }, "keyref": { "description": "Key reference resolved at publish; the key text is denormalised into the output. No schema.org target.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "string" }, "isPartOf": { "description": "The site the page belongs to; points to the WebSite @id. Chunks point to their topic.", "$comment": "schema.org: https://schema.org/isPartOf", "type": "string" }, "conref": { "description": "Content reference expanded at publish so every published topic is self-contained. No schema.org target; transclusion is not derivation.", "$comment": "schema.org: none (see lossy-mappings.md)", "type": "string" }, "relatedLinks": { "description": "Related topics. Reuse is a link, not transclusion, wherever an agent reads the topic.", "$comment": "schema.org: https://schema.org/relatedLink", "type": "array" } }, "required": [ "shortdesc", "title" ] }, { "type": "object", "required": [ "title", "shortdesc", "prolog" ], "properties": { "title": { "type": "string", "minLength": 1 }, "shortdesc": { "type": "string", "minLength": 1 }, "prolog": { "type": "object", "required": [ "audience", "stableId", "canonicalUrl", "critdates" ], "properties": { "audience": { "type": "string", "minLength": 1, "enum": [ "operator", "team lead", "admin", "developer", "tenant admin" ] }, "stableId": { "type": "string", "minLength": 1 }, "canonicalUrl": { "type": "string", "minLength": 1 }, "critdates": { "type": "object", "required": [ "revised" ], "properties": { "revised": { "type": "string", "minLength": 10 } } }, "keywords": { "type": "array", "items": { "type": "string" } }, "surface": { "type": "string", "enum": [ "the Desk", "Slack", "meetings", "email", "phone and MCP" ] }, "ladderRung": { "type": "string", "enum": [ "rule", "replay", "local judge", "frontier model", "person" ] }, "productArea": { "type": "string", "enum": [ "company memory", "the decision record", "the decision ladder", "the Desk", "ingestion", "agents at work", "a copy for every team", "integrations" ] }, "tenancyScope": { "type": "string", "enum": [ "platform", "team copy" ] } } } } }, { "description": "PROPOSAL: release note topic, a specialisation of topic for one version delta. Main entity TechArticle; version as softwareVersion.", "$comment": "schema.org: https://schema.org/TechArticle", "type": "object", "properties": { "changeList": { "description": "The changes in the release.", "$comment": "schema.org: https://schema.org/releaseNotes", "type": "array" }, "softwareVersion": { "description": "Version the release note covers.", "$comment": "schema.org: https://schema.org/softwareVersion", "type": "string" } } } ] } }, "glossentry": { "$schema": "http://json-schema.org/draft-07/schema#", "description": "DITA 2.0 glossary entry: one term and its definition. Emitted as a DefinedTerm inDefinedTermSet of the glossary.", "$comment": "schema.org: https://schema.org/DefinedTerm", "type": "object", "properties": { "glossdef": { "description": "The definition.", "$comment": "schema.org: https://schema.org/description", "type": "string" }, "glossterm": { "description": "The term.", "$comment": "schema.org: https://schema.org/name", "type": "string" } }, "required": [ "glossdef", "glossterm" ] } }