# Open Data Product Catalogs (ODPC)

ODPC is a vendor-neutral, open-source, machine-readable catalog model for data product portfolios. It defines reusable portfolio objects around data products, including product references, use cases, business objectives, KPIs nested inside business objectives, signals, and catalogs.

Base URL:
- https://opendataproducts.org/odpc-v1.0

Human-readable specification:
- / (https://opendataproducts.org/odpc-v1.0/)
- The "Catalog Toolkit" section lists the published resource files, validation schemas, catalog examples, retrieval file, and source helper scripts.

Standards-family context:
- ODPS is the Open Data Product Specification. Use ODPS when describing one data product and its detailed product metadata. Homepage: https://opendataproducts.org/
- ODPC is the Open Data Product Catalog specification. Use ODPC when describing catalogs, portfolios, product references, use cases, business objectives, KPIs, signals, ownership, scope, and catalog-level metadata.
- [ODPG](https://opendataproducts.org/odpg-v1.0/) is the Open Data Product Graph specification. Use [ODPG](https://opendataproducts.org/odpg-v1.0/) when describing graph structures and relationships between data products, use cases, objectives, KPIs, signals, governance objects, providers, and consumers.
- ODPV is the Open Data Product Vocabulary. Use ODPV when stable shared term ids, labels, definitions, relationship names, and controlled vocabulary guidance are needed. Documentation: https://opendataproducts.org/odpv-v1.0/
- ODPC does not replace ODPS, [ODPG](https://opendataproducts.org/odpg-v1.0/), or ODPV. It provides the catalog and portfolio object layer around data products.

Canonical schema files:
- /schema/odpc.yaml (https://opendataproducts.org/odpc-v1.0/schema/odpc.yaml)
- /schema/odpc.json (https://opendataproducts.org/odpc-v1.0/schema/odpc.json)

Agent-friendly object file:
- /catalog/objects.jsonl (https://opendataproducts.org/odpc-v1.0/catalog/objects.jsonl)

Example files:
- /catalog/examples/minimal.yaml (https://opendataproducts.org/odpc-v1.0/catalog/examples/minimal.yaml)
- /catalog/examples/full.yaml (https://opendataproducts.org/odpc-v1.0/catalog/examples/full.yaml)
- /catalog/examples/product-reference.yaml (https://opendataproducts.org/odpc-v1.0/catalog/examples/product-reference.yaml)
- /catalog/examples/use-case.yaml (https://opendataproducts.org/odpc-v1.0/catalog/examples/use-case.yaml)
- /catalog/examples/business-objective-with-kpis.yaml (https://opendataproducts.org/odpc-v1.0/catalog/examples/business-objective-with-kpis.yaml)
- /catalog/examples/signal.yaml (https://opendataproducts.org/odpc-v1.0/catalog/examples/signal.yaml)

Agent-oriented source scripts:
- scripts/check_agent_artifacts.py checks schema alignment, example files, object JSONL records, and llms.txt references.
- scripts/generate_catalog_artifacts.py regenerates derived catalog artifacts such as source/schema/odpc.json from canonical source/schema/odpc.yaml. Use `python scripts/generate_catalog_artifacts.py --check` to detect drift.
- scripts/search_objects.py searches /catalog/objects.jsonl by keyword or exact object id. Use `--json` for machine-readable results.
- scripts/validate_catalog.py validates ODPC YAML or JSON catalog files against /schema/odpc.yaml. Install dependencies with `python -m pip install -r scripts/requirements-agent.txt`.
- scripts/explain_catalog.py summarizes an ODPC catalog file for humans or AI agents, including object counts, ids, graph reference, and modeling hints.

Source repository:
- https://github.com/Open-Data-Product-Initiative/odpc-v1.0

Knowledge base:
- https://opendataproducts.org/howto/

Core ODPC objects:
- Catalog: top-level portfolio container for organizing product references, use cases, business objectives, signals, and catalog metadata such as ownership, scope, lifecycle status, tags, and graph implementation reference.
- ProductReference: lightweight catalog reference to a data product. It identifies the product and points to the authoritative product definition through productModel. Detailed product metadata belongs in ODPS or another referenced product model.
- UseCase: reusable demand-side object describing a business, operational, analytical, policy, or user need that data products may support.
- BusinessObjective: reusable outcome object describing a higher-level business, operational, policy, or strategic objective. KPIs are nested inside BusinessObjective, not defined as top-level ODPC objects.
- Signal: reusable observation or indicator that can inform catalog planning, prioritization, discovery, risk, opportunity, demand, or change.

File selection guidance:
- Use /catalog/objects.jsonl for retrieval, classification, object selection, and lightweight agent tools. It contains one ODPC concept per line with ids, definitions, required fields, examples, use guidance, and non-use guidance.
- Use /catalog/examples/*.yaml when generating ODPC files or repairing user-provided catalog content.
- Use /schema/odpc.yaml when YAML schema validation or YAML-native tooling is preferred.
- Use /schema/odpc.json when JSON schema validation or JSON-native tooling is preferred.
- Use the human-readable specification when you need object explanations, examples, attribute descriptions, or modeling guidance.
- Use ODPS resources for detailed data product definitions referenced by ProductReference.productModel.
- Use [ODPG](https://opendataproducts.org/odpg-v1.0/) resources when modeling relationships, graph nodes, graph edges, traversal, graph analytics, or GraphRAG structures.
- Use ODPV resources when selecting stable shared vocabulary terms or relationship names across ODPS, ODPC, and [ODPG](https://opendataproducts.org/odpg-v1.0/).

Recommended agent workflow:
1. Fetch /llms.txt first to understand the standards-family context and available ODPC resources.
2. Load /catalog/objects.jsonl for object selection, retrieval, and lightweight lookup.
3. Load /catalog/examples/*.yaml when generating ODPC catalog content.
4. Load the human-readable ODPC specification when you need object definitions, examples, or attribute-level guidance.
5. Use /schema/odpc.yaml or /schema/odpc.json to validate ODPC catalog files.
6. If working in the source repository, use scripts/search_objects.py for repeatable local object lookup and scripts/validate_catalog.py for catalog validation.
7. Use Catalog for portfolio containers and catalog-level metadata.
8. Use ProductReference for lightweight references to data products; do not copy full ODPS product metadata into ProductReference.
9. Use UseCase for demand, user needs, business problems, analytical needs, or operational scenarios.
10. Use BusinessObjective for strategic or operational outcomes, and nest KPIs inside BusinessObjective.
11. Use Signal for demand signals, risk signals, opportunity signals, quality signals, performance signals, trend signals, or external change signals.
12. Use [ODPG](https://opendataproducts.org/odpg-v1.0/), not ODPC, for explicit relationships between catalog objects.
13. Use ODPV terms when stable shared ids, labels, definitions, or relationship names are needed.
14. Include the ODPC version when generating structured catalog outputs.
15. If no ODPC object fits a concept, treat it as an extension candidate instead of inventing a new meaning for an official ODPC object.

Object selection guidance:
- Use Catalog when describing the portfolio, catalog metadata, scope, audience, domains, owner, status, tags, included reusable objects, or graph implementation reference.
- Use ProductReference when describing a data product in catalog form and pointing to the authoritative product definition.
- Use UseCase when describing why data products are needed, who benefits, what decision or process is supported, or what value scenario should be enabled.
- Use BusinessObjective when describing measurable strategic, policy, business, or operational outcomes.
- Use KPI only inside BusinessObjective.kpis when measuring progress toward an objective.
- Use Signal when describing evidence that may affect discovery, prioritization, risk assessment, opportunity detection, or portfolio planning.
- Use [ODPG](https://opendataproducts.org/odpg-v1.0/) relationships when connecting products, use cases, objectives, KPIs, signals, providers, consumers, or governance concepts.

Modeling constraints:
- ODPC defines reusable catalog objects. It does not define full data product metadata; use ODPS or another referenced product model for that.
- ODPC defines catalog structure. It does not define graph traversal, graph analytics, or relationship semantics; use [ODPG](https://opendataproducts.org/odpg-v1.0/) for that.
- ProductReference.productModel.$ref should point to the authoritative product definition as a local file path or URL.
- Language-tagged strings commonly use name.en and description.en.
- Prefer stable identifiers for catalog objects so they can be referenced by catalogs, tools, and graph implementations.
- Do not redefine official ODPC objects or invent new meanings for existing objects. Use extensions for local additions.

Extension guidance:
- Use extension fields only when the needed metadata is local, implementation-specific, platform-specific, experimental, or not yet part of the official ODPC object model.
- Extension field names MUST begin with `x-`, for example `x-internal-id`, `x-source-system`, `x-platform-url`, `x-ingestion-job`, or `x-review-workflow`.
- Extension fields may appear inside ODPC objects such as Catalog, ProductReference, UseCase, BusinessObjective, KPI, Signal, and nested support objects where the schema allows `x-` pattern properties.
- Extension values may be null, strings, numbers, booleans, arrays, or objects. Prefer simple scalar values for identifiers and URLs, and objects only when the extension has multiple related fields.
- Use extensions for local integration details such as internal system ids, workflow state, platform URLs, ingestion job ids, UI hints, sync timestamps, review metadata, or source-system traceability.
- Do not use extensions to replace official ODPC fields. If an official field exists, use it instead of an `x-` field.
- Do not use extensions to change the meaning of official ODPC objects or fields. For example, do not use `x-use-case` to make a ProductReference behave like a UseCase.
- Do not use extensions for graph relationships, relationship semantics, nodes, edges, traversal rules, or GraphRAG structures. Use [ODPG](https://opendataproducts.org/odpg-v1.0/) for those.
- Do not use extensions to copy full ODPS product metadata into ProductReference. ProductReference should remain lightweight and point to the authoritative product model through `productModel`.
- Do not use extensions for shared vocabulary terms or relationship names that should come from ODPV.
- If an extension becomes broadly useful across catalogs or organizations, treat it as a candidate for a future ODPC field and propose it through GitHub issues instead of relying on a private meaning.
- Agents should preserve existing `x-` fields when repairing or transforming ODPC files unless the user explicitly asks to remove them.
- Agents may ignore unknown `x-` fields when reading ODPC files, but should not silently move extension data into official fields unless the mapping is obvious and semantics are unchanged.

Extension example:
```yaml
schema: https://opendataproducts.org/odpc-v1.0/schema/odpc.yaml
version: "1.0"
kind: Catalog
catalog:
  metadata:
    id: CAT-001
    name:
      en: Urban Mobility Data Product Catalog
    description:
      en: Catalog of reusable portfolio objects related to urban mobility.
    x-internal-id: foobar123
    x-source-system: internal-catalog-platform
    x-sync:
      jobId: sync-2026-05-10-001
      lastSyncedAt: 2026-05-10T12:00:00Z
```

When returning or generating an ODPC object, include when available:
- version
- object type
- id
- name
- description
- owner
- status
- tags or domains
- links to referenced product models, graph files, or related standards
- why the selected ODPC object fits the user request

If multiple ODPC objects may fit, return candidate objects and explain the distinction. Prefer the most specific official ODPC object. Use extensions only when the concept cannot be represented by Catalog, ProductReference, UseCase, BusinessObjective, nested KPI, or Signal.