Contribution Guidelines

The Triodian Metamodel is an open-source project that welcomes contributions from the community. This page explains how to contribute effectively.

Contributions go to one of two repositories:

Repository	What it holds	Contribute here when you want to
Triodian/Triodian_Metamodel	The JSON Schemas (`schemas/`), the shared vocabulary (`schemas/common.schema.json`), worked examples (`examples/`), interoperability mappings (`interoperability/`) and the validation scripts (`scripts/`)	Change or add a schema, a value list, an example or a mapping
The documentation site repository (Triodian/metamodel_website, the Docusaurus source of metamodel.triodian.com)	One MDX page per documentation page under `docs/`, and `scripts/check_docs.py`, which checks the pages against the schemas	Fix or improve a documentation page

The schemas are the source of truth: when a schema changes, the matching documentation page changes too.

Ways to Contribute

Contribution Type	Description	Skill Level
Report Issues	Identify bugs, gaps, or improvements	Beginner
Improve Documentation	Fix typos, clarify content, add examples	Beginner
Propose Enhancements	Suggest new features or domains	Intermediate
Submit Schema Changes	Modify or extend JSON schemas	Intermediate
Create Examples	Add real-world usage examples	Intermediate
Build Integrations	Develop platform integrations	Advanced
Review Pull Requests	Help review community contributions	Advanced

Getting Started

1. Understand the Project

Before contributing, familiarize yourself with:

Metamodel Overview — Core concepts
Domain Documentation — Existing domains
JSON Schema Index — Schema structure
Open Source Manifesto — Project philosophy

2. Set Up Your Environment

For schema changes, fork Triodian/Triodian_Metamodel on GitHub, then:

# Clone your fork
git clone https://github.com/YOUR-USERNAME/Triodian_Metamodel.git
cd Triodian_Metamodel

# Add upstream remote
git remote add upstream https://github.com/Triodian/Triodian_Metamodel.git

# Install the validator's dependencies (Python 3)
pip install -r scripts/requirements.txt

# Run validation
python scripts/validate.py

For documentation changes, clone the documentation site repository and run it locally (Node 20 or later):

npm ci          # install the pinned dependencies
npm start       # local preview with live reload at http://localhost:3000

3. Find Something to Work On

Check GitHub Issues for open tasks
Look for issues labeled good first issue for beginner-friendly tasks
Review help wanted labels for community priority items

Contribution Workflow

For Documentation Changes

Fork the documentation site repository
Create a branch for your changes: git checkout -b docs/improve-capabilities-examples
Make changes to the MDX files under docs/
Test locally with npm start, and check the page against the schemas with python scripts/check_docs.py ../Triodian_Metamodel --warnings docs/<page>.mdx (a checkout of the metamodel repository next to the site)
Submit a Pull Request with clear description
Address review feedback as needed
Celebrate when merged!

For Schema Changes

Schema changes are made in Triodian/Triodian_Metamodel and require additional rigor:

Create an Issue first — Discuss proposed changes before implementing
Edit the schema under schemas/, following the Schema Standards below
Add or adjust examples — Update the schema's embedded examples and, where a documented worked example is affected, its file in examples/doc-examples/ (listed in manifest.json)
Run the validator — python scripts/validate.py --doc-examples must pass locally
Change shared values in one place — Value lists shared across domains (priority, risk level, frequency, status, maturity, domain type …) live in schemas/common.schema.json. After changing them, run python scripts/vocabulary_map.py to regenerate docs/shared-vocabulary.md and python scripts/vocabulary_map.py --check to confirm no shared concept uses a local list
Record renamed values in docs/vocabulary-migration.json, so existing implementations can migrate
Update documentation — Open a matching pull request on the documentation site

CI (.github/workflows/validate-schemas.yml) runs on every push and pull request. It runs the structural checks, confirms the shared vocabulary report is up to date, runs vocabulary_map.py --check and validates the documentation examples. All four steps are blocking: a pull request cannot be merged until CI passes.

Schema Standards

Naming Conventions

Element	Convention	Example
Schema files	kebab-case, singular, `<domain>.schema.json`	`capability.schema.json`, `value-stream.schema.json`
Schema `$id`	`https://triodian.com/schemas/` followed by the file's path	`https://triodian.com/schemas/capability.schema.json`
Property names	camelCase	`maturityLevel`
Identifiers	`<entity>ID` (never `id` or `…Id`)	`capabilityID`, `orgUnitID`
Enum values	camelCase	`inProgress`
Definition names	camelCase	`capabilityComponent`

Required Schema Elements

Every domain schema uses JSON Schema draft-07, has its domain's main record at the root, a required identifier, "additionalProperties": false, and its element types under definitions:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://triodian.com/schemas/capability.schema.json",
  "title": "Capabilities Domain Schema",
  "description": "Schema for the Capabilities domain in the Triodian Metamodel",
  "type": "object",
  "required": ["capabilityID", "title", "description", "purpose", "owner"],
  "additionalProperties": false,
  "properties": {
    "capabilityID": {
      "description": "Unique identifier for the Capability",
      "allOf": [{ "$ref": "common.schema.json#/definitions/identifier" }]
    },
    "title": {
      "type": "string",
      "description": "The name or title of the Capability"
    },
    "description": {
      "type": "string",
      "description": "A detailed explanation of what the Capability entails"
    }
  },
  "definitions": {}
}

Property Guidelines

Property Aspect	Guideline
Descriptions	Every property must have a description
Types	Use specific types (not just `any`)
Required	Mark truly required fields as required
Undefined fields	Every object sets `"additionalProperties": false`
Enums	Use enums for categorical values, with camelCase values
Shared concepts	Reference the shared list in `common.schema.json` instead of defining a local one
References	Use `$ref` for reusable definitions; element types live under `definitions`
Links	Carry the ID beside the name (`orgUnitTitle` with `orgUnitID`, `parent` with `parentCapabilityID`)
Examples	Every new or changed schema has an example that validates

Enum Conventions

Values are camelCase. A field that expresses a shared concept references the shared list:

{
  "maturityLevel": {
    "description": "Current maturity level of the Capability",
    "allOf": [{ "$ref": "common.schema.json#/definitions/maturityLevel" }]
  }
}

The shared maturityLevel list is initial, repeatable, defined, managed, optimizing. A domain-specific list is defined in place:

{
  "capabilityCategory": {
    "type": "string",
    "description": "Broad categorization of capability type",
    "enum": ["coreBusiness", "supporting", "enabling", "strategic", "foundational", "distinctive"]
  }
}

Documentation Standards

MDX File Structure

---
sidebar_position: 1
title: Page Title
description: Clear, concise description for SEO
keywords: [relevant, keywords, for, search]
---

# Page Title

Brief introduction paragraph.

## Main Section

Content organized in logical sections.

### Subsection

More detailed content.

## Related Documentation

- [Related Page 1](./related-1) — Brief description
- [Related Page 2](./related-2) — Brief description

Writing Style

Aspect	Guideline
Voice	Active voice preferred
Tense	Present tense for descriptions
Person	Second person ("you") for instructions
Length	Concise sentences, short paragraphs
Examples	Include practical examples
Tables	Use tables for structured comparisons

Code Examples

Include language identifier: ```json, ```python
Tag every JSON example: ```json schema=<file>.schema.json for a complete record (it is validated against the schema; add #/definitions/<name> for an element), or ```json fragment for a partial snippet
Follow the metamodel's conventions in every example: camelCase property names and values, <entity>ID identifiers, and the shared value lists
Link to schemas on GitHub (the file under blob/main/schemas/ in Triodian_Metamodel), as the domain pages do with their **Schema:** line
Keep examples realistic and complete; where the metamodel repository has a matching example in examples/doc-examples/, use it
Add comments for complex examples
Test all code examples before submitting

Pull Request Guidelines

PR Title Format

type(scope): brief description

Examples:
- docs(capabilities): add example for manufacturing
- schema(risk): add control effectiveness enum
- fix(validation): correct required field check

Types: docs, schema, fix, feat, refactor, test, chore

PR Description Template

## Description
Brief description of changes.

## Motivation
Why is this change needed?

## Changes Made
- Change 1
- Change 2

## Testing
How were these changes tested?

## Related Issues
Closes #123

## Checklist
- [ ] Documentation updated
- [ ] Schema validates correctly
- [ ] Examples tested
- [ ] No breaking changes (or migration guide provided)

Review Process

Automated checks — In the metamodel repository, CI runs scripts/validate.py (structure and documentation examples) and scripts/vocabulary_map.py --check; on the documentation site, CI runs scripts/check_docs.py and the site build
Community review — At least one approval required
Maintainer review — Final approval from project maintainer
Merge — Squash and merge to main branch

Issue Guidelines

Bug Reports

## Bug Description
Clear description of the bug.

## Steps to Reproduce
1. Step one
2. Step two
3. Step three

## Expected Behavior
What should happen.

## Actual Behavior
What actually happens.

## Environment
- Browser/Tool: 
- Version:

## Additional Context
Screenshots, logs, etc.

Feature Requests

## Feature Description
Clear description of the proposed feature.

## Motivation
Why is this feature needed? What problem does it solve?

## Proposed Solution
How should this feature work?

## Alternatives Considered
Other approaches considered and why this is preferred.

## Additional Context
Mockups, examples from other tools, etc.

Community Guidelines

Code of Conduct

We are committed to providing a welcoming and inclusive environment:

Be respectful — Treat all contributors with respect
Be constructive — Focus on improving the project
Be patient — Remember that contributors have varying experience levels
Be collaborative — Work together toward common goals

Communication Channels

Channel	Purpose
GitHub Issues	Bug reports, feature requests
GitHub Discussions	Questions, ideas, general discussion
Pull Requests	Code and documentation contributions

Response Times

Activity	Expected Response
Issue triage	Within 1 week
PR initial review	Within 2 weeks
Discussion reply	Within 1 week

Recognition

Contributors

All contributors are recognized in:

GitHub contributors list
Release notes for significant contributions
Annual contributor acknowledgment

Types of Recognition

Contribution Level	Recognition
First contribution	Welcome message, first-timer badge
Regular contributor	Contributor badge
Significant impact	Featured contributor
Sustained contribution	Maintainer consideration

Licensing

Contribution License

By contributing to the Triodian Metamodel, you agree that your contributions will be licensed under the Apache License, Version 2.0, the licence of the repository.

What This Means

Your contributions can be used, modified, and redistributed by anyone
Commercial use is permitted, including in proprietary products
You grant users a licence to any of your patents that your contribution covers
Licence and attribution notices must be kept when the work is redistributed

Getting Help

Stuck?

Check existing GitHub Issues
Ask in GitHub Discussions
Review similar merged PRs for examples

Questions About This Guide?

Open an issue with the label question or ask in Discussions.

Quick Reference

Common Commands

In the metamodel repository:

# Validate all schemas (structural checks)
python scripts/validate.py

# Also validate the documentation's worked examples
python scripts/validate.py --doc-examples

# Regenerate the shared vocabulary report
python scripts/vocabulary_map.py

# Check that shared concepts use the shared vocabulary
python scripts/vocabulary_map.py --check

In the documentation site repository:

# Run local documentation server
npm start

# Build documentation locally
npm run build

# Check pages against the schemas
python scripts/check_docs.py ../Triodian_Metamodel --warnings

File Locations

Content Type	Location
Domain, relationship and Strategic Response Model schemas	`schemas/` in Triodian_Metamodel
Shared vocabulary	`schemas/common.schema.json`
Coverage schemas	`schemas/coverage/`
Extension schemas	`schemas/extensions/`
Worked examples	`examples/doc-examples/` (with `manifest.json`)
Interoperability mappings	`interoperability/`
Validation scripts	`scripts/validate.py`, `scripts/vocabulary_map.py`
Documentation pages	`docs/` in the documentation site repository

Open Source Manifesto — Project philosophy
JSON Schema Index — Schema reference
Domain Attributes — Attribute reference

Ways to Contribute​

Getting Started​

1. Understand the Project​

2. Set Up Your Environment​

3. Find Something to Work On​

Contribution Workflow​

For Documentation Changes​

For Schema Changes​

Schema Standards​

Naming Conventions​

Required Schema Elements​

Property Guidelines​

Enum Conventions​

Documentation Standards​

MDX File Structure​

Writing Style​

Code Examples​

Pull Request Guidelines​

PR Title Format​

PR Description Template​

Review Process​

Issue Guidelines​

Bug Reports​

Feature Requests​

Community Guidelines​

Code of Conduct​

Communication Channels​

Response Times​

Recognition​

Contributors​

Types of Recognition​

Licensing​

Contribution License​

What This Means​

Getting Help​

Stuck?​

Questions About This Guide?​

Quick Reference​

Common Commands​

File Locations​

Related Documentation​