Rules
39 business rules described. A business rule is a condition the business imposes, with what it constrains and what happens when it is broken.
| Business rule | Severity | First line | Links |
|---|---|---|---|
| Conversion failed | warning | An office document could not be converted to PDF: timeout, size, corruption or missing converter. The document stays downloadable, without preview or extracted text. | 59 |
| Stale source | warning | A source or a note has not changed for longer than the configured threshold. The date comes from git and is always right. | 46 |
| Operation matching | warning | An operation note attaches to the operation imported from the contract of its API on three rungs, tried in order, the first that matches winning: the operation_id of the frontmatter against the operation identifier of the contract; the method and path pair (or port and the title for a SOAP operation) against the operation's; the title of the note in comparison form, spaces and punctuation ignored, against the operation title or its identifier. The note names its API in the api attribute or through a markdown link; a note that names none is a candidate for every API of its source that declares a contract. | 44 |
| Operation unmatched | warning | An operation note that names an API with an imported contract, in its api attribute or through a markdown link, and that none of the three rungs of the operation matching attaches to an operation of that contract. One of two things is true: the operation disappeared from the contract and the note describes something that no longer exists, or the note is ahead of the contract and describes an operation the next version will declare. The build cannot tell which, so the finding says both, and the author decides: retire the note or point it at the operation that replaced its own, or keep it with the operation_id to come until the contract catches up. A note that names no API is not reported: it is a candidate for every contract of its source and may describe an API without a contract. A note taken in an ambiguity is reported by the matching rule instead. | 37 |
| Cross-source link | warning | A markdown link leaves its source, with the <source>:<path> prefix or with a relative path that climbs above the source root into a sibling source, while inference.cross_source_links is off. The link is not recorded: the model keeps no relation between the two notes until the configuration allows links across sources, or the author links to a note of the same source. The linter in global scope reports the same finding from one repository when the link reaches a note of the published model and that model says it was built with cross-source links off; a link that leaves the source for a file that does not exist is a broken link once such links are allowed. | 34 |
| Unresolved reference | warning | A value of a reference-typed frontmatter attribute (reads, roles, rules, consumers, affects, broader among others) matches no note by identifier, by path relative to the source root or by exact title, or matches several notes by title. No link is recorded for that value; the other values of the attribute are unaffected. The fix is to write the identifier, the path or the exact title of an existing note, the identifier or the path when a title is shared: this repository names its roles by path, roles/publication/reader, because the glossary carries a term with the same title as one of them. A note found under a type the attribute does not accept is a relation outside the matrix, not an unresolved reference. | 31 |
| Ambiguous operation | warning | At the rung of the operation matching where a match is found, two operation notes claim the same operation imported from a contract, or one note matches several operations of its API. Nothing is attached: the finding names every candidate, the imported operation stays a separate entity with the properties of the contract only, and the other notes and operations of the API are matched as usual. The operation_id of exactly one operation in each note settles it; a note that names no API and matches several contracts of its source names its API in the api attribute. | 27 |
| Undefined term | warning | A recurring expression crosses the threshold without any note defining it. It has a keyword page built from its passages, but no definition. | 26 |
| Unreachable contract | warning | The contract an API note declares in its contract attribute, a URL or a path relative to the note, could not be fetched, read or parsed: the server answered with an error, the build ran without network access, the file is missing, or the document is neither an OpenAPI 3.x document in JSON or YAML nor a WSDL 1.1 or 2.0 document. No operation is imported from it, the note keeps the operations written by hand, and the build goes on; the API page has no imported operations until a later build reads the contract. A project whose contracts must be present raises the severity to error. | 23 |
| API without consumer | warning | An API has no consumer, declared or inferred: no attribute, no section, no mention in another note. | 22 |
| Consumer mismatch | warning | An API declares a consumer that never cites it, or a note cites an API that does not list it. One of the two is out of date. A declared consumer is an identifier, written in full or relative to the source of the API note; a note listed under the ## Consumers section of the API note is declared too; a note cites the API when a serves link between the two was read in that note, the API's own consumers attribute and ## Consumers section being declarations rather than citations. The attribute asks for the reconciliation: an API note without it is left to the API without consumer check. | 22 |
| Missing application | warning | An entity resolves to no application: none on the source, none in a rule, none in frontmatter. | 21 |
| Unknown type | warning | The type cascade gave a note a type that neither the default profile nor the project profile declares: a source type, a typing rule or a frontmatter type names a slug that does not exist. The note is kept and treated as a document, and its type origin records where the unknown slug came from, so that the site shows it. The fix is a type of the profile, a declaration in the project profile, or a correction of the rule or the frontmatter. | 21 |
| Disabled plugin | warning | A declared plugin needs a system tool that is not installed on the machine that builds: the build ran the detection command of every system dependency of the manifest, one answered nothing, and the plugin was not registered, so that none of its readers, converters, sources, inference methods, checks, projections or components took part in the build. An optional dependency yields the same finding as info and the plugin stays registered. The fix is the tool on the PATH of the build, or the plugin removed from plugins:; a project whose conversions must run raises the severity to error. | 20 |
| Unknown application | warning | The application cascade (the application of the source, the set.application of a typing rule, the frontmatter application) produced an identifier that applications: does not declare. The value is kept as written on the entity and the finding says where it came from; nothing composes the entity into a declared application. Distinct from the missing application, where the cascade produced nothing at all. | 20 |
| Unknown attribute | warning | A frontmatter key is declared neither by the type of the note nor among the common attributes of the profile. The value is kept as written in the model and shown in the side panel of the page, but nothing interprets it: it produces no relation and no typed display. Most often a typo in a key, or an attribute the project profile has yet to declare. | 19 |
| Unknown domain | warning | A frontmatter domain names no domain declared under domains: of the configuration, by its identifier or by its identifier path. The frontmatter wins over the folders and the globs, so the value is kept as written on the entity and the site shows what the author meant, but nothing files the note under a declared domain. Distinct from the unclassified domain, where the note names nothing, sits under no claimed folder and matches no glob. | 18 |
| Unusable pseudonymisation dictionary | warning | The pseudonymisation dictionary the configuration names is missing, is not valid YAML or does not match its schema. While pseudonymisation is disabled the finding is a warning and the build goes on; when it is enabled the finding is raised as an error, the build fails and every transcript is withheld from the output, because a site built without the dictionary would publish every name as written. | 18 |
| Transcript withheld | warning | A transcript was kept out of the site because its reader cannot write it back with the pseudonyms: the page of the meeting shows neither the transcript nor its download, and its text enters neither the model nor the search index. The raw file is never published. | 16 |
| Unreachable source | warning | A declared source could not be fetched or read: wrong URL, unknown ref, missing credentials, a missing local path, or a faulty concordance-lint.yaml in the repository, which the build refuses to read differently from its linter. The build goes on without it; nothing from that source enters the model until it comes back. | 14 |
20 rules of 21 — pagination by twenty. The Links column counts the related pages, which brings the most central rules of the journey to the top.