Getting Started

General Information

The CommonsDB API facilitates the declaration of metadata and rights using cryptographic methods. This section provides an overview of key processes required for making API calls.

Overview

CommonsDB uses a combination of cryptographic signatures and structured metadata to ensure the integrity and authenticity of content declarations. Understanding these fundamental concepts is essential for successful API integration.

Key Concepts

Cryptographic Validation

All declarations in CommonsDB use cryptographic signatures to ensure:

• Authenticity: Proof that the declaration comes from the claimed source
• Integrity: Assurance that the data hasn't been tampered with
• Non-repudiation: The ability to prove that a declaration was made by a specific entity

Decentralized Identifiers (DIDs)

CommonsDB uses Decentralized Identifiers to associate cryptographic keys with domain ownership, enabling trustless verification of declarations.

---

Metadata Collection

To make a proper API call, a structured metadata object must be included in the HTTP request body.

Metadata Structure

The metadata object contains essential information required for a declaration, including:

• Cryptographic Signatures: For validation, namely signature, tsaSignature, and optionally commonsDbRegistrySignature and commonsDbRegistryTsaSignature
• Public Metadata: The publicMetadata section stores core declaration data including iscc, declarerId, credentials, and optional fields such as supplierMetadata and isccContentCode256
• CommonsDB Registry: The optional commonsDbRegistry section for public domain and Creative Commons licensed content

Example Metadata Object

Code(json)
 
{
  "signature": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImp3ayI6e319.payload.signature",
  "tsaSignature": {
    "tsr": "base64-encoded-timestamp-response",
    "tsq": "base64-encoded-timestamp-request"
  },
  "commonsDbRegistrySignature": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCIsImp3ayI6e319.registry-payload.signature",
  "commonsDbRegistryTsaSignature": {
    "tsr": "base64-encoded-registry-timestamp-response",
    "tsq": "base64-encoded-registry-timestamp-request"
  },
  "declarationMetadata": {
    "publicMetadata": {
      "$schema": "https://w3id.org/commonsdb/schema/0.2.0.json",
      "@context": "https://w3id.org/commonsdb/context/0.2.0.json",
      "iscc": "ISCC:KEC2EHPLVKPVDFVORULRVCUFXL3DZ4SA6JSDQLNOXEVYYCXR4N5IBDY",
      "isccContentCode256": "ISCC:EEDY2FY2RKC3V5R4BMYFK6U7YTUQ4M2YPWRMP3ARGZNYBJOK54KDSXQ",
      "name": "Example Content",
      "description": "Sample content description",
      "mediatype": "image/jpeg",
      "timestamp": 1736251200000,
      "declarerId": "did:web:example.com",
      "credentials": [
        {
          "@context": ["https://www.w3.org/ns/credentials/v2"],
          "type": ["VerifiableCredential", "VerifiableSupplier"],
          "proof": {
            "type": "JwtProof2020",
            "jwt": "eyJhbGciOiJFUzI1NiJ9..."
          }
        }
      ],
      "supplierMetadata": {
        "rightsStatement": "https://creativecommons.org/publicdomain/mark/1.0/",
        "location": "https://europeana.eu/item/123",
        "name": "Example Content",
        "creator": "John Doe",
        "description": "Sample content description",
        "attributionString": "John Doe, via Example Organization"
      }
    },
    "commonsDbRegistry": {
      "iscc": "ISCC:KEC2EHPLVKPVDFVORULRVCUFXL3DZ4SA6JSDQLNOXEVYYCXR4N5IBDY",
      "location": "https://europeana.eu/item/123",
      "rightsStatement": "https://creativecommons.org/publicdomain/mark/1.0/",
      "timestamp": 1736251200000,
      "credentials": [
        {
          "proof": "eyJhbGciOiJFUzI1NiJ9..."
        }
      ]
    }
  }
}

256-bit ISCC Content-Code (isccContentCode256)

The composite iscc embeds a 64-bit Content-Code unit. Declarers who generate their ISCC units at a higher resolution can optionally publish the full 256-bit Content-Code of the same asset in publicMetadata.isccContentCode256 (a standalone Content-Code ISCC-UNIT, e.g. generated with bits=256 in iscc-core / iscc-sdk).

Validation rules (enforced at declaration time):

1. isccContentCode256 never replaces iscc — the composite ISCC is still required.
2. The value must be a well-formed 256-bit Content-Code ISCC-UNIT (ISCC: followed by 55 base32 characters).
3. Its content type (Text/Image/Audio/Video/Mixed) must match the content type of the composite iscc.
4. Longer ISCC units are extensions of their truncated forms, so the 256-bit Content-Code must start with the 64-bit Content-Code unit embedded in iscc. Declarations where the first 64 bits differ are rejected with a 422 error.

Once accepted, the field is stored with the rest of the public metadata and returned unchanged by all metadata retrieval endpoints.

Use cases:

• Higher-precision similarity matching: 64 bits of Content-Code resolution are sufficient for candidate lookup, but at registry scale they can produce false positives for near-duplicate detection. The 256-bit code lets consumers confirm matches with far higher confidence.
• Independent content verification: Anyone holding a copy of the asset can regenerate the 256-bit Content-Code locally and compare it with the declared one — a much stronger check than the 64-bit unit alone, without needing access to the original file used at declaration time.
• Cross-registry interoperability: Registries and matching engines that operate on full-length ISCC units can match declared content directly, instead of truncating their own codes to 64 bits.
• Rights and preference enforcement: TDM/AI opt-out and licensing workflows that match content at scale can rely on the finer-grained code to reduce wrongful matches when resolving declarations for a given asset.

Metadata Validation Process

Best Practices

Next Steps

Now that you understand the basics of metadata collection, you can proceed to:

• Set up X.509 certification for cryptographic authentication
• Learn about metadata signatures for metadata validation
• Explore the Declaration API for making your first declaration