# Open Data Product Vocabulary (ODPV)

ODPV is a controlled vocabulary for the OpenDataProducts.org standards family. It defines stable terms, labels, definitions, concept groups, relationship names, and related-term links used across ODPS, ODPC, and ODPG.

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

Human-readable specification:
- / (https://opendataproducts.org/odpv-v1.0/)
- The "Vocabulary Toolkit for Tools and AI Agents" section lists the published resource files, validation schema, and source helper scripts.

Standards-family context:
- ODPS is the Open Data Product Specification. Use ODPS when describing one data product and its product metadata. Homepage: https://opendataproducts.org/
- ODPC is the Open Data Product Catalog specification. Use ODPC when describing catalogs, portfolios, use cases, objectives, KPIs, signals, and related portfolio objects.
- ODPG is the Open Data Product Graph specification. Use ODPG when describing graph structures and relationships between data products, use cases, objectives, KPIs, signals, governance objects, providers, and consumers. Documentation: https://opendataproducts.org/odpg-v1.0/
- ODPV does not replace ODPS, ODPC, or ODPG. It provides stable ids, labels, definitions, and relationship names that those specifications can reference.

Canonical vocabulary files:
- /vocab/odpv.yaml (https://opendataproducts.org/odpv-v1.0/vocab/odpv.yaml)
- /vocab/odpv.json (https://opendataproducts.org/odpv-v1.0/vocab/odpv.json)

Section vocabulary files:
- /vocab/core.yaml (https://opendataproducts.org/odpv-v1.0/vocab/core.yaml)
- /vocab/value.yaml (https://opendataproducts.org/odpv-v1.0/vocab/value.yaml)
- /vocab/governance.yaml (https://opendataproducts.org/odpv-v1.0/vocab/governance.yaml)
- /vocab/relationships.yaml (https://opendataproducts.org/odpv-v1.0/vocab/relationships.yaml)

Agent-friendly vocabulary file:
- /vocab/terms.jsonl (https://opendataproducts.org/odpv-v1.0/vocab/terms.jsonl)

Validation schema:
- /schema/odpv.schema.json (https://opendataproducts.org/odpv-v1.0/schema/odpv.schema.json)

Agent-oriented source scripts:
- scripts/generate_vocab_artifacts.py regenerates derived vocabulary artifacts from canonical source/vocab/odpv.yaml. Use `python3 scripts/generate_vocab_artifacts.py --check` to detect drift.
- scripts/validate_vocab.py validates vocabulary structure, required fields, generated artifacts, JSONL, section files, and relationship guidance.
- scripts/search_vocab.py searches ODPV terms using preferredLabel, alsoKnownAs, definition, examples, and relatedTerms. Use `--json` for machine-readable results.
- scripts/test_vocab_scripts.py verifies the helper scripts.

File selection guidance:
- Use /vocab/terms.jsonl for retrieval, embeddings, search, and lightweight agent tools. It contains one term per line with ids, uris, labels, definitions, aliases, related terms, examples, usedIn values, and relationship domain/range hints where available.
- Use /vocab/odpv.yaml as the canonical source when complete vocabulary structure, section context, schema-compatible metadata, or validation context is required.
- Use /vocab/odpv.json when JSON is easier to consume than YAML.
- Use section YAML files when only one vocabulary area is needed.
- Use /schema/odpv.schema.json to validate ODPV vocabulary files.

Recommended agent workflow:
1. Fetch /llms.txt first to understand the standards-family context and available vocabulary resources.
2. Load /vocab/terms.jsonl for term search, retrieval, embeddings, and lightweight lookup.
3. If working from the source repository, use scripts/search_vocab.py for repeatable local term lookup; use `--json` when another tool or agent will consume the result.
4. Use /vocab/odpv.yaml when full vocabulary structure, section context, schema-compatible metadata, or validation context is needed.
5. Match user language against preferredLabel, alsoKnownAs, definition, examples, and relatedTerms.
6. Check the vocabulary version and include it when generating structured outputs.
7. For graph work, use relationship domain and range fields from relationship terms.
8. Return stable term id and uri, not only human-readable labels.
9. If editing vocabulary files in the source repository, update source/vocab/odpv.yaml first, then run scripts/generate_vocab_artifacts.py and scripts/validate_vocab.py.
10. If no existing term fits, suggest an extension term or propose a new shared term through GitHub issues instead of inventing a new meaning for an official term.

Use ODPV terms by their stable `id` and `uri`. Do not redefine official ODPV terms or invent new meanings for existing terms. If a needed concept is not present, treat it as an extension candidate and use a separate namespace or prefix.

When returning a matched ODPV term, include:
- vocabularyVersion
- section
- id
- uri
- preferredLabel
- definition
- why this term fits
- relatedTerms when useful

If multiple terms may fit, return candidate terms and explain the distinction. Prefer the most specific official ODPV term. Use `relatedTo` only when a more specific relationship term is not available.

Graph relationship guidance:
- Use only official ODPV relationship ids unless using an explicit extension namespace or prefix.
- For graph edges, use relationship terms from /vocab/relationships.yaml or relationship records in /vocab/terms.jsonl.
- Check `domain` for recommended source node types and `range` for recommended target node types.
- ODPV defines relationship names and meanings. ODPG defines graph structures and how relationships are used in graph files.

Suggesting new terms:
- If a useful shared term appears to be missing from ODPV, suggest it through GitHub issues: https://github.com/Open-Data-Product-Initiative/odpv-v1.0/issues
- Include the proposed term id, preferred label, definition, concept group, related terms, and example usage when possible.

When selecting terms:
- Use `DataProduct` for a managed reusable data offering.
- Use `Dataset` for a structured collection of data that may be part of or exposed through a data product.
- Use `DataService` for an API, query endpoint, or delivery service that provides access to data.
- Use Value terms such as `UseCase`, `BusinessObjective`, `KPI`, `Signal`, `Gap`, and `Priority` to connect data products to demand and measurable outcomes.
- Use Governance terms such as `DataQuality`, `SLA`, `License`, `Policy`, `ComplianceRule`, and `AccessCondition` to describe trust, access, obligations, and control.
- Use Relationship terms such as `supports`, `requires`, `contributesTo`, `measures`, `dependsOn`, `governedBy`, `providedBy`, and `consumedBy` when building graph structures.

Prefer the JSONL file for retrieval, embeddings, search, and lightweight agent tools. Prefer the YAML or JSON files when complete vocabulary structure, sections, and schema-compatible metadata are required.