Making Declarations: Technical Workflow

Submitting a declaration connects your local catalog data to the public registry. Because this process involves structuring institutional metadata, generating content-derived identifiers, and transmitting data to CommonsDB, the workflow is purposefully divided into three distinct phases:

1. Preparing your data (Phase 1)
2. Generating ISCC codes locally (Phase 2)
3. Executing your chosen approach (Phase 3)

By following these distinct phases, you can ensure your catalog data is accurately formatted and securely prepared before making your official declaration to the registry.

Phase 1: Preparing Your Data

Once you have successfully set up your identity and obtained your Verifiable Credential, the next step is to prepare your data.

The metadata you assemble during this phase forms the core of the declarations you will submit to the CommonsDB registry. This information will be permanently bound to the unique ISCC fingerprint of your digital asset. By preparing accurate and structured data, you ensure that essential details – such as license information, attribution, and the online location of your assets – travel alongside your content, remaining discoverable to downstream users even if the file itself is separated from your institutional catalog.

Required Data Fields

Every declaration must include a baseline set of information to be accepted by the registry. (Note: If you are using the Approach 2 Declarer desktop tool, your workload is significantly reduced; the tool automatically generates the ISCC, timestamp, and thumbnail fields on your behalf).

• iscc: The unique identifier and  content fingerprint generated from your media file.
• name: The title of the content.
• rightsStatement: The official URI of the open license applied to the asset.
• location: A persistent URL linking back to the asset or catalog record on your institution's website.
• timestamp: The exact creation time of the declaration.
• credentials: Your Verifiable Credential and public key information, proving your institutional authority.
• thumbnail: A Base64 encoded preview image to help users visually identify the asset.

Selecting a Rights Statement

To guarantee machine-readability and legal interoperability across the digital commons, your rightsStatement must use the official URI from one of the following widely recognized open licenses. Restrictive licenses (such as NC/ND) are not accepted. We fully support historical license iterations (e.g., version 2.0 or 3.0) and regional "ported" licenses, meaning you do not need to update your existing catalog data to match the latest global versions.

Optional Fields (Recommended for Discoverability)

While the fields below are optional, we highly encourage you to include them. Providing richer descriptive metadata significantly improves the discoverability of your collections.

• description: A brief text description of the content.
• creationDate: The date the original work or asset was created.
• steward: The name of the responsible institution holding the asset.
• attributionString: The specific text that downstream users should display to properly credit your institution.
• pdRationale: (Only used in declarations that include the Public Domain Mark.) A string corresponding to a Wikidata item that explains the legal rationale for why the asset is in the Public Domain. Please refer to the developer documentation for all allowed values.

System Fields (For Updates Only)

Because declarations submitted to CommonsDB are cryptographically signed and immutable, they cannot simply be edited or deleted once accepted. To handle inevitable cataloging errors or changes in copyright status without breaking the historical record, the registry relies on a specialized linkage field.

• supersedes: This field holds the cryptographic Content ID (declarationId / CID) of a previous declaration. You will only use this field when you need to formally correct or update a record that your institution has already submitted to the registry. By including the previous declarationId here, you tell the registry to prioritize your new declaration while safely maintaining the provenance chain. (For a complete, step-by-step guide on how to process these corrections, please refer to Maintaining Your Declarations).

Phase 2: Generating ISCC Codes Locally

Before you can submit a declaration to the registry, your digital asset needs a persistent identifier. The International Standard Content Code (ISCC) serves as this cryptographic anchor. Because the ISCC is generated directly from the media content itself (its visual, audio, or textual "DNA"), it ensures that your rights declaration remains securely bound to a specific media asset even if the file is later renamed, downloaded, or stripped of its original metadata by a third party.

How This Fits Your Pathway

How these codes are generated depends on your chosen infrastructure:

• Approach 1 (Integrated Workflow): Your IT team will implement the libraries  to programmatically generate these codes across your servers.
• Approach 2 (Declarer Application): You simply point the application to your folder; the desktop tool handles the ISCC generation entirely automatically behind the scenes.

However, regardless of which pathway you use, both rely on the same underlying mechanics and require your media files to meet specific formatting standards.

Local Processing and "Fully Parsing" the Media The ISCC (ISO 24138:2024) is always generated on-premises. Your media files never leave your infrastructure or get uploaded to CommonsDB. To create the fingerprint, the local software running on your machine (whether that is your custom server script or the Declarer desktop app) must be able to "fully parse" the file. This means the software does not just look at the file's title or metadata header; it must actually open, analyze, and process the underlying image pixels, audio waves, or text characters.

Supported Media Formats Because of this deep analysis requirement, you must ensure the assets you feed into the system are in one of the following fully supported standard formats:

• Images: JPG/JPEG, PNG, GIF, TIF/TIFF, BMP, PSD, EPS, WEBP, AVIF, HEIC
• Audio: MP3, WAV, OGG, AIF/AIFF, FLAC, OPUS
• Video: MP4, AVI, MOV, MKV, WEBM, MPG/MPEG, WMV, FLV, OGV, 3GP, 3G2, ASF
• Text/Documents: PDF, DOC, DOCX, EPUB, HTML, ODT, RTF, TXT, XML, MD, JSON

Best Practice for Generating ISCCs

Generate ISCC fingerprints using high-quality standard derivatives, such as medium-to-high resolution JPEGs, rather than proprietary, uncompressed RAW camera files. Providing a clean, well-defined asset ensures optimal feature extraction by the ISCC algorithm, significantly improving matching performance across the registry.

Performance Note (For Pathway 1 System Administrators)

Generating the perceptual and cryptographic hashes required for the complete ISCC string can be computationally intensive. IT departments building custom pipelines should provision adequate CPU and RAM resources for processing. For large archival repositories, we recommend running batch generation scripts incrementally or during off-peak server hours. (Note: Pathway 2 users do not need to worry about this, as the Declarer tool is optimized for smaller, manageable batches).

Phase 3: Choosing Your Approach

With your data prepared and your fingerprints (ISCCs) generated, you are ready to construct and submit your declarations. Depending on the infrastructure path you selected earlier, you will execute this phase using either Approach 1 (Integrated Workflow) or Approach 2 (The Declarer Application).

Approach 1: Integrated Workflow (Python SDK)

For institutions managing large-scale or continuous ingestions, the ISCC SDK (Python) is the recommended foundation for building an automated pipeline. This approach allows your IT team to programmatically loop through your local storage directories, generate fingerprints, map them to your database, and push them directly to the CommonsDB Declaration API.

To successfully submit a declaration, your pipeline must programmatically execute the following sequence for every digital asset:

• Assemble: Construct a strictly structured, nested JSON-LD object. This format ensures your rights data is machine-readable and interoperable across the web. You must divide your data into two distinct blocks: publicMetadata (your technical and identity fields) and supplierMetadata (your descriptive rights information).
• Sign: Cryptographically sign the payload using the private key you generated during the onboarding process (see Onboarding). This is the specific key mathematically tied to your Verifiable Credential. Creating this JSON Web Signature (JWS) serves as irrefutable proof that the declaration was authorized exclusively by your institution.
• Timestamp: Append a signature from an external Trusted Time Stamping Authority (TSA). A TSA is an independent cryptographic service (such as FreeTSA, or a commercial provider like DigiCert) that issues secure, RFC 3161-compliant time stamps. This provides an independent, tamper-proof record of exactly when the declaration was made, which is crucial for proving historical provenance and resolving future rights conflicts.
• Post: Transmit the fully assembled and signed payload to the CommonsDB Declaration API endpoint.

Required JSON-LD Payload Structure:

{
  "@context": "[https://schema.commonsdb.org/v1](https://schema.commonsdb.org/v1)",
  "type": "Declaration",
  "declarationMetadata": {
    "publicMetadata": {
      "iscc": "ISCC:KACY-QAQA-6A6A-1B2C-3D4E-5F6G",
      "declarerId": "did:web:erfgoed-delft.nl",
      "timestamp": "2026-03-04T14:30:00Z",
      "version": "1.0",
      "mediatype": "image/jpeg",
      "thumbnail": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB...[truncated for readability]...5CYII=",
      "credentials": [
        {
          "issuer": "did:web:commonsdb.org",
          "issuanceDate": "2026-01-15T00:00:00Z",
          "credentialSubject": {
            "id": "did:web:erfgoed-delft.nl"
          },
          "proof": {
            "type": "Ed25519Signature2020",
            "created": "2026-01-15T00:00:00Z",
            "jws": "eyJhbG..."
          }
        }
      ]
    },
    "supplierMetadata": {
      "rightsStatement": "[http://creativecommons.org/publicdomain/mark/1.0/](http://creativecommons.org/publicdomain/mark/1.0/)",
      "location": "[https://erfgoed-delft.nl/collections/maps/item-1024](https://erfgoed-delft.nl/collections/maps/item-1024)",
      "name": "*Historical Map of Delft*",
      "creator": "Willem Janszoon Blaeu",
      "attributionString": "Delft Municipal Archive, Netherlands",
      "description": "A 17th-century hand-colored engraving depicting the city of Delft."
    }
  }
}

Verifying Your Submission

Congratulations – once your automated pipeline successfully transmits the payload and receives a confirmation from the API, you have officially made your first declaration to the CommonsDB!

To ensure your ingestion pipeline is functioning correctly, you should actively verify your initial submissions:

View in the Explorer: You do not have to rely solely on backend logs. You can visually verify that your declaration was processed by pasting the generated ISCC fingerprint or the new declarationId directly into the public CommonsDB Explorer. Your asset's metadata, verified rights statement, and the thumbnail preview you generated will be immediately visible and discoverable to the public.

Check the API Response: Ensure your system is configured to log the HTTP success responses (e.g., 200 OK) returned by the CommonsDB API. This response will contain the unique cryptographic declarationId (CID) permanently assigned to your new record.

Subsequent Declarations

Now that your API integration is tested and verified, your pipeline is ready for scale. You can process subsequent declarations in continuous automated batches as your digitized collections grow, or trigger updates dynamically whenever a rights status is updated in your internal catalog.

Approach 2: Using the Declarer Application

CommonsDB Declarer is a standalone, Dockerized application designed for registering digital assets on the CommonsDB Registry. It eliminates the need to write custom ingestion scripts or integrate APIs. Behind a simple visual interface, the tool automates the entire pipeline: extracting local ISCC codes, appending cryptographic timestamps, signing payloads, and handling the API submission.

1. Technical Prerequisites

Before launching the tool, your representative must ensure the following are ready:

• Docker Desktop: Docker must be installed and actively running in the background. (Mac users: launch from Applications; Windows users: launch Docker Desktop from the Start menu. If running on an Apple Silicon M1/M2/M3 Mac, the application automatically handles the required Linux binaries setup.)
• Onboarding Credentials: Have your private key from the CreatorCredentials.app ready, and your API Bearer Token.

2. Preparing Your Data Directory

The Declarer relies on a strict, predictable local folder layout to process your data batches. When you download the Declarer package, it includes a data/ directory that comes with a preformatted metadata.csv template. All of your working files must be organized directly within this specific folder.

Here is how your local environment should look:

Plaintext

commonsdb-declarer/
├── data/                     <-- All your work happens in this folder
│   ├── metadata.csv          <-- Your catalog data sheet
│   ├── image_001.jpg         <-- Local asset file
│   └── image_002.png         <-- Local asset file

• Drop Your Assets: Place all the digital files you wish to declare in this batch directly into the data/ folder.
• Fill Out the Metadata Template: Open the provided metadata.csv file. You will see it already contains the exact column headers required by the registry (such as title, source_url, rightsStatement, and creator), along with a few example rows (such as the Jousting Armor example). Delete the example data rows and replace them with your own catalog information.
• Filenames: Pay special attention to the filename column. The text you enter here (e.g., image_001.jpg) must perfectly match the exact name of the digital file sitting next to it in the folder. This is how the software knows which rights belong to which image.

3. Building and Running the Tool

To launch the app container interface, open your terminal (or command prompt), navigate into your commonsdb-declarer/ folder, and execute these two commands:

Step A: Build the local application image

Bash

docker build -t commons-declarer .

Step B: Run the container and mount your data folder

Bash

docker run -p 8501:8501 -v "$(pwd)/data":/app/data commons-declarer

4. Processing and Submitting Your Batch

Once the terminal displays a message indicating the container is successfully active, open your web browser and navigate to the application's graphical control dashboard:

➡️ http://localhost:8501

Inside the interactive web interface, step through the workspace:

1. Load Credentials: Paste your private key and API Bearer Token into the configuration panel. This links the tool to your institutional identity.
2. Verify Batch Data: The tool automatically scans your mounted directory, parses your updated metadata.csv file, and uses the filename column to pair each row with your actual local media assets. It computes the unique ISCC fingerprint completely on-premises (your master files never leave your system) and extracts a Base64 thumbnail preview. (Note: Base64 is simply a technical standard that converts a small, low-resolution visual preview of your image into a long string of text characters, allowing it to be securely transmitted and stored inside the registry database).
3. Sign and Publish: Review the loaded grid for any mapping errors. When ready, click Sign and Publish. The application calls your local key to sign the objects, attaches a Trusted Time Stamping Authority signature, and transmits the verified payload batch to the CommonsDB Registry.

5. Tracking Your Results (Outputs)

Once your batch successfully registers, the container automatically saves two new files back into your local data/ folder for your internal records:

• metadata_DECLARED.csv: A copy of your original metadata sheet, but with the new declarationId (the cryptographic Content ID / CID), the computed iscc code, and the official registry declaration_timestamp appended to each row. This may be used to sync records back to your internal CMS.
• MASTER_LEDGER.csv: A continuous, running log. Every time you process a new batch of declarations, the app automatically appends the results to the bottom of this master sheet, giving your institution one unified local history of all submissions.

6. Verifying Your Submission

Congratulations—once the Declarer tool finishes processing and outputs your ledger, you have officially made your declarations to CommonsDB!

You do not have to just take the software's word for it. You can visually verify your success right away:

1. Open your newly updated MASTER_LEDGER.csv.
2. Copy the generated ISCC fingerprint or the new declarationId from any of your processed assets.
3. Paste that identifier directly into the search bar of the CommonsDB Explorer.

Your asset's metadata, your institution's verified rights statement, and the thumbnail preview you generated will be immediately visible and discoverable to the world.

With this visual confirmation, your ingestion workflow is complete. Whether you need to process a dozen more files or scale up to thousands, you now have a repeatable, secure process to ensure your organization's rights information remains permanently anchored in the digital commons.