Code Standards Ontology

An OWL ontology for codifying software development standards as structured, queryable knowledge graphs. Standards become machine-readable, versionable, and programmatically accessible to both humans and AI agents.

Core Philosophy: Code standards are institutional knowledge. By modeling them ontologically, we transform tribal wisdom into queryable data—enabling automated linting context, AI-assisted code review, and consistent onboarding across teams.

Quick Start

1. Core Concepts

Each code standard is a structured record with:

CodeStandard
├── name         - Domain path (e.g., "react/component/folder-structure")
├── description  - What and why
├── dos          - Correct examples with code
├── donts        - Incorrect examples with explanation
├── hasCategory  - Grouping (React, CSS, Storybook...)
└── extends      - Parent standard (optional)

Standards are organized by Categories (technology domains) and can extend other standards for specialization.

2. Defining a Standard

@prefix cs: <http://pragma.canonical.com/codestandards#> .
@prefix cs:  <http://pragma.canonical.com/codestandards#> .

cs:ComponentFolderStructure a cs:CodeStandard ;
    cs:name "react/component/structure/folder" ;
    cs:hasCategory cs:ReactCategory ;
    cs:description "Each component must reside in its own folder containing all related files." ;
    cs:dos """
(Do) Place all component-related files within a single folder.
```bash
Button/
  ├── Button.tsx
  ├── Button.stories.tsx
  ├── Button.test.tsx
  ├── index.ts
  ├── styles.css
  └── types.ts

""" ; cs:donts """ (Don't) Scatter component files across different directories.

# Bad: Files are not co-located
components/Button.tsx
stories/Button.stories.tsx
styles/Button.css

""" .

3. Name Convention

Standard names follow a domain path pattern:

{category}/{domain}/{subdomain}

| Pattern | Example | |---------|---------| | react/component/folder-structure | React component folder layout | | css/selector/nesting | CSS selector nesting rules | | storybook/story/naming | Storybook story naming conventions | | rust/error/result-type | Rust error handling with Result |

Categories

Standards are grouped by technology domain:

| Category | Slug | Standards | Focus | |----------|------|-----------|-------| | React | react | 20+ | Component structure, hooks, patterns | | CSS | css | 8+ | Selectors, nesting, custom properties | | Storybook | storybook | 10+ | Stories, documentation, controls | | Code | code | 12+ | General TypeScript/JavaScript | | Styling | styling | 6+ | Design system styling patterns | | Icons | icons | 4+ | SVG icon implementation | | Rust | rust | 15+ | Idiomatic Rust, monadic composition | | Turtle | turtle | 5+ | RDF/Turtle file authoring |

How-To Guides

How to Add a New Standard

1. Identify the category (React, CSS, etc.)
2. Determine the domain path name
3. Create or edit the category's .ttl file in data/
4. Define required properties

cs:MyNewStandard a cs:CodeStandard ;
    cs:name "react/hooks/use-effect-cleanup" ;
    cs:hasCategory cs:ReactCategory ;
    cs:description """
useEffect hooks that create subscriptions, timers, or listeners must
return a cleanup function to prevent memory leaks.
""" ;
    cs:dos """
(Do) Return a cleanup function for subscriptions.
```typescript
useEffect(() => {
  const subscription = source.subscribe(handler);
  return () => subscription.unsubscribe();
}, [source]);

""" ; cs:donts """ (Don't) Forget cleanup for resources that persist.

// Bad: Timer never cleared
useEffect(() => {
  setInterval(poll, 1000);
}, []);

""" .

Writing Effective Do's and Don'ts

Do's should:

• Start with "(Do)" for parsing consistency
• Include realistic, copy-pasteable code
• Show the pattern in context

Don'ts should:

• Start with "(Don't)" for parsing consistency
• Explain why the pattern is problematic
• Show realistic mistakes developers actually make

How to Extend a Standard

Use cs:extends when a standard builds on or specializes another:

cs:ComponentContextStructure a cs:CodeStandard ;
    cs:name "react/component/structure/context" ;
    cs:extends cs:ComponentFolderStructure ;
    cs:hasCategory cs:ReactCategory ;
    cs:description """
Context provider components follow the standard folder structure with
additional files for the context definition and hook.
""" ;
    cs:dos """
(Do) Include Context.tsx and useContext hook.
```bash
AuthProvider/
  ├── AuthProvider.tsx      # Provider component
  ├── Context.tsx           # Context definition
  ├── useAuth.ts            # Consumer hook
  ├── index.ts
  └── types.ts

""" .

The extends relationship enables:

• Inheritance queries (find all folder structure variants)
• Hierarchical documentation
• Progressive specificity

Reference

Classes

| Class | Description | Instances | |-------|-------------|-----------| | CodeStandard | A coding guideline with do's and don'ts | 64 | | Category | Grouping for related standards | 8 |

CodeStandard Properties

| Property | Range | Description | |----------|-------|-------------| | name | NamePattern | Domain path identifier (e.g., react/component/folder) | | description | string | What the standard requires and why | | dos | string | Correct examples with code blocks | | donts | string | Incorrect examples with explanations | | hasCategory | Category | Technology domain classification | | extends | CodeStandard | Parent standard for specialization |

Category Properties

| Property | Range | Description | |----------|-------|-------------| | slug | string | Short identifier (e.g., react, css) | | label | string | Display name | | comment | string | Category description |

Name Pattern

Standard names must match:

^[a-z]+(/[a-z0-9-]+){2,}$

Valid: react/component/folder-structure, css/selector/nesting Invalid: React/Component, component-structure

Architecture

code-standards/
├── definitions/
│   └── CodeStandard.ttl    # TBox: Classes, properties, constraints
├── data/
│   ├── react.ttl           # React standards
│   ├── css.ttl             # CSS standards
│   ├── storybook.ttl       # Storybook standards
│   ├── code.ttl            # General code standards
│   ├── styling.ttl         # Styling standards
│   ├── icons.ttl           # Icon standards
│   ├── rust.ttl            # Rust standards
│   └── turtle.ttl          # Turtle authoring standards
├── skills/
│   └── audit/              # Standard compliance checking skill
├── sem.toml                # Package manifest
└── README.md

Namespaces

@prefix cs: <http://pragma.canonical.com/codestandards#> .

Dependencies

• skos — Category as SKOS Concept

Integration

AI Code Review

Standards are designed for AI consumption. When reviewing code, AI assistants can:

1. Query relevant standards for the code being reviewed
2. Apply the structured do's/don'ts to evaluate the diff
3. Generate precise feedback based on standard violations

The structured format enables consistent, actionable code review feedback.

IDE Integration

Standards can power:

• Real-time linting hints
• Autocomplete suggestions
• Documentation popups
• Refactoring recommendations

Onboarding

New team members can query standards by domain:

# "What are the React component rules?"
"Show me all standards for React components"

Design System Ontology

Code standards complement the Design System Ontology:

| Ontology | Focus | |----------|-------| | Design System | What to build (components, patterns, modifiers) | | Code Standards | How to build (structure, patterns, conventions) |

Version

0.1.0 — Initial release with React, CSS, Storybook, and general code standards

Links

• Source
• Design System Ontology
• Pragma Monorepo