Skip to main content

Spec Creator’s Guide

This guide provides practical instructions for extending the Base Product Specification (BPS) into domain-specific descriptors such as Data Product Descriptor Specification (DPDS), AI Product Descriptor Specification (AIPDS), or any future product class.
It is intended for architects, ontologists, and governance leads who are responsible for creating and maintaining new product specifications.

1. Purpose of the Guide​

  • Enable consistency across product specifications.
  • Provide a repeatable methodology for extending BPS.
  • Reduce duplication by reusing common BPS entities.
  • Ensure interoperability between different product classes (Data, AI, Software, Physical).

2. Foundation: What BPS Provides​

BPS defines the core entities and relationships common to all products:

  • Product (abstract identifier of a unit of value)
  • ProductVersion (immutable snapshot in time)
  • Agent (human, collective, non-human, hybrid)
  • Interface (InputPort, OutputPort, ServiceEndpoint)
  • Asset (datasets, models, APIs, components)
  • Contract & PolicyRiskProfile
  • Evaluation, Metric, Provenance
  • ExternalSpec with dct:conformsTo

These are the building blocks that domain-specific specifications extend.

3. Extension Methodology​

Step 1: Identify Domain-Specific Needs​

  • What properties or entities are unique to your domain?
  • Example for AI Products: BiasMetric, TrainingDataset, DriftDetection.

Step 2: Reuse Before You Create​

  • Prefer to reuse BPS entities wherever possible.
  • Example: Use Evaluation + Metric for accuracy instead of inventing a new “PerformanceResult”.

Step 3: Extend via Namespaced Classes​

  • Define new entities in your own namespace.
  • Example: apds:BiasEvaluation extends Evaluation.
  • Example: apds:ExplainabilityReport extends Asset.

Step 4: Define Relationships​

  • Anchor your new entities back to BPS.
  • Example: ProductVersion evaluatedBy BiasEvaluation.
  • Example: ProductVersion conformsTo AIPDS.

Step 5: Provide Validation Shapes​

  • Create SHACL shapes (RDF/graph) or JSON Schema (JSON) to enforce compliance.
  • Example: Require that every AIPDS ProductVersion has at least one BiasEvaluation.

Step 6: Map to External Standards​

  • Align with ISO, NIST, W3C, or industry efforts.
  • Example: Map AIPDS RiskClassification to EU AI Act levels.
  • Example: Map AIPDS BiasMetric to NIST AI RMF.

4. Lifecycle and Governance​

  • All product specifications inherit the ProductVersion lifecycle (Draft → Published → Deprecated → Retired).
  • Extensions may add domain-specific states.
    • Example: AI Products may include Training, Validating, Monitoring.
  • Governance roles should always include: Owner, Publisher, Maintainer, Evaluator, Auditor.

5. Conformance and Compatibility​

  • Declare conformance: ProductVersion dct:conformsTo ExternalSpec.
  • Use semantic versioning:
    • Major (breaking), Minor (additive), Patch (fixes).
  • Encourage Core vs. Extended conformance levels:
    • Core = Product + Version + Agent + Interface.
    • Extended = adds Provenance, Evaluation, Policies, ExternalSpec.

6. Reference Implementation Patterns​

Provide concrete, machine-readable examples:

  • JSON/YAML descriptor examples of Data Product and AI Product.
  • Validation schemas for SHACL/JSON Schema.
  • Sample workflows showing how a product descriptor moves from draft to published.

7. Worked Examples​

  • Data Product (DPDS): dataset + output port + contract.
  • AI Product (AIPDS): model + evaluation (bias/fairness) + monitoring spec.
  • Physical Product: storage appliance + service endpoint + warranty contract.

8. Checklist for New Specification Authors​

Before finalizing a new spec:

  • Have I reused BPS entities wherever possible?
  • Have I clearly named extensions with a namespace?
  • Have I defined validation rules (SHACL/JSON Schema)?
  • Have I mapped to external standards?
  • Have I included lifecycle and governance roles?
  • Have I provided examples and schemas?
  • Have I declared conformance via dct:conformsTo?

9. Conclusion​

The Spec Creator’s Guide ensures that all extensions of the Base Product Specification remain consistent, interoperable, and standards-aligned.
By following these steps, authors can confidently create AIPDS, AIPROD, or future specifications that integrate seamlessly into the broader ecosystem while preserving the integrity of BPS.