ISCC - Schema

JSON Schema and JSON-LD Contexts for ISCC Metadata

What is iscc-schema?

iscc-schema provides the official schema definitions for the International Standard Content Code (ISO 24138:2024). YAML-based OpenAPI 3.1.0 definitions are the single source of truth for auto-generated JSON Schema, JSON-LD contexts, Python models, and vocabulary documentation.

Install

pip install iscc-schema

Quick Start

Core and Service metadata serialize as full JSON-LD by default:

from iscc_schema import IsccMeta

meta = IsccMeta(
    iscc="ISCC:KACYPXW445FTYNJ3CYSXHAFJMA2HUWULUNRFE3BLHRSCXYH2M5AEGQY",
    name="The Never Ending Story",
)

# Serialize as dict (set fields only)
meta.dict()
# {'iscc': 'ISCC:KACY...', 'name': 'The Never Ending Story'}

# Serialize as JSON (includes schema defaults)
meta.json()
# JSON-LD: includes @context, @type and a version-pinned $schema

Seed and Protocol records serialize as compact JSON — just the fields plus a version-pinned $schema that anchors the schema version and lets any consumer recover full JSON-LD on demand:

from iscc_schema import STM, recover_context

seed = STM(
    doi="10.5555/example.2020.0001",
    resource_type="JournalArticle",
    title="On the Stability of Quasilinear Forms",
    publisher="Meridian Academic Press",
    pubyear=2020,
)

# Compact JSON by default: fields plus the version-pinned $schema, no @context/@type
seed.json()

# Opt into full JSON-LD when you need it
seed.json(ld=True)

# Recover the JSON-LD @context from compact data using its $schema
recover_context(seed.dict())

Schema Categories

• ISCC Metadata. Core vocabulary for digital content identified by the ISCC. All fields are optional, covering content description, rights, technical properties, and cryptographic declarations.
• Seed Metadata. Industry-specific input for Meta-Code generation (ISBN, ISRC, STM). Required fields ensure interoperable content fingerprinting across platforms.
• Service Metadata. Use-case-specific schemas for ISCC registries (TDM, GenAI). Machine-readable signals for text and data mining rights and generative AI disclosure.
• Protocol Schemas. ISCC Discovery Protocol wire records (IsccNote). Compact, signature-anchored declaration records for ISCC-HUB timestamping and registration.

Published Artifacts

Documentation

Documentation is hosted at schema.iscc.codes

Development

uv sync              # Install dependencies
uv run poe all       # Full build pipeline (codegen, tests, docs)

Status

Under development. Expect breaking changes until we reach a version 1.0 release.