Skip to content

Schemas

Schemas define reusable data contracts between OpenSPAD plugins.

Current implementation status

The current Administration → Schemas page is a Dummy / placeholder implementation (Dummy 1.0.2).

The UI already presents the schema concept and three initial schema identifiers. Plugins already store input_schema and output_schema. A dedicated Schema CRUD backend is not implemented yet.

Why schemas matter

Without a shared contract, every plugin could invent its own payload structure. OpenSPAD instead separates processing logic from the data contract:

flowchart LR
    IN[Input Schema] --> P[Plugin] --> OUT[Output Schema]

A plugin therefore declares which schema it accepts and which schema it produces.

Current schema identifiers

Pipeline Seed

openspad.pipeline.seed.v1

Initial input to the semantic pipeline.

flowchart LR
    U[Project Use Case] -->|Pipeline Seed| SE[Semantic Enrichment]

Shared Semantic State

openspad.pipeline.shared-schema.v1

This is the current common default used by the plugin backend for both input_schema and output_schema.

flowchart LR
    S1[Shared State] --> IFC[IFC Plugin] --> S2[Enriched State]
    S2 --> BSDD[bSDD Plugin] --> S3[Further Enriched State]

The schema type remains canonical while the content evolves through the pipeline.

IDS Document

ids.document.v1

Intended as the final structured output contract for the Composer.

flowchart LR
    S[Shared Semantic State] --> C[Composer] --> I[IDS Document]

Current Administration UI

The page is available at:

/administration/schemas/

Current elements include:

  • Schemas heading
  • contextual ? Help
  • search-style placeholder
  • the three schema identifiers above
  • explanatory placeholder text
Capability Current status
Schemas administration page Available
Contextual Help Available
Initial schema IDs displayed Available
Plugin input_schema / output_schema Available
Dedicated SchemaDefinition backend Not implemented
Create / edit / delete schema Not implemented
Schema version management Not implemented
Contract validation API Not implemented

Current plugin integration

The plugin model already contains:

input_schema
output_schema

The current common default is:

openspad.pipeline.shared-schema.v1

The Plugins UI displays contracts as:

IN:  <input schema>
OUT: <output schema>

So the schema-reference mechanism exists already, even though the central registry is still a placeholder.

Schema vs. Shared Semantic State

A schema defines structure.

A Shared Semantic State is actual project data conforming to that structure.

flowchart TB
    SCHEMA[Shared Schema v1]
    A[State after Semantic Enrichment]
    B[State after IFC]
    C[State after bSDD]

    SCHEMA -. defines .-> A
    SCHEMA -. defines .-> B
    SCHEMA -. defines .-> C

Different states can contain different accumulated information while still conforming to the same schema.

Example pipeline contract

flowchart LR
    SEED["openspad.pipeline.seed.v1"]
    SE[Semantic Enrichment]
    S1["shared-schema.v1"]
    IFC[IFC]
    S2["shared-schema.v1"]
    BSDD[bSDD]
    S3["shared-schema.v1"]
    COMP[Composer]
    IDS["ids.document.v1"]

    SEED --> SE --> S1 --> IFC --> S2 --> BSDD --> S3 --> COMP --> IDS

Technical implementation today

The current backend route is:

GET /schemas/

It renders:

schemas.html

with:

page_version = "Dummy 1.0.2"

There is currently no schema-specific CRUD API in schemas_page.py.

Target architecture

The intended next step is a central SchemaDefinition registry.

A future schema definition could contain:

SchemaDefinition
├── schema_id
├── name
├── version
├── description
├── status
├── schema_type
├── definition
├── created_at
└── updated_at

This is target architecture, not current implementation.

A logical implementation sequence is:

flowchart TD
    A[SchemaDefinition model]
    B[Registry storage]
    C[CRUD API]
    D[Administration UI]
    E[Plugin schema dropdowns]
    F[Contract validation]
    G[Pipeline compatibility checks]

    A --> B --> C --> D --> E --> F --> G

Versioning principle

Schema identifiers already carry a version suffix such as .v1.

For incompatible structural changes, a new schema version should be introduced rather than silently changing an existing contract.

Example:

openspad.pipeline.shared-schema.v1
openspad.pipeline.shared-schema.v2

The concrete version-management backend is not implemented yet.

Troubleshooting

Why can I not create or edit schemas?

Because the current Schemas page is still a Dummy / placeholder.

Why can a plugin reference a schema that is not centrally registered?

Because plugin schema values exist already, but a central registry does not yet enforce them.

Why do enrichment plugins use the same input and output schema?

Because they are intended to enrich the content of the Shared Semantic State without changing its canonical structural contract.