@canonical/code-standards 0.1.0 → 0.1.1

package/data/tsdoc.ttl

@@ -1,42 +1,45 @@
-@prefix cso: <http://pragma.canonical.com/codestandards#> .
-@prefix cs: <http://pragma.canonical.com/codestandards/instances#> .
+@prefix cs: <http://pragma.canonical.com/codestandards#> .
 @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
 @prefix owl: <http://www.w3.org/2002/07/owl#> .
 @prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
 
 # TSDoc Category
-cs:TSDocCategory a cso:Category ;
+cs:TSDocCategory a cs:Category ;
     rdfs:label "TSDoc"@en ;
     rdfs:comment "Standards for TypeScript documentation comments — placement, layering, and tag usage."@en ;
-    cso:slug "tsdoc" .
+    cs:slug "tsdoc" .
 
 # Module Tag Location
-cs:TSDocModuleTagLocation a cso:CodeStandard ;
-    cso:name "tsdoc/module-tag-location" ;
-    cso:hasCategory cs:TSDocCategory ;
-    cso:description "The `@module` TSDoc tag must appear only on barrel files such as `index.ts`. Ordinary source files must document their exported API directly and must not use file-level `@module` tags." ;
-    cso:dos """
-(Do) Use `@module` on a barrel file that defines a package or folder-level API.
-```typescript
+cs:TSDocModuleTagLocation a cs:CodeStandard ;
+    cs:name "tsdoc/module-tag-location" ;
+    cs:hasCategory cs:TSDocCategory ;
+    cs:description "The `@module` TSDoc tag must appear only on barrel files such as `index.ts`. Ordinary source files must document their exported API directly and must not use file-level `@module` tags." ;
+    cs:do [
+        cs:description "Use `@module` on a barrel file that defines a package or folder-level API." ;
+        cs:language "typescript" ;
+        cs:code """
 /**
  * Public protocol API.
  * @module protocol
  */
 export { createRequest, matchResponse } from './index.js';
-```
-
-(Do) Document an ordinary source file at the exported symbol instead of using `@module`.
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Document an ordinary source file at the exported symbol instead of using `@module`." ;
+        cs:language "typescript" ;
+        cs:code """
 /** Build a completion item for a CSS variable. */
 export default function buildCompletionItem(name: string) {
   // ...
 }
-```
-""" ;
-    cso:donts """
-(Don't) Add `@module` to a single-purpose implementation file.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Add `@module` to a single-purpose implementation file." ;
+        cs:language "typescript" ;
+        cs:code """
 /**
  * Build a completion item.
  * @module providers/completions/buildCompletionItem
@@ -44,34 +47,39 @@ export default function buildCompletionItem(name: string) {
 export default function buildCompletionItem(name: string) {
   // ...
 }
-```
-
-(Don't) Use file-level `@module` tags as a substitute for export documentation.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use file-level `@module` tags as a substitute for export documentation." ;
+        cs:language "typescript" ;
+        cs:code """
 /** @module helpers/formatCurrency */
 export default function formatCurrency(value: number) {
   return `$${value}`;
 }
-```
-""" .
+    """
+    ] .
 
 # Documentation Layers
-cs:TSDocDocumentationLayers a cso:CodeStandard ;
-    cso:name "tsdoc/documentation-layers" ;
-    cso:hasCategory cs:TSDocCategory ;
-    cso:description "File-level and export-level TSDoc serve fundamentally different purposes. Export-level documentation describes *what the symbol does* — its API contract, parameters, return semantics, and side effects. File-level documentation describes *why this module exists* — its architectural role, the design invariants it upholds, and how its exports relate to each other. In single-export files the file exists solely to house that export, so file-level documentation is redundant; document only the exported symbol. In multi-export files, a file-level block is warranted when it explains the cohesion principle that binds the exports together — the reason they live in one file rather than separate ones." ;
-    cso:dos """
-(Do) In single-export files, document only at the export level — the API contract belongs on the symbol.
-```typescript
+cs:TSDocDocumentationLayers a cs:CodeStandard ;
+    cs:name "tsdoc/documentation-layers" ;
+    cs:hasCategory cs:TSDocCategory ;
+    cs:description "File-level and export-level TSDoc serve fundamentally different purposes. Export-level documentation describes *what the symbol does* — its API contract, parameters, return semantics, and side effects. File-level documentation describes *why this module exists* — its architectural role, the design invariants it upholds, and how its exports relate to each other. In single-export files the file exists solely to house that export, so file-level documentation is redundant; document only the exported symbol. In multi-export files, a file-level block is warranted when it explains the cohesion principle that binds the exports together — the reason they live in one file rather than separate ones." ;
+    cs:do [
+        cs:description "In single-export files, document only at the export level — the API contract belongs on the symbol." ;
+        cs:language "typescript" ;
+        cs:code """
 // resolveDefinition.ts — single export, no file-level block needed
 /** Resolve definition locations for a CSS custom property. */
 export default function resolveDefinition(cssVar: string, graph: TokenGraph) {
   // ...
 }
-```
-
-(Do) In multi-export files, use a file-level block to explain the module's architectural purpose — why these exports are grouped.
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "In multi-export files, use a file-level block to explain the module's architectural purpose — why these exports are grouped." ;
+        cs:language "typescript" ;
+        cs:code """
 // types.ts — multiple exports, file-level explains cohesion
 /**
  * Shared types for diagnostic rule modules.
@@ -82,10 +90,12 @@ export default function resolveDefinition(cssVar: string, graph: TokenGraph) {
 
 export interface UsageRuleContext { /* ... */ }
 export interface FileRuleContext { /* ... */ }
-```
-
-(Do) Use export-level TSDoc to describe the API contract: what the symbol does, its parameters, return value, and any side effects.
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Use export-level TSDoc to describe the API contract: what the symbol does, its parameters, return value, and any side effects." ;
+        cs:language "typescript" ;
+        cs:code """
 /**
  * Check: css/missing-fallback — var() without a fallback on an unregistered property.
  *
@@ -95,43 +105,49 @@ export interface FileRuleContext { /* ... */ }
 export default function checkMissingFallback(ctx: UsageRuleContext, results: Diagnostic[]) {
   // ...
 }
-```
-""" ;
-    cso:donts """
-(Don't) Add a file-level block in a single-export file that restates what the export-level doc already says.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Add a file-level block in a single-export file that restates what the export-level doc already says." ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: file-level repeats the export's own description
 /** Resolve definitions for CSS custom property usages. */
 
 /** Resolve definitions for CSS custom property usages. */
 export default function resolveDefinition() { /* ... */ }
-```
-
-(Don't) Use file-level docs to describe *what* an export does — that belongs on the export itself.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use file-level docs to describe *what* an export does — that belongs on the export itself." ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: file-level describes the function instead of the module's role
 /** Build a completion item for a CSS variable. */
 
 export default function buildCompletionItem(name: string) { /* ... */ }
-```
-
-(Don't) Omit file-level docs on multi-export modules where the grouping rationale is non-obvious.
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Omit file-level docs on multi-export modules where the grouping rationale is non-obvious." ;
+        cs:language "typescript" ;
+        cs:code """
 // Bad: reader cannot tell why these live together
 export function isCompletionRequest(req: WorkerRequest) { /* ... */ }
 export function isHoverRequest(req: WorkerRequest) { /* ... */ }
 export function isDiagnosticsRequest(req: WorkerRequest) { /* ... */ }
-```
-""" .
+    """
+    ] .
 
 # Self-Contained Documentation
-cs:TSDocSelfContained a cso:CodeStandard ;
-    cso:name "tsdoc/self-contained" ;
-    cso:hasCategory cs:TSDocCategory ;
-    cso:description "TSDoc comments must be self-contained — a reader should fully understand the documented symbol from its comment alone. External links (public specs, RFCs, GitHub issues) are allowed as supplementary references, but the comment itself must never depend on them for comprehension. If an external concept drives the implementation, distill the essential information into the comment." ;
-    cso:dos """
-(Do) Explain the concept inline so the reader needs nothing else:
-```typescript
+cs:TSDocSelfContained a cs:CodeStandard ;
+    cs:name "tsdoc/self-contained" ;
+    cs:hasCategory cs:TSDocCategory ;
+    cs:description "TSDoc comments must be self-contained — a reader should fully understand the documented symbol from its comment alone. External links (public specs, RFCs, GitHub issues) are allowed as supplementary references, but the comment itself must never depend on them for comprehension. If an external concept drives the implementation, distill the essential information into the comment." ;
+    cs:do [
+        cs:description "Explain the concept inline so the reader needs nothing else" ;
+        cs:language "typescript" ;
+        cs:code """
 /**
  * Encode a string as a percent-encoded URI component.
  *
@@ -141,10 +157,12 @@ cs:TSDocSelfContained a cso:CodeStandard ;
 export function encodeComponent(value: string): string {
   // ...
 }
-```
-
-(Do) Add an external link as a supplementary reference after a self-sufficient explanation:
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Add an external link as a supplementary reference after a self-sufficient explanation" ;
+        cs:language "typescript" ;
+        cs:code """
 /**
  * Compare two semantic version strings.
  *
@@ -157,10 +175,12 @@ export function encodeComponent(value: string): string {
 export function compareVersions(a: string, b: string): number {
   // ...
 }
-```
-
-(Do) Reference a GitHub issue for additional context when the comment already explains the behaviour:
-```typescript
+    """
+    ] ;
+    cs:do [
+        cs:description "Reference a GitHub issue for additional context when the comment already explains the behaviour" ;
+        cs:language "typescript" ;
+        cs:code """
 /**
  * Truncate session tokens to 64 characters before storage.
  *
@@ -173,11 +193,12 @@ export function compareVersions(a: string, b: string): number {
 export function truncateToken(token: string): string {
   // ...
 }
-```
-""" ;
-    cso:donts """
-(Don't) Point the reader to an external resource instead of explaining the behaviour:
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Point the reader to an external resource instead of explaining the behaviour" ;
+        cs:language "typescript" ;
+        cs:code """
 /**
  * Encode a URI component.
  *
@@ -187,10 +208,12 @@ export function truncateToken(token: string): string {
 export function encodeComponent(value: string): string {
   // ...
 }
-```
-
-(Don't) Reference a wiki or internal doc as a substitute for inline explanation:
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Reference a wiki or internal doc as a substitute for inline explanation" ;
+        cs:language "typescript" ;
+        cs:code """
 /**
  * Truncate session tokens before storage.
  *
@@ -200,10 +223,12 @@ export function encodeComponent(value: string): string {
 export function truncateToken(token: string): string {
   // ...
 }
-```
-
-(Don't) Leave the reader unable to understand the symbol without following a link:
-```typescript
+    """
+    ] ;
+    cs:dont [
+        cs:description "Leave the reader unable to understand the symbol without following a link" ;
+        cs:language "typescript" ;
+        cs:code """
 /**
  * Compare two semantic version strings.
  *
@@ -212,5 +237,5 @@ export function truncateToken(token: string): string {
 export function compareVersions(a: string, b: string): number {
   // ...
 }
-```
-""" .
+    """
+    ] .

package/data/turtle.ttl

@@ -20,9 +20,10 @@ cs:DefinitionsVsData a cs:CodeStandard ;
 - `data/` contains instance files with actual data conforming to the schema
 
 This separation allows tools to distinguish between schema and instance data, enables different validation rules, and makes the codebase easier to navigate.""" ;
-    cs:dos """
-(Do) Place ontology definitions (classes, properties, datatypes) in the `definitions/` directory.
-```turtle
+    cs:do [
+        cs:description "Place ontology definitions (classes, properties, datatypes) in the `definitions/` directory." ;
+        cs:language "turtle" ;
+        cs:code """
 # definitions/ontology.ttl
 @prefix ds: <https://ds.canonical.com/> .
 
@@ -32,32 +33,36 @@ ds:Component a owl:Class ;
 ds:name a owl:DatatypeProperty ;
     rdfs:domain ds:UIElement ;
     rdfs:range xsd:string .
-```
-
-(Do) Place instance data in the `data/` directory.
-```turtle
+    """
+    ] ;
+    cs:do [
+        cs:description "Place instance data in the `data/` directory." ;
+        cs:language "turtle" ;
+        cs:code """
 # data/global/component/button.ttl
 @prefix ds: <https://ds.canonical.com/> .
 
 ds:global.component.button a ds:Component ;
     ds:name "Button" .
-```
-""" ;
-    cs:donts """
-(Don't) Mix class definitions and instance data in the same file.
-```turtle
+    """
+    ] ;
+    cs:dont [
+        cs:description "Mix class definitions and instance data in the same file." ;
+        cs:language "turtle" ;
+        cs:code """
 # Bad: Mixing schema and data
 ds:Component a owl:Class .
 ds:global.component.button a ds:Component .
-```
-
-(Don't) Place instance data in the `definitions/` directory.
-```
+    """
+    ] ;
+    cs:dont [
+        cs:description "Place instance data in the `definitions/` directory." ;
+        cs:code """
 # Bad: Data file in definitions
 definitions/
   └── button.ttl  # Contains instance data
-```
-""" .
+    """
+    ] .
 
 # Local Name Casing Convention Standard
 cs:LocalNameCasing a cs:CodeStandard ;
@@ -70,47 +75,57 @@ cs:LocalNameCasing a cs:CodeStandard ;
 - **lowercase** (often with dots or hyphens) for instances (e.g., `ds:global.component.button`)
 
 This convention allows a single prefix to serve both definitions and data, with the casing clearly indicating the type of resource.""" ;
-    cs:dos """
-(Do) Use PascalCase for class names.
-```turtle
+    cs:do [
+        cs:description "Use PascalCase for class names." ;
+        cs:language "turtle" ;
+        cs:code """
 ds:Component a owl:Class .
 ds:UIBlock a owl:Class .
 ds:ModifierFamily a owl:Class .
-```
-
-(Do) Use camelCase for property names.
-```turtle
+    """
+    ] ;
+    cs:do [
+        cs:description "Use camelCase for property names." ;
+        cs:language "turtle" ;
+        cs:code """
 ds:name a owl:DatatypeProperty .
 ds:hasProperty a owl:ObjectProperty .
 ds:parentComponent a owl:ObjectProperty .
-```
-
-(Do) Use lowercase (with dots or hyphens as separators) for instance identifiers.
-```turtle
+    """
+    ] ;
+    cs:do [
+        cs:description "Use lowercase (with dots or hyphens as separators) for instance identifiers." ;
+        cs:language "turtle" ;
+        cs:code """
 ds:global.component.button a ds:Component .
 ds:global.modifier_family.importance a ds:ModifierFamily .
-```
-""" ;
-    cs:donts """
-(Don't) Use lowercase for class names.
-```turtle
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use lowercase for class names." ;
+        cs:language "turtle" ;
+        cs:code """
 # Bad: Class names should be PascalCase
 ds:component a owl:Class .
-```
-
-(Don't) Use PascalCase for instance identifiers.
-```turtle
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use PascalCase for instance identifiers." ;
+        cs:language "turtle" ;
+        cs:code """
 # Bad: Instance names should be lowercase
 ds:GlobalComponentButton a ds:Component .
-```
-
-(Don't) Use PascalCase or uppercase for property names.
-```turtle
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use PascalCase or uppercase for property names." ;
+        cs:language "turtle" ;
+        cs:code """
 # Bad: Property names should be camelCase
 ds:HasProperty a owl:ObjectProperty .
 ds:NAME a owl:DatatypeProperty .
-```
-""" .
+    """
+    ] .
 
 # Unified Prefix Standard
 cs:UnifiedPrefix a cs:CodeStandard ;
@@ -119,9 +134,10 @@ cs:UnifiedPrefix a cs:CodeStandard ;
     cs:description """When a package uses a single namespace for both ontology and data, use a unified prefix with casing to distinguish between classes, properties, and instances. This simplifies prefix management and makes the relationship between schema and data more apparent.
 
 The namespace URI should be a base URI without a fragment or trailing path segment for ontology vs data (e.g., `https://ds.canonical.com/` rather than separate `https://ds.canonical.com/ontology#` and `https://ds.canonical.com/data/`).""" ;
-    cs:dos """
-(Do) Use a single prefix for both definitions and data.
-```turtle
+    cs:do [
+        cs:description "Use a single prefix for both definitions and data." ;
+        cs:language "turtle" ;
+        cs:code """
 # In both definitions/ and data/ files:
 @prefix ds: <https://ds.canonical.com/> .
 
@@ -132,27 +148,29 @@ ds:name a owl:DatatypeProperty .
 # Data uses lowercase
 ds:global.component.button a ds:Component ;
     ds:name "Button" .
-```
-""" ;
-    cs:donts """
-(Don't) Use separate prefixes for ontology and data when a unified prefix is preferred.
-```turtle
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use separate prefixes for ontology and data when a unified prefix is preferred." ;
+        cs:language "turtle" ;
+        cs:code """
 # Bad: Unnecessarily complex when unified prefix suffices
 @prefix dso: <https://ds.canonical.com/ontology#> .
 @prefix ds: <https://ds.canonical.com/data/> .
 
 ds:global.component.button a dso:Component .
-```
-""" .
+    """
+    ] .
 
 # Prefix Declaration Standard
 cs:PrefixDeclaration a cs:CodeStandard ;
     cs:name "turtle/syntax/prefix-declaration" ;
     cs:hasCategory cs:TurtleCategory ;
     cs:description """Every Turtle file must declare all prefixes used within the file at the top of the file. Each prefix should be declared exactly once. Standard prefixes (rdf, rdfs, owl, xsd, skos) should be declared when used but are commonly understood.""" ;
-    cs:dos """
-(Do) Declare all prefixes at the top of the file.
-```turtle
+    cs:do [
+        cs:description "Declare all prefixes at the top of the file." ;
+        cs:language "turtle" ;
+        cs:code """
 @prefix rdf:   <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
 @prefix rdfs:  <http://www.w3.org/2000/01/rdf-schema#> .
 @prefix owl:   <http://www.w3.org/2002/07/owl#> .
@@ -161,19 +179,22 @@ cs:PrefixDeclaration a cs:CodeStandard ;
 
 ds:Component a owl:Class ;
     rdfs:label "Component" .
-```
-""" ;
-    cs:donts """
-(Don't) Declare the same prefix multiple times.
-```turtle
+    """
+    ] ;
+    cs:dont [
+        cs:description "Declare the same prefix multiple times." ;
+        cs:language "turtle" ;
+        cs:code """
 # Bad: Duplicate prefix declaration
 @prefix ds: <https://ds.canonical.com/> .
 @prefix ds: <https://ds.canonical.com/> .
-```
-
-(Don't) Use prefixes without declaring them.
-```turtle
+    """
+    ] ;
+    cs:dont [
+        cs:description "Use prefixes without declaring them." ;
+        cs:language "turtle" ;
+        cs:code """
 # Bad: Missing prefix declaration for ds:
 ds:Component a owl:Class .
-```
-""" .
+    """
+    ] .

package/definitions/CodeStandard.ttl

@@ -8,8 +8,8 @@
 # Ontology Declaration
 cs: a owl:Ontology ;
     rdfs:label "Code Standards Ontology"@en ;
-    rdfs:comment "An ontology for describing software development code standards and best practices. This ontology provides a structured way to document coding standards including categories, descriptions, do's and don'ts."@en ;
-    owl:versionInfo "1.0.0" .
+    rdfs:comment "An ontology for describing software development code standards and best practices. This ontology provides a structured way to document coding standards including categories, descriptions, do's and don'ts with structured examples."@en ;
+    owl:versionInfo "2.0.0" .
 
 # Classes
 cs:CodeStandard a owl:Class ;
@@ -21,6 +21,10 @@ cs:Category a owl:Class ;
             rdfs:comment "A category for grouping related code standards (e.g., testing, components, react, typescript)"@en ;
             rdfs:subClassOf skos:Concept .
 
+cs:Example a owl:Class ;
+           rdfs:label "Example"@en ;
+           rdfs:comment "A single do or don't example with a description, optional language tag, and optional code block"@en .
+
 # Datatype properties
 cs:slug a owl:DatatypeProperty ;
     rdfs:label "slug"@en ;
@@ -48,6 +52,17 @@ cs:extends a owl:ObjectProperty ;
               rdfs:domain cs:CodeStandard ;
               rdfs:range cs:CodeStandard .
 
+cs:do a owl:ObjectProperty ;
+      rdfs:label "do"@en ;
+      rdfs:comment "A positive example showing what should be done"@en ;
+      rdfs:domain cs:CodeStandard ;
+      rdfs:range cs:Example .
+
+cs:dont a owl:ObjectProperty ;
+        rdfs:label "don't"@en ;
+        rdfs:comment "A negative example showing what should not be done"@en ;
+        rdfs:domain cs:CodeStandard ;
+        rdfs:range cs:Example .
 
 cs:name a owl:DatatypeProperty ;
         rdfs:label "name"@en ;
@@ -57,24 +72,17 @@ cs:name a owl:DatatypeProperty ;
 
 cs:description a owl:DatatypeProperty ;
                rdfs:label "description"@en ;
-               rdfs:comment "A general description of the code standard in markdown format"@en ;
-               rdfs:domain cs:CodeStandard ;
+               rdfs:comment "A general description of the code standard or example"@en ;
                rdfs:range xsd:string .
 
-cs:dos a owl:DatatypeProperty ;
-       rdfs:label "do's"@en ;
-       rdfs:comment "Examples of what should be done, in markdown format"@en ;
-       rdfs:domain cs:CodeStandard ;
-       rdfs:range xsd:string .
-
-cs:donts a owl:DatatypeProperty ;
-         rdfs:label "don'ts"@en ;
-         rdfs:comment "Examples of what should not be done, in markdown format"@en ;
-         rdfs:domain cs:CodeStandard ;
-         rdfs:range xsd:string .
+cs:language a owl:DatatypeProperty ;
+            rdfs:label "language"@en ;
+            rdfs:comment "The programming language of the example code block (e.g., 'typescript', 'rust', 'css', 'bash', 'svg', 'turtle')"@en ;
+            rdfs:domain cs:Example ;
+            rdfs:range xsd:string .
 
-cs:slug a owl:DatatypeProperty ;
-    rdfs:label "slug"@en ;
-    rdfs:comment "A short identifier for the category or standard, used for domain annotation."@en ;
-    rdfs:domain cs:Category ;
-    rdfs:range xsd:string .
+cs:code a owl:DatatypeProperty ;
+        rdfs:label "code"@en ;
+        rdfs:comment "The code content of the example"@en ;
+        rdfs:domain cs:Example ;
+        rdfs:range xsd:string .