Skip to main content

Spec Writers Workflow

This guide provides a step-by-step operational process for authors who wish to create domain-specific product descriptor specifications (PDS/PROD) using the Base Product Specification (BPS) as a foundation.
It is intended for spec writers, standards bodies, and enterprise architects.

1. Identify the Product Domain​

The first step is to define the domain of applicability.
Examples include:

  • Data Products
  • AI Products
  • Software Products
  • Physical Products (devices, appliances, manufactured goods)

Clearly articulate scope and boundaries (e.g., “This specification covers tabular datasets, but not real-time data streams”).

2. Map Domain Concepts to the BPS Meta-Model​

BPS provides core entities such as Product, ProductVersion, Interface, Agent, Asset, Contract, Evaluation, and Provenance.

For each entity:

  • Retain entities that map directly to your domain.
  • Specialize entities that require domain-specific meaning.
    • e.g., in AI, Evaluation → bias testing, drift detection.
  • Extend entities where additional attributes are needed.
    • e.g., in Physical Products, Asset → safety certificate, material composition.

Output: A mapping table from BPS → Domain concepts.

3. Split into PDS and PROD​

Every domain MUST define both a PDS and a PROD:

  • PDS (Deployment Blueprint):
    Specifies how the product is deployed, operated, or delivered.
    Examples:

    • Data: ingestion pipelines, query endpoints.
    • AI: training pipelines, serving endpoints, monitoring hooks.
    • Software: manifests, runtime dependencies, scaling policies.
    • Physical: manufacturing processes, distribution logistics, warranty coverage.

  • PROD (Semantic Blueprint):
    Specifies what the product is, its meaning, role, and constraints.
    Examples:

    • Data: schema, semantics, usage policies, lineage.
    • AI: purpose, ethical profile, risk class, interpretability.
    • Software: functional role, APIs, compliance certifications.
    • Physical: product class, certifications, compliance standards.

4. Define Domain-Specific Extensions​

Extend BPS entities to capture mandatory and optional domain-specific properties.

  • Mandatory attributes: critical for interoperability and governance.
  • Optional attributes: enrich the description without breaking compliance.
  • External standards alignment: ISO, IEEE, W3C, NIST, or industry regulations should be referenced whenever possible.

5. Establish Conformance Rules​

All domain-specific specifications MUST define clear conformance criteria, using RFC 2119 terminology:

  • MUST for required behavior.
  • SHOULD for recommended practices.
  • MAY for optional features.

Examples:

  • “An AI Product Descriptor MUST include a declared risk class aligned with the EU AI Act.”
  • “A Data Product Descriptor SHOULD provide lineage metadata if available.”

6. Provide Examples and Templates​

Each domain specification SHOULD include canonical examples, preferably in multiple serializations (JSON, YAML, RDF).

  • Show a minimal working example.
  • Show an enriched descriptor with optional attributes.
  • Include at least one end-to-end product profile (PDS + PROD together).

7. Governance and Publication​

Define a governance model for maintaining the specification:

  • Versioning: How new versions are released.
  • Deprecation: How old versions are retired.
  • Publication: Where descriptors are stored (e.g., GitHub, registries, internal repositories).
  • Community involvement: Whether the spec is enterprise-specific or open to wider adoption.

✅ Summary​

The workflow for spec writers can be summarized as:

  1. Define domain scope.
  2. Map domain to BPS meta-model.
  3. Split into PDS (deployment) and PROD (semantic).
  4. Add domain-specific extensions.
  5. Define conformance rules.
  6. Provide examples and templates.
  7. Establish governance and publish.

BPS serves as the scaffold, while domain-specific PDS/PROD provide the concrete implementation.