Repository Guidelines

Instruction Files

Read these before making changes; they are authoritative for repo workflows.

Project Structure

• linkml/ contains LinkML schema definitions for credential types
• artifacts/ contains generated OWL, SHACL, and JSON-LD context files
• examples/ contains example credential instances for testing
• manifests/ contains wallet rendering manifests
• src/ contains Python source code for the credentials pipeline
• docs/ contains MkDocs source pages
• tests/ contains pytest tests
• submodules/ contains git submodules:
  • harbour-credentials — cryptographic signing/verification library
    • harbour-credentials/submodules/ontology-management-base — ontology validation pipeline
    • harbour-credentials/submodules/w3id.org — W3ID redirect rules

Build, Test, and Development Commands

Always use make targets — never call generators, linters, or test runners directly. Each repository in the submodule chain has its own Makefile with a consistent command surface. Run make help to discover available targets.

# Install dev dependencies
make setup
make install dev

# Generate artifacts from LinkML schemas
make generate                  # all domains
make generate DOMAIN=<name>    # single domain (OMB)
make generate gx               # Gaia-X from service-characteristics (OMB)

# Lint and format
make lint
make format

# Run tests
make test

# Run validation pipeline
make validate

The make targets handle virtualenv activation, correct flags, line-ending normalisation, and cross-platform path issues. Bypassing them (e.g. calling gen-owl or python -m directly) risks producing artifacts with wrong line endings, missing flags, or inconsistent output.

Git Commit & Pull Request Policy

Commit Requirements

• Always sign commits with -s -S flags (Signed-off-by + GPG signature)
• Never include AI attribution in commits — no Co-Authored-By, Generated-By, or similar headers mentioning AI assistants (Claude, Copilot, ChatGPT, etc.)
• Never mention AI tools in commit messages — do not reference that code was AI-generated or AI-assisted
• Author must be a human developer with their official email address
• Use conventional commit format: feat:, fix:, docs:, chore:, refactor:, test:

# Correct commit command
git commit -s -S -m "feat: add new credential type"

Preparing Commits and Pull Requests

When instructed to prepare a commit or PR, default to preparing the .playground files first. After explicit human confirmation in the current session, the agent may directly create the signed commit, push the branch, and open the PR using the prepared .playground content. Otherwise:

1. Create the .playground/ directory (already in .gitignore)
2. Generate two markdown files:
   • .playground/commit-message.md — Conventional commit message(s)
   • .playground/pr-description.md — PR description following the repository's PR template

The human operator will review these files and either:

• Use them to manually commit/push and create a PR,
• Ask the agent to perform the signed commit/push/PR flow directly after explicit confirmation, or
• Use automated tooling with signed commits (git commit -s -S)

Commit Message Format

# .playground/commit-message.md

feat(linkml): add MembershipCredential schema

- Define membership credential with role claims
- Add selective disclosure annotations
- Include example instance

Refs: #123

PR Description Format

Follow .github/pull_request_template.md if it exists, otherwise use:

# .playground/pr-description.md

## Summary

Brief description of the changes.

## Changes

- List of specific changes made
- Another change

## Testing

- [ ] Tests pass locally (`make test`)
- [ ] Validation passes (`make validate`)

## Related Issues

Closes #123

Verification Before Push

STRICT REQUIREMENT — never push without local verification.

Before pushing any branch or accepting a solution as complete, the agent must:

1. Run tests locally (make test) in the affected repository and confirm they pass

2. Run validation locally (make validate) when schemas or artifacts changed

3. Run lint locally (make lint) to catch formatting issues

4. Regenerate artifacts (make generate) when LinkML schemas changed, and verify the generated output is as expected

5. Run GitLab CI locally when changing .gitlab-ci.yml or CI-related files in service-characteristics:

   # Requires: npm install -g gitlab-ci-local
   # Requires: rsync (via msys2: pacman -S rsync, or apt: apt install rsync)
   # Requires: Docker/Podman for container-based jobs
   gitlab-ci-local                    # run all jobs
   gitlab-ci-local --job test-shacl   # run a single job
   gitlab-ci-local --list             # list available jobs
   

   Note: On corporate networks, Docker image pulls may require proxy configuration. If gitlab-ci-local cannot pull images, verify the CI changes are correct by inspection and note the limitation in the PR.

6. Check submodule CI — after pushing a submodule branch, observe the CI pipeline (GitHub Actions / GitLab CI) and wait for it to go green before cascading pins to the next layer. Do not assume CI will pass; check it.

For the multi-layer submodule chain (service-characteristics → OMB → harbour-credentials → credentials), this means:

• Fix and test at the innermost affected layer first
• Push that layer, observe its CI, confirm green
• Only then update the submodule pin in the next layer up
• Repeat until all layers are green

Never skip local testing with the assumption that CI will catch issues. CI is a safety net, not a substitute for local verification.

Standards Compliance

STRICT REQUIREMENT — all schemas, examples, and models must align with the relevant W3C, IETF, and industry specifications.

When defining or modifying LinkML schemas, JSON-LD examples, or DID documents:

1. Cross-reference the spec copy in docs/. The LinkML schema files use bracketed tags (e.g. [VCDM2], [DID Core], [OID4VP], [SD-JWT]) that cite specific spec sections. Before changing a slot range, class hierarchy, or property definition, locate the corresponding spec document in docs/ and verify the modeling choice against the normative text.

2. Document the rationale in the schema. Every non-trivial modeling decision must have a YAML comment citing the spec section and briefly explaining why the chosen type/range/constraint is correct. Example:

   # [DID Core] §5.4 — serviceEndpoint is a URI, map, or set thereof.
   # Base range is uri (the common case); service-specific classes
   # override via slot_usage for structured endpoint objects.
   serviceEndpoint:
     slot_uri: didcore:serviceEndpoint
     range: uri
   

3. Use standard vocabulary (DID Core, VC Data Model 2.0, OID4VP, schema.org, Gaia-X Trust Framework) rather than inventing new terms.

4. Never use range: Any in LinkML slot definitions. linkml:Any produces rdfs:range linkml:Any in OWL, which triggers closed-shape SHACL violations during RDFS inference. Always choose a spec-aligned range:

   • uri for properties whose values are network addresses or identifiers (e.g. DID Core serviceEndpoint)
   • A named class for structured objects with a defined schema (e.g. OID4VP TransactionData)

5. Validate examples against SHACL (make validate) to catch inference issues before they reach CI.

Coding Style

• Python 3.12+ with type hints
• Use pathlib.Path (not os.path)
• 4-space indentation
• Module docstrings required
• Run make lint before committing