Serialization

This section defines how BPS descriptors (PDS and PROD) can be serialized into machine-readable formats.
Serialization ensures that product descriptors can be exchanged, validated, and integrated across platforms and tools.

1. General Principles

Neutrality:
BPS does not mandate a single format. We provide canonical bindings to maximize interoperability:
- Semantic binding (canonical): RDF/OWL (Turtle or JSON-LD)
- Practical binding: JSON / YAML
- Validation binding: SHACL (for RDF) and JSON Schema (for JSON)

A conformant descriptor MUST be serializable in at least one machine-readable format.

Recommendations:
- PDS (deployment) is best suited to JSON or YAML.
- PROD (semantics) is best suited to RDF/Turtle or JSON-LD.
Rule:
A conformant descriptor MUST be serializable into at least one machine-readable format.

2. Namespaces & Prefixes (illustrative)

Use stable prefixes in RDF/JSON-LD:

@prefix bps: <https://kivanura.org/spec/bps/0.1/> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .
@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
@prefix dcat: <http://www.w3.org/ns/dcat#> .

Minimal vocabulary (illustrative):

bps:Product, bps:ProductVersion
bps:hasPurpose → bps:Purpose (bps:statement)
bps:hasClassification → bps:Classification (bps:scheme, bps:code, bps:label)
(aligns with SKOS: skos:inScheme, skos:notation, skos:prefLabel)
bps:hasCertification → bps:Certification (bps:certBody, bps:certName, bps:certId, bps:validFrom, bps:validTo, bps:evidenceUri)
bps:hasHealth → bps:HealthIndicator (bps:key, bps:value, bps:observedAt)
dct:conformsTo → external spec link (e.g., DPDS, DPROD, AIPDS)

Note: IRIs above are illustrative. Replace with your published BPS namespace IRIs.

3. Minimal Example: Data Product (DPDS/DPROD)

3.1 PDS (JSON)

{
  "productId": "urn:example:dataproduct:transactions",
  "version": "1.2",
  "status": "Published",
  "interfaces": {
    "input": [{ "protocol": "SQL", "format": "ANSI-SQL" }],
    "output": [{ "protocol": "S3", "format": "Parquet" }]
  },
  "health": [
    { "key": "uptime", "value": "99.9%", "observedAt": "2025-09-18T09:00:00Z" },
    { "key": "freshness", "value": "PT12H", "observedAt": "2025-09-18T09:00:00Z" }
  ],
  "conformsTo": "https://dpds.opendatamesh.org/specifications/dpds/1.0.0/"
}

3.2 PROD (Turtle)

@prefix bps: <https://kivanura.org/spec/bps/0.1/> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<urn:example:dataproduct:transactions>
  a bps:Product ;
  dct:title "Customer Transactions Dataset" ;
  dct:description "Captures debit/credit transactions for retail customers." ;
  bps:hasPurpose [
    a bps:Purpose ;
    bps:statement "Regulatory and analytics reporting"
  ] ;
  bps:hasClassification [
    a bps:Classification ;
    bps:scheme <https://tax.example.org/finance> ;
    bps:code "TXN" ;
    bps:label "Customer Transactions"
  ] ;
  dct:conformsTo <https://www.omg.org/technology/rfc/ekgptf-24-09-08.pdf> .

4. URI Best Practices (Guidance for Spec Writers)

Spec writers are responsible for minting and maintaining their own canonical URIs.
URIs SHOULD be:
- Stable (don’t change once published).
- Versioned (e.g., /1.0.0/ rather than /latest/).
- Dereferenceable (a browser should return human-readable and/or machine-readable documentation).

Examples:

DPDS: https://dpds.opendatamesh.org/specifications/dpds/1.0.0/
DPROD: https://www.omg.org/technology/rfc/ekgptf-24-09-08.pdf (until EKGF publishes versioned ontology URIs).
BPS: https://kivanura.org/spec/bps/0.1/

5. AI Product Example (AIPDS/AIPROD)

5.1 AIPDS (YAML)

productId: urn:example:aiproduct:credit-model
version: "3.0"
status: Published
interfaces:
  input:
    - protocol: REST
      format: JSON
  output:
    - protocol: REST
      format: JSON
sla:
  latency: "<100ms"
  availability: "99.9%"
health:
  - key: drift
    value: "low"
    observedAt: "2025-09-18T09:00:00Z"
  - key: throughput
    value: "120rps"
    observedAt: "2025-09-18T09:00:00Z"

5.2 AIPROD (JSON-LD)

{
  "@context": {
    "bps": "https://kivanura.org/spec/bps/0.1/",
    "dct": "http://purl.org/dc/terms/"
  },
  "@id": "urn:example:aiproduct:credit-model",
  "@type": "bps:Product",
  "dct:title": "Credit Scoring Model",
  "dct:description": "Predicts applicant creditworthiness for consumer loans.",
  "bps:hasPurpose": { "bps:statement": "Automated credit risk decision support" },
  "bps:hasClassification": [{
    "bps:scheme": "https://tax.example.org/ai-model-types",
    "bps:code": "CLS-BIN",
    "bps:label": "Binary Classifier"
  }],
  "bps:hasCertification": [{
    "bps:certBody": "Internal AI Review Board",
    "bps:certName": "Fairness Review",
    "bps:certId": "AIRB-2025-113",
    "bps:validFrom": "2025-07-01",
    "bps:validTo": "2026-07-01",
    "bps:evidenceUri": "https://evidence.example.org/AIRB-2025-113.pdf"
  }],
  "dct:conformsTo": "https://example.org/aiprod/1.0.0/"
}

6. Physical Product Example (PHPDS/PHPROD)

6.1 PHPDS (JSON)

{
  "productId": "urn:example:physical:storage-2tb",
  "version": "2.1",
  "status": "Published",
  "interfaces": {
    "input": [{ "protocol": "USB-C", "format": "Power" }],
    "output": [{ "protocol": "USB-C", "format": "Data" }]
  },
  "warranty": "24 months",
  "health": [
    { "key": "mtbf", "value": "30000h", "observedAt": "2025-08-01T00:00:00Z" }
  ]
}

6.2 PHPROD (Turtle)

@prefix bps: <https://kivanura.org/spec/bps/0.1/> .
@prefix dct: <http://purl.org/dc/terms/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<urn:example:physical:storage-2tb>
  a bps:Product ;
  dct:title "External Storage Device 2TB" ;
  dct:description "Consumer electronic device for file storage." ;
  bps:hasPurpose [ a bps:Purpose ; bps:statement "Personal and small-office data storage" ] ;
  bps:hasClassification [
    a bps:Classification ;
    bps:scheme <https://tax.example.org/consumer-electronics> ;
    bps:code "STOR-EXT" ;
    bps:label "External Storage"
  ] ;
  bps:hasCertification [
    a bps:Certification ;
    bps:certBody "TÜV Rheinland" ;
    bps:certName "CE" ;
    bps:certId "CE-2025-7781" ;
    bps:validFrom "2025-01-10"^^xsd:date
  ] .

7. Software Product Example (SWPDS/SWPROD)

7.1 SWPDS (YAML)

productId: urn:example:software:payments-api
version: "2.1"
status: Published
interfaces:
  input:
    - protocol: REST
      format: JSON
      name: /payments/authorize
  output:
    - protocol: REST
      format: JSON
      name: /payments/status
artifacts:
  openapi: https://api.example.org/payments/v2/openapi.yaml
runtime:
  environment: "kubernetes"
  region: "eu-west-2"
health:
  - key: uptime
    value: "99.99%"
    observedAt: "2025-09-18T09:00:00Z"
  - key: errorRate
    value: "0.02%"
    observedAt: "2025-09-18T09:00:00Z"

7.2 SWPROD (Turtle)

@prefix bps: <https://kivanura.org/spec/bps/0.1/> .
@prefix dct: <http://purl.org/dc/terms/> .

<urn:example:software:payments-api>
  a bps:Product ;
  dct:title "Payment Orchestration API" ;
  dct:description "Routes and reconciles payments across multiple gateways." ;
  bps:hasPurpose [ a bps:Purpose ; bps:statement "Enterprise payment routing and settlement" ] ;
  bps:hasClassification [
    a bps:Classification ;
    bps:scheme <https://tax.example.org/software> ;
    bps:code "PAY-ORCH" ;
    bps:label "Payment Orchestration Service"
  ] ;
  dct:conformsTo <https://spec.openapis.org/oas/3.1.0> .

8. Validation Profiles (Informative)

8.1 SHACL (RDF) — Sketch

@prefix sh: <http://www.w3.org/ns/shacl#> .
@prefix bps: <https://kivanura.org/spec/bps/0.1/> .
@prefix dct: <http://purl.org/dc/terms/> .

bps:ProductShape
  a sh:NodeShape ;
  sh:targetClass bps:Product ;
  sh:property [
    sh:path dct:title ;
    sh:datatype xsd:string ;
    sh:minCount 1
  ] ;
  sh:property [
    sh:path bps:hasPurpose ;
    sh:minCount 1
  ] ;
  sh:property [
    sh:path bps:hasClassification ;
    sh:minCount 1 ;
    sh:message "At least one Classification is REQUIRED where a relevant scheme exists."
  ] .

8.2 JSON Schema — Sketch (PDS fragment)

{
  "$id": "https://kivanura.org/spec/bps/0.1/pds.schema.json",
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["productId", "version", "status", "interfaces"],
  "properties": {
    "productId": { "type": "string" },
    "version": { "type": "string" },
    "status": { "enum": ["Draft", "Published", "Deprecated", "Retired"] },
    "interfaces": {
      "type": "object",
      "properties": {
        "input": { "type": "array", "items": { "type": "object" } },
        "output": { "type": "array", "items": { "type": "object" } }
      }
    },
    "health": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["key", "value", "observedAt"],
        "properties": {
          "key": { "type": "string" },
          "value": { "type": ["string", "number"] },
          "observedAt": { "type": "string", "format": "date-time" }
        }
      }
    }
  }
}

9. Authoring Guidance

Purpose/IntendedUse (PROD) should be concise and unambiguous.
Classification (PROD) should use an agreed taxonomy; include scheme IRI, code, and label.
Certification (PROD) should include issuer, ID, validity, and evidenceUri where possible.
HealthIndicator (PDS) should include meaningful SLIs (e.g., uptime, freshness, drift, MTBF) with timestamps.

10. Notes on Alignment

Classification aligns with SKOS (skos:Concept, skos:inScheme, skos:notation, skos:prefLabel) and DCAT themes.
Provenance should re-use PROV-O (prov:wasGeneratedBy, prov:wasDerivedFrom) when modeling history.
ExternalSpec references should use dct:conformsTo to declare conformance to domain specs (e.g., DPDS, DPROD, AIPDS).

11. Extensibility

Domain profiles (e.g., AIPDS/AIPROD, DPDS/DPROD) MAY add fields and constraints, provided they do not override BPS core terms.
Provide mappings back to BPS terms to ensure cross-domain interoperability.

1. General Principles​

2. Namespaces & Prefixes (illustrative)​

3. Minimal Example: Data Product (DPDS/DPROD)​

3.1 PDS (JSON)​

3.2 PROD (Turtle)​

4. URI Best Practices (Guidance for Spec Writers)​

5. AI Product Example (AIPDS/AIPROD)​

5.1 AIPDS (YAML)​

5.2 AIPROD (JSON-LD)​

6. Physical Product Example (PHPDS/PHPROD)​

6.1 PHPDS (JSON)​

6.2 PHPROD (Turtle)​

7. Software Product Example (SWPDS/SWPROD)​

7.1 SWPDS (YAML)​

7.2 SWPROD (Turtle)​

8. Validation Profiles (Informative)​

8.1 SHACL (RDF) — Sketch​

8.2 JSON Schema — Sketch (PDS fragment)​

9. Authoring Guidance​

10. Notes on Alignment​

11. Extensibility​