For Coding Agents¶

Dense, prescriptive reference for AI coding agents working on or integrating with iscc-schema.

Architecture Map¶

File Layout¶

Schema Composition¶

IsccMeta (iscc-all.yaml composes via allOf + $ref):
  ├── iscc-jsonld.yaml      → @context, @type, $schema
  ├── iscc-minimal.yaml     → iscc
  ├── iscc-basic.yaml       → name, description, meta
  ├── iscc-embeddable.yaml  → creator, license, credit, rights, acquire
  ├── iscc-extended.yaml    → media_id, iscc_id, image, identifier, keywords, form, version, tdm, genai
  ├── iscc-technical.yaml   → mode, filename, filesize, datasize, mediatype, duration, fps, width, height, created
  ├── iscc-crypto.yaml      → tophash, metahash, datahash, nonce, signature
  ├── iscc-nft.yaml         → external_url, animation_url, properties, attributes, nft
  └── iscc-declaration.yaml → original, redirect, chain, wallet, credentials, verifications

Standalone (NOT in IsccMeta):
  ├── isbn.yaml      → ISBN  (seed metadata)
  ├── isrc.yaml      → ISRC  (seed metadata)
  ├── stm.yaml       → STM   (seed metadata; scholarly / DOI works)
  ├── tdm.yaml       → TDM   (service metadata; also inline in IsccMeta.tdm)
  ├── genai.yaml     → GenAI (service metadata; also inline in IsccMeta.genai)
  ├── identifiers.yaml → Identifiers (service metadata; asset-to-identifiers response, includes Identifier items)
  └── iscc-note.yaml → IsccNote (protocol record; ISCC Discovery Protocol declaration)

Import Dependency Flow¶

iscc_schema.__init__
  → iscc_schema.schema (generated) → iscc_schema.base → pydantic.BaseModel
                                    → iscc_schema.fields (AnyUrl)
  → iscc_schema.seed_isbn (generated) → iscc_schema.base
  → iscc_schema.seed_isrc (generated) → iscc_schema.base
  → iscc_schema.seed_stm (generated) → iscc_schema.base
  → iscc_schema.service_tdm (generated) → iscc_schema.base
  → iscc_schema.service_genai (generated) → iscc_schema.base
  → iscc_schema.service_identifiers (generated) → iscc_schema.base
  → iscc_schema.protocol_iscc_note (generated) → iscc_schema.base
  → iscc_schema.recovery → iscc_schema.contexts (generated)

Public API Exports¶

from iscc_schema import IsccMeta      # Main metadata model (all fields)
from iscc_schema import Signature     # Cryptographic signature (nested)
from iscc_schema import ISBN          # Seed metadata
from iscc_schema import ISRC          # Seed metadata
from iscc_schema import STM           # Seed metadata (scholarly / DOI works)
from iscc_schema import TDM           # Service metadata
from iscc_schema import GenAI         # Service metadata
from iscc_schema import Identifier    # Bare typed external identifier item
from iscc_schema import Identifiers   # Asset-to-identifiers service metadata
from iscc_schema import IsccNote      # Protocol record (ISCC Discovery Protocol)
from iscc_schema import recover_context  # JSON-LD context recovery

Decision Dispatch¶

Which model to use?¶

Which serialization method?¶

All methods accept an ld parameter (bool) to control JSON-LD field inclusion.

Default ld value depends on model type:

Which build command?¶

Constraints and Invariants¶

Model Configuration¶

All models inherit from iscc_schema.base.BaseModel with:

• extra="forbid" — unknown fields raise ValidationError by default; generated Service objects (TDM, GenAI, Identifiers), nested identifier items, and their inline forms in IsccMeta override this to extra="allow" for forward-compatible service signals
• validate_assignment=True — assignment validates at runtime
• use_enum_values=True — enums serialize to string values
• populate_by_name=True — accept both context_ and @context
• from_attributes=True — models can be built from objects with matching attributes (ORM-style)

Empty String Coercion¶

The @model_validator(mode="before") in base.py converts falsy values on declared schema fields to None, except empty lists on required list fields, which are preserved so list constraints such as minItems can run. Combined with exclude_none=True in serialization, empty optional declared values are silently dropped. Unknown extension fields are preserved as supplied, including 0.0, [], {}, "", and False.

URL Validation¶

AnyUrl in fields.py validates against RFC 3986. Accepts any scheme (http, https, ipfs, data, urn). Empty string → None via the empty-string coercion.

Field Aliases¶

Three fields use aliases because @ and $ are invalid in Python identifiers:

Extension Fields¶

Authored in the YAML source:

x-iscc-jsonld is generated, not authored — build_json_schema.py writes it into each standalone schema JSON to document the compact→JSON-LD upgrade path.

Generated File Post-Processing¶

build_code.py applies two patches after code generation:

1. Import swap: pydantic.BaseModel → iscc_schema.base.BaseModel, pydantic.AnyUrl → iscc_schema.fields.AnyUrl
2. URL versioning: http://purl.org/iscc/context → http://purl.org/iscc/context/{version}.jsonld, http://purl.org/iscc/schema → http://purl.org/iscc/schema/{version}.json

Side Effects Catalog¶

Task Recipes¶

Add a new field to IsccMeta¶

1. Choose the appropriate YAML schema file in iscc_schema/models/ based on the field's category
2. Add the property with type, description, and x-iscc-* extension fields
3. Add the field name to the priority list in tools/build_json_schema.py for property ordering
4. Run uv run poe all to regenerate everything and run tests
5. Verify the field appears in schema.py, docs/schema/iscc.json, and vocabulary docs

Add a new standalone schema (seed, service, or protocol)¶

Standalone schemas come in three categories: seed (compact JSON, for Meta-Code generation), service (JSON-LD by default, for registry discovery), and protocol (compact JSON with a version-specific $schema, for ISCC Discovery Protocol records like IsccNote).

1. Create iscc_schema/models/{name}.yaml with title, type, properties
2. Add to SEED_SCHEMAS, SERVICE_SCHEMAS, or PROTOCOL_SCHEMAS in tools/build_code.py
3. Add to the matching list in tools/build_json_schema.py
4. Add to the matching list in tools/build_json_ld_context.py (service/protocol schemas also need their @type IRI in the hardcoded context dict, e.g. "IsccNote": ".../terms/#IsccNote")
5. Add to the matching list in tools/build_terms.py
6. Add to the matching list and to STANDALONE_META in tools/build_docs.py
7. Export the new model from iscc_schema/__init__.py
8. Add the schema's doc page to the nav in zensical.toml and to PAGES in tools/gen_llms_full.py
9. Run uv run poe all

Recover JSON-LD context from plain JSON¶

from iscc_schema import recover_context

data = {"iscc": "ISCC:KACYPXW445FTYNJ3", "name": "Example"}
data_with_context = recover_context(data)
# Adds @context from SCHEMA_CONTEXTS[SCHEMA_ISCC]

Bypass validation (downstream pattern)¶

meta = IsccMeta.model_construct(iscc="ISCC:...", name="...")
# No validation, no coercion — use only for trusted internal data

Change Playbook¶

If modifying a YAML schema property¶

• Run uv run poe all — regenerates code, JSON Schema, context, docs, runs tests
• Check generated schema.py for correct field type and alias
• Check docs/schema/iscc.json for correct property definition
• If property has x-iscc-context: check docs/context/iscc.jsonld and contexts.py

If modifying base.py¶

• Run uv run pytest — tests cover serialization, coercion, JCS
• Check that dict(), json(), jcs() defaults still match expectations
• Downstream impact: iscc-sdk subclasses IsccMeta and uses .construct() extensively

If modifying fields.py (AnyUrl)¶

• Run uv run pytest — tests cover URL validation patterns
• Check that valid URIs (http, ipfs, data, urn) still accepted
• Check that empty string → None coercion still works

If modifying build_code.py¶

• Run uv run poe buildcode && uv run pytest
• Verify post-processing patches applied correctly in generated files
• Check import statements in schema.py reference iscc_schema.base.BaseModel

If modifying build_json_schema.py¶

• Run uv run poe buildschema
• Verify docs/schema/iscc.json property order matches priority list
• Verify contexts.py regenerated with correct mappings
• Verify @context property accepts both URI string and inline object

If adding a new x-iscc-* extension field¶

• Update all tools/build_*.py scripts that inspect extension fields
• Update tools/build_docs.py to render the new extension in documentation
• Run uv run poe all

Common Mistakes¶

NEVER edit schema.py, generator.py, seed_*.py, service_*.py, or contexts.py directly — they are overwritten by poe buildcode / poe buildschema. ALWAYS edit the source YAML schemas and run the build pipeline.

NEVER add a new YAML schema field without adding it to the priority list in tools/build_json_schema.py. Fields missing from this list end up unsorted at the bottom of the generated JSON Schema.

NEVER use pydantic.BaseModel or pydantic.AnyUrl in hand-written code that extends iscc-schema. ALWAYS use iscc_schema.base.BaseModel and iscc_schema.fields.AnyUrl — they provide JSON-LD serialization, empty-string coercion, and RFC 3986 validation.

NEVER assume fields are present in serialized output. exclude_none=True and exclude_unset=True mean only explicitly set, non-None fields appear. ALWAYS check for key existence when consuming IsccMeta dicts.

NEVER pass by_alias=False to dict() or json() unless you specifically need Python field names (context_, type_, schema_). The default by_alias=True produces JSON-LD compatible output with @context, @type, $schema.

NEVER add a standalone schema without updating ALL five build scripts (build_code.py, build_json_schema.py, build_json_ld_context.py, build_terms.py, build_docs.py) plus public exports and docs navigation. Missing any one causes incomplete output.