Contributing¶

We'd love your help with iscc-schema, from typo fixes to new schema fields. This page covers everything you need to get a working development environment and submit a pull request.

Getting Started¶

Prerequisites¶

• Python 3.10+ (up to 3.14)
• uv for package management
• Git

Setup¶

git clone https://github.com/iscc/iscc-schema.git
cd iscc-schema
uv sync

This installs all runtime and development dependencies in an isolated virtual environment.

Verify Your Setup¶

uv run poe all

This runs the full build pipeline: YAML formatting, code generation, JSON Schema, JSON-LD context, documentation, and tests. If it passes, your environment is set up correctly.

The Golden Rule¶

YAML schemas are the single source of truth. Many files in this project are auto-generated from the OpenAPI 3.1.0 definitions in iscc_schema/models/*.yaml. Never edit generated files directly - your changes will be overwritten.

Generated files (do not edit):

• iscc_schema/schema.py - Pydantic models
• iscc_schema/generator.py - API models
• iscc_schema/seed_*.py - seed metadata models
• iscc_schema/service_*.py - service metadata models
• iscc_schema/contexts.py - JSON-LD context mappings
• docs/schema/*.json - JSON Schema files
• docs/context/*.jsonld - JSON-LD context files

Hand-editable source files:

• iscc_schema/models/*.yaml - schema definitions
• iscc_schema/base.py - custom BaseModel with serialization
• iscc_schema/fields.py - URL validation type
• iscc_schema/recovery.py - JSON-LD context recovery
• tools/*.py - build scripts

Making Changes¶

Workflow¶

1. Create a branch from develop
2. Make your changes (see task guides below)
3. Run uv run poe all to regenerate artifacts and run tests
4. Commit your changes (include both source and generated files)
5. Open a pull request against develop

Adding or Modifying a Schema Field¶

1. Find the appropriate YAML file in iscc_schema/models/ - fields are grouped by category (basic, technical, crypto, etc.)
2. Add or modify the property following the existing YAML structure
3. Add the field name to the priority list in tools/build_json_schema.py (controls property ordering in the generated JSON Schema)
4. Run uv run poe all
5. Check that the field appears correctly in iscc_schema/schema.py and docs/schema/iscc.json

Fixing a Bug in Python Code¶

1. Edit the relevant source file (base.py, fields.py, recovery.py, etc.)
2. Add a test in tests/ that reproduces the bug
3. Run uv run pytest to verify the fix

Improving Documentation¶

Documentation pages in docs/ can be edited directly, except for pages that are generated by tools/build_docs.py (schema pages, terms, index, changelog). For generated docs, modify the YAML source or the build script instead.

Serve docs locally to preview your changes:

uv run poe docs-serve

Code Conventions¶

We use Black with line length 100 for Python formatting (uv run poe formatcode, or poe all runs it for you). YAML files use 2-space indentation (uv run poe formatyaml). All files use LF line endings, enforced by the build pipeline.

Type annotations go in PEP 484 type comments, not inline:

def process(data, strict=False):
    # type: (dict, bool) -> dict
    """Process metadata."""

Use absolute imports. Write short, pure functions. No nested functions.

Testing¶

Tests live in tests/ and use pytest. Run the full suite with:

uv run pytest

Run a specific test:

uv run pytest tests/test_schema.py::test_name -v

Guidelines:

• Use real data, not mocks - if something is hard to test without mocking, refactor the code
• Write simple, focused test functions (no test classes)
• Ensure all tests pass before submitting a PR

Build Commands Reference¶

Questions?¶

Not sure where to start, or want to check whether an idea fits before writing code? Open a GitHub issue and we'll figure it out together.