Open Collections Protocol

1. Why this protocol exists

Many collections are trapped inside custom platforms, local databases, or one-off APIs. That makes long-term access and cross-institution discovery harder than it needs to be.

This protocol lowers that barrier by defining a simple publication surface based on HTTP, URLs, and JSON files that can be hosted almost anywhere.

2. Core protocol and optional capabilities

The protocol is intentionally layered:

• Core protocol: stable URLs, a collection manifest, item detail files, media assets, and DCD discovery.
• Optional capabilities: scalable collection access patterns for very large collections (for example pagination, filtering, and incremental sync).

A collection is valid and publishable using only the core protocol. Optional capabilities are additive, not required.

3. Core model in simple terms

4. Baseline publication model (static-friendly)

Small and medium collections can work well with one manifest file plus linked item and media files.

Example collection manifest (core)

{
  "id": "rotterdam-harbor",
  "title": "Rotterdam Harbor Collection",
  "protocolVersion": "1.0",
  "canonicalUrl": "https://museum-example.org/collections/rotterdam/collection.json",
  "license": "CC BY 4.0",
  "rightsStatement": "https://rightsstatements.org/vocab/InC/1.0/",
  "items": [
    {
      "id": "map-123",
      "title": "Harbor map, 1898",
      "type": "image",
      "thumbnailUrl": "123.thumb.jpg",
      "detailUrl": "123.json",
      "updatedAt": "2025-09-01T12:00:00Z"
    }
  ]
}

Example item record (core)

{
  "id": "map-123",
  "title": "Harbor map, 1898",
  "canonicalUrl": "https://museum-example.org/collections/rotterdam/123.json",
  "date": "1898",
  "license": "CC BY 4.0",
  "attribution": "Museum Example",
  "assets": [
    {
      "role": "full",
      "url": "123.jpg",
      "mimeType": "image/jpeg"
    }
  ],
  "extensions": {
    "ocp:geo": {
      "lat": 51.9244,
      "lon": 4.4777
    }
  }
}

Example host-root structure

/collections.json
/collections/rotterdam/collection.json
/collections/rotterdam/123.json
/collections/rotterdam/123.jpg
/collections/rotterdam/123.thumb.jpg

Use collections.json as the host index, then keep each collection folder flat: collection.json plus the files it references.

5. Item detail files in a flat collection layout

Treat collection.json as a collection index, not a full record store. Keep item summaries lightweight so the manifest stays easy to publish, cache, and synchronize.

In practice, collection.json should carry discovery fields such as item identity, title, type, thumbnail, media URL, update time, and a detailUrl. Put richer descriptive, technical, or domain-specific metadata in the linked item detail file.

A preferred publication pattern is a flat collection directory where collection.json, media files, thumbnails, and item detail JSON files live together. Nested per-item directories are optional and not required by this protocol.

Example flat collection layout

/collection.json
/map-123.jpg
/map-123.thumb.jpg
/map-123.json
/poster-045.tif
/poster-045.json

This same layout supports a sidecar JSON pattern, where each media file has a nearby detail file (e.g., map-123.jpg with map-123.json) and the manifest links to it with detailUrl.

Example manifest item (lightweight summary)

{
  "id": "map-123",
  "title": "Harbor map, 1898",
  "type": "image",
  "thumbnailUrl": "map-123.thumb.jpg",
  "mediaUrl": "map-123.jpg",
  "detailUrl": "map-123.json",
  "updatedAt": "2025-09-01T12:00:00Z"
}

Example item detail file (rich metadata)

{
  "id": "map-123",
  "canonicalUrl": "https://museum-example.org/collections/harbor/map-123.json",
  "title": "Harbor map, 1898",
  "date": "1898",
  "attribution": "Museum Example",
  "license": "CC BY 4.0",
  "rightsStatement": "https://rightsstatements.org/vocab/InC/1.0/",
  "description": "Survey map showing harbor expansion plans.",
  "assets": [
    {
      "role": "full",
      "url": "https://museum-example.org/collections/harbor/map-123.jpg",
      "mimeType": "image/jpeg"
    }
  ],
  "extensions": {
    "ocp:geo": {
      "lat": 51.9244,
      "lon": 4.4777
    }
  }
}

Collections may also reference media or metadata files stored in other collection directories when needed, provided URLs remain stable and item relationships stay clear.

6. Large collections and scalability (optional)

For very large collections, a single manifest that lists every item can become impractical. In those cases, publishers can add Collection Access Capabilities.

These capabilities are optional and do not replace the core model. They provide scalable access patterns while keeping the protocol web-native.

Example manifest with optional capabilities

{
  "id": "rotterdam-harbor",
  "title": "Rotterdam Harbor Collection",
  "protocolVersion": "1.0",
  "capabilities": {
    "pagination": true,
    "filtering": true,
    "incrementalSync": true
  },
  "itemsPageUrl": "https://museum-example.org/collections/rotterdam/entries?page=1",
  "queries": {
    "itemSearchUrlTemplate": "https://museum-example.org/collections/rotterdam/entries{?page,pageSize,type,from,to,updatedAfter}"
  }
}

Example paginated response (optional capability)

{
  "items": [
    {
      "id": "map-123",
      "title": "Harbor map, 1898",
      "type": "image",
      "thumbnailUrl": "123.thumb.jpg",
      "detailUrl": "123.json",
      "updatedAt": "2025-09-01T12:00:00Z"
    }
  ],
  "nextPageUrl": "https://museum-example.org/collections/rotterdam/entries?page=2"
}

See Optional Collection Access Capabilities for guidance.

7. Versioning, identity, extensions, and rights

• Protocol versioning: include a top-level protocolVersion (for example "1.0").
• Schema direction: publish JSON Schema definitions for manifests, item records, and optional capability objects.
• Identity: use canonical URLs as primary public identifiers; local IDs remain useful internal keys.
• Mirrors: mirrors are allowed, but canonical URLs should be explicit so consumers can reconcile duplicates.
• Extensions: prefer namespaced extension objects (for example extensions.ocp:geo) to avoid collisions.
• Rights metadata: include clear rights, license, usage, and attribution fields whenever possible.

8. Domain discovery (DCD)

DCD is a small file at /.well-known/collections.json that declares which collections a domain considers authoritative.

Example domain discovery file

{
  "domain": "museum-example.org",
  "collections": [
    {
      "id": "rotterdam-harbor",
      "title": "Rotterdam Harbor Collection",
      "manifestUrl": "https://cdn.museum-example.org/collections/rotterdam/collection.json",
      "canonicalUrl": "https://museum-example.org/collections/rotterdam/collection.json"
    }
  ]
}

9. Linked collections

A collection can reference other collections for federation and reuse.

Example linked collection entry

{
  "id": "north-sea-maps",
  "title": "North Sea Map Collections",
  "items": [
    {
      "id": "rotterdam-maps",
      "type": "collection",
      "url": "https://museum-a.org/collections/rotterdam/collection.json"
    },
    {
      "id": "antwerp-maps",
      "type": "collection",
      "url": "https://archive-b.be/collections/antwerp/collection.json"
    }
  ]
}

10. Protocol maturity and next steps

The protocol model is conceptually strong and already useful for publication. It is also still maturing.

Likely maturity steps:

• Publish a formal versioned specification.
• Maintain JSON Schema definitions for core and optional structures.
• Stabilize versioning and compatibility guidance.
• Document optional scalability capabilities more deeply across implementations.
• Ship multiple reference implementations (publisher, browser, indexer).

11. Practical next steps

• Publish a collection
• Optional Collection Access Capabilities
• Choose hosting
• Understand tool roles
• Open available tools